macOS-NSToolBar

NSToolBar

1 简述

工具栏，用于管理窗口标题栏下方和应用程序的自定义内容上方的空间，以快速访问应用程序功能。

2 源码注解

@interface NSToolbar : NSObject

2.1 初始化创建

- (instancetype)initWithIdentifier:(NSToolbarIdentifier)identifier NS_DESIGNATED_INITIALIZER;
- (instancetype)init API_AVAILABLE(macos(10.13));

2.2 代理

@property (nullable, weak) id<NSToolbarDelegate> delegate;

@protocol NSToolbarDelegate <NSObject>

@optional
- (nullable NSToolbarItem *)toolbar:(NSToolbar *)toolbar itemForItemIdentifier:(NSToolbarItemIdentifier)itemIdentifier willBeInsertedIntoToolbar:(BOOL)flag;
// 返回默认情况下在工具栏中显示的项目的有序列表。
- (NSArray<NSToolbarItemIdentifier> *)toolbarDefaultItemIdentifiers:(NSToolbar *)toolbar;
// 按标识符返回所有允许项的列表。
- (NSArray<NSToolbarItemIdentifier> *)toolbarAllowedItemIdentifiers:(NSToolbar *)toolbar;

@optional

- (NSArray<NSToolbarItemIdentifier> *)toolbarSelectableItemIdentifiers:(NSToolbar *)toolbar;

- (void)toolbarWillAddItem:(NSNotification *)notification;

- (void)toolbarDidRemoveItem:(NSNotification *)notification;

2.3 属性

// 接收者的标识符
@property (readonly, copy) NSToolbarIdentifier identifier;
// 工具类显示模式
@property NSToolbarDisplayMode displayMode;
typedef NS_ENUM(NSUInteger, NSToolbarDisplayMode) {
    NSToolbarDisplayModeDefault,
    NSToolbarDisplayModeIconAndLabel,
    NSToolbarDisplayModeIconOnly,
    NSToolbarDisplayModeLabelOnly
} API_AVAILABLE(ios(13.0));
// 是否显示工具栏和主窗口内容之间的分割线
@property BOOL showsBaselineSeparator;
// 是否允许用户修改工具栏
@property BOOL allowsUserCustomization;
// 是否为拓展添加item
@property BOOL allowsExtensionItems API_AVAILABLE(macos(10.10)) API_UNAVAILABLE(ios);
// item数组
@property (readonly, copy) NSArray<__kindof NSToolbarItem *> *items;
// 可见的item数组
@property (nullable, readonly, copy) NSArray<__kindof NSToolbarItem *> *visibleItems;
// 尺寸模式
@property NSToolbarSizeMode sizeMode API_UNAVAILABLE(ios);
typedef NS_ENUM(NSUInteger, NSToolbarSizeMode) {
    NSToolbarSizeModeDefault,
    NSToolbarSizeModeRegular,
    NSToolbarSizeModeSmall
};

2.4 管理item

// 添加指定的item到索引处
- (void)insertItemWithItemIdentifier:(NSToolbarItemIdentifier)itemIdentifier atIndex:(NSInteger)index;
// 删除item
- (void)removeItemAtIndex:(NSInteger)index;

3 重点解析

3.1 sizeMode

设置工具栏图标大小

• NSToolbarSizeModeDefault // 默认大小
• NSToolbarSizeModeRegular // 常规尺寸 32*32像素
• NSToolbarSizeModeSmall // 小尺寸24*24像素

[toolBar setSizeMode:NSToolbarSizeModeSmall];

NSToolbar *toolBar = [[NSToolbar alloc] initWithIdentifier:@"toolBar"];
    [self.view.window setToolbar:toolBar];
    switch (toolBar.sizeMode) {
        case NSToolbarSizeModeDefault:
            
            break;
        case NSToolbarSizeModeRegular:
            
            break;
        case NSToolbarSizeModeSmall:
            
            break;
            
        default:
            break;
    }

3.2 displayMode

设置工具栏显示模式

• NSToolbarDisplayModeDefault // 默认
• NSToolbarDisplayModeIconAndLabel // 显示图标和标签
• NSToolbarDisplayModeIconOnly // 只显示图标
• NSToolbarDisplayModeLabelOnly // 只显示标签

[toolBar setDisplayMode:NSToolbarDisplayModeIconOnly];

4 示例

4.1 代码

1. 创建继承NSWindowController的窗口控制器FSWindowCtl，并在Main.storyboard中修改为FSWindowCtl，如下图

   

2. 在FSWindowCtl添加item标识符

   static NSToolbarItemIdentifier leftIdentifier = @"left";
   static NSToolbarItemIdentifier rightIdentifier = @"right";

3. windowDidLoad中添加并设置NSToolBar

   - (void)windowDidLoad {
       [super windowDidLoad];
       
       NSToolbar *toolbar = [[NSToolbar alloc] initWithIdentifier:@"toolbar"];
       [toolbar setSizeMode:NSToolbarSizeModeDefault];
       toolbar.allowsUserCustomization = YES;
       toolbar.autosavesConfiguration = YES;
       toolbar.displayMode = NSToolbarDisplayModeIconAndLabel;
       toolbar.delegate = self;
       [self.window setToolbar:toolbar];
   }

4. 实现toolbar的代理方法

   	#pragma mark - NSToolbarDelegate
   - (NSToolbarItem *)toolbar:(NSToolbar *)toolbar itemForItemIdentifier:(NSToolbarItemIdentifier)itemIdentifier willBeInsertedIntoToolbar:(BOOL)flag {
       NSToolbarItem *toolbarItem = [[NSToolbarItem alloc] init];
       if ([itemIdentifier isEqualToString:leftIdentifier]) {
           toolbarItem = [self setToolbarItem:@"left"
                                        label:@"left"
                                 paletteLable:@"left"
                                      toolTip:@"left tip"
                                        image:@"left"];
       } else if ([itemIdentifier isEqualToString:rightIdentifier]) {
           toolbarItem = [self setToolbarItem:@"right"
                                        label:@"right"
                                 paletteLable:@"right"
                                      toolTip:@"right tip"
                                        image:@"right"];
       } else {
           return nil;
       }
       return toolbarItem;
   }
   
   - (NSToolbarItem *)setToolbarItem:(NSString *)identifier
                               label:(NSString *)label
                        paletteLable:(NSString *)paletteLable
                             toolTip:(NSString *)toolTip
                               image:(NSString *)image {
       NSToolbarItem *toolbarItem = [[NSToolbarItem alloc] initWithItemIdentifier:identifier];
       toolbarItem.label = label;
       toolbarItem.paletteLabel = paletteLable;
       toolbarItem.toolTip = toolTip;
       toolbarItem.target = self;
       [toolbarItem setAction:@selector(itemClick:)];
       toolbarItem.image = [NSImage imageNamed:image];
       return toolbarItem;
   }
   
   - (NSArray<NSToolbarItemIdentifier> *)toolbarDefaultItemIdentifiers:(NSToolbar *)toolbar {
       return @[NSToolbarSpaceItemIdentifier,
                leftIdentifier,
                rightIdentifier,
                NSToolbarSpaceItemIdentifier,
                NSToolbarShowColorsItemIdentifier];
   }
   
   - (NSArray<NSToolbarItemIdentifier> *)toolbarAllowedItemIdentifiers:(NSToolbar *)toolbar {
       return @[leftIdentifier,
                rightIdentifier,
                NSToolbarShowColorsItemIdentifier,
                NSToolbarSpaceItemIdentifier];
   }
   
   #pragma mark - Action
   - (void)itemClick:(NSToolbarItem *)item {
       
   }

4.2 storyboard

直接在storyboard拖拽NSToolbarItem，并添加即可，不再详述。

5 自定义NSToolbarItem

toolbarItem.view = 自定义的View 
// 使用setView：如果您希望工具栏项使用标准以外的内容。请注意，默认情况下，许多set/get方法将通过转发到您设置的视图的调用来实现，如果视图响应它。另外，您的视图必须是可归档的（为了让工具栏复制您的项目并将其交给配置调色板）。

---

FSToolbarDemo