From dc30f9b4d4761d56d57252eba131449c233b16fc Mon Sep 17 00:00:00 2001 From: Vadim Shpakovski Date: Sun, 4 Sep 2016 14:30:22 +0300 Subject: [PATCH] Add nullability attributes in headers --- Framework/MASPreferencesViewController.h | 54 +++++++++-- Framework/MASPreferencesWindowController.h | 103 ++++++++++++++++++--- Framework/MASPreferencesWindowController.m | 12 ++- 3 files changed, 145 insertions(+), 24 deletions(-) diff --git a/Framework/MASPreferencesViewController.h b/Framework/MASPreferencesViewController.h index 8675d71..0ff861e 100644 --- a/Framework/MASPreferencesViewController.h +++ b/Framework/MASPreferencesViewController.h @@ -2,23 +2,61 @@ // Any controller providing preference pane view must support this protocol // -#import +#import +NS_ASSUME_NONNULL_BEGIN + +/*! + * Requirements for the Preferences panel + */ @protocol MASPreferencesViewController +/*! + * Unique identifier of the Panel represented by the view controller. + */ +@property (nonatomic, readonly, nullable) NSString *identifier; + +/*! + * Toolbar icon for the Panel represented by the view controller. + */ +@property (nonatomic, readonly, nullable) NSImage *toolbarItemImage; + +/*! + * Toolbar item label for the Panel represented by the view controller. + * + * This label may be used as a Preferences window title. + */ +@property (nonatomic, readonly, nullable) NSString *toolbarItemLabel; + @optional +/*! + * Called when selection goes to the Panel represented by the view controller. + */ - (void)viewWillAppear; + +/*! + * Called when selection goes to another Panel. + */ - (void)viewDidDisappear; -- (NSView *)initialKeyView; -@property (nonatomic, readonly) BOOL hasResizableWidth; -@property (nonatomic, readonly) BOOL hasResizableHeight; +/*! + * Returns initial control in the key view loop. + * + * @return The view to focus on automatically when the panel is open. + */ +- (__kindof NSView *)initialKeyView; -@required +/*! + * The flag used to detect if the Prerences window can be resized horizontally. + */ +@property (nonatomic, readonly) BOOL hasResizableWidth; -@property (nonatomic, readonly) NSString *identifier; -@property (nonatomic, readonly) NSImage *toolbarItemImage; -@property (nonatomic, readonly) NSString *toolbarItemLabel; +/*! + * The flag used to detect if the Prerences window can be resized vertically. + */ +@property (nonatomic, readonly) BOOL hasResizableHeight; @end + +NS_ASSUME_NONNULL_END diff --git a/Framework/MASPreferencesWindowController.h b/Framework/MASPreferencesWindowController.h index 275f5d1..e5ea47a 100644 --- a/Framework/MASPreferencesWindowController.h +++ b/Framework/MASPreferencesWindowController.h @@ -1,16 +1,25 @@ // // You create an application Preferences window using code like this: -// _preferencesWindowController = [[MASPreferencesWindowController alloc] initWithViewControllers:controllers -// title:title] +// _preferencesWindowController = [[MASPreferencesWindowController alloc] initWithViewControllers:controllers title:title] // // To open the Preferences window: // [_preferencesWindowController showWindow:sender] // -#import "MASPreferencesViewController.h" +#import -extern NSString *const kMASPreferencesWindowControllerDidChangeViewNotification; +@protocol MASPreferencesViewController; +NS_ASSUME_NONNULL_BEGIN + +/*! + * Notification posted when you switch selected panel in Preferences. + */ +extern NSString * const kMASPreferencesWindowControllerDidChangeViewNotification; + +/*! + * Window controller for managing Preference view controllers. + */ __attribute__((__visibility__("default"))) #if MAC_OS_X_VERSION_MAX_ALLOWED > MAC_OS_X_VERSION_10_5 @interface MASPreferencesWindowController : NSWindowController @@ -26,20 +35,90 @@ __attribute__((__visibility__("default"))) NSToolbar * __unsafe_unretained _toolbar; } +/*! + * Child view controllers in the Preferences window. + */ @property (nonatomic, readonly) NSMutableArray *viewControllers; + +/*! + * Index of selected panel in the Preferences window. + */ @property (nonatomic, readonly) NSUInteger indexOfSelectedController; -@property (nonatomic, readonly, retain) NSViewController *selectedViewController; -@property (nonatomic, readonly) NSString *title; -@property (nonatomic, assign) IBOutlet NSToolbar *toolbar; -- (id)initWithViewControllers:(NSArray *)viewControllers; -- (id)initWithViewControllers:(NSArray *)viewControllers title:(NSString *)title; -- (void)addViewController:(NSViewController *) viewController; +/*! + * View controller representing selected panel in the Preferences window. + */ +@property (nonatomic, readonly) NSViewController *selectedViewController; + +/*! + * Optional window title provided in the initializer. + */ +@property (nonatomic, copy, readonly, nullable) NSString *title; + +/*! + * The toolbar managed by the Preferences window. + */ +@property (nonatomic, unsafe_unretained) IBOutlet NSToolbar *toolbar; + +/*! + * Creates new a window controller for Preferences with custom title. + * + * @param viewControllers Non-empty list of view controllers representing Preference panels. + * @param title Optional title for the Preferneces window. Pass `nil` to show the title provided by selected view controller. + * + * @return A new controller with the given title. + */ +- (instancetype)initWithViewControllers:(NSArray *)viewControllers title:(NSString * _Nullable)title; +- (instancetype)init __attribute((unavailable("Please use initWithViewControllers:title:"))); +/*! + * Creates new a window controller for Preferences with a flexible title. + * + * @param viewControllers Non-empty list of view controllers representing Preference panels. + * + * @return A new controller with title depending on selected view controller. + */ +- (instancetype)initWithViewControllers:(NSArray *)viewControllers; + +/*! + * Appends new panel to the Preferences window. + * + * @param viewController View controller representing new panel. + */ +- (void)addViewController:(NSViewController *)viewController; + +/*! + * Changes selection in the Preferences toolbar. + * + * @param controllerIndex Position of the new panel to select in the toolbar. + */ - (void)selectControllerAtIndex:(NSUInteger)controllerIndex; + +/*! + * Changes selection in the Preferences toolbar using panel identifier. + * + * @param identifier String identifier of the view controller to select. + */ - (void)selectControllerWithIdentifier:(NSString *)identifier; -- (IBAction)goNextTab:(id)sender; -- (IBAction)goPreviousTab:(id)sender; +/*! + * Useful action for switching to the next panel. + * + * For example, you may connect it to the main menu. + * + * @param sender Menu or toolbar item. + */ +- (IBAction)goNextTab:(id _Nullable)sender; + +/*! + * Useful action for switching to the previous panel. + * + * For example, you may connect it to the main menu. + * + * @param sender Menu or toolbar item. + */ +- (IBAction)goPreviousTab:(id _Nullable)sender; @end + +NS_ASSUME_NONNULL_END diff --git a/Framework/MASPreferencesWindowController.m b/Framework/MASPreferencesWindowController.m index 82cd69d..1106320 100644 --- a/Framework/MASPreferencesWindowController.m +++ b/Framework/MASPreferencesWindowController.m @@ -1,4 +1,5 @@ #import "MASPreferencesWindowController.h" +#import "MASPreferencesViewController.h" NSString *const kMASPreferencesWindowControllerDidChangeViewNotification = @"MASPreferencesWindowControllerDidChangeViewNotification"; @@ -30,13 +31,14 @@ @implementation MASPreferencesWindowController #pragma mark - -- (id)initWithViewControllers:(NSArray *)viewControllers +- (instancetype)initWithViewControllers:(NSArray *)viewControllers { return [self initWithViewControllers:viewControllers title:nil]; } -- (id)initWithViewControllers:(NSArray *)viewControllers title:(NSString *)title +- (instancetype)initWithViewControllers:(NSArray *)viewControllers title:(NSString *)title { + NSParameterAssert(viewControllers.count > 0); NSString *nibPath = [[NSBundle bundleForClass:MASPreferencesWindowController.class] pathForResource:@"MASPreferencesWindow" ofType:@"nib"]; if ((self = [super initWithWindowNibPath:nibPath owner:self])) { @@ -58,8 +60,9 @@ - (void)dealloc self.toolbar.delegate = nil; } -- (void)addViewController: (NSViewController *) viewController +- (void)addViewController:(NSViewController *)viewController { + NSParameterAssert(viewController); [_viewControllers addObject: viewController]; [_toolbar insertItemWithItemIdentifier: [viewController identifier] atIndex: ([_viewControllers count] - 1)]; [_toolbar validateVisibleItems]; @@ -258,7 +261,7 @@ - (void)setSelectedViewController:(NSViewController 0); self.selectedViewController = [self viewControllerForIdentifier:identifier]; }