Toolbar Management Checklist
Before you begin coding:
If you have image-based toolbar items, find or create the images (in the proper size and aspect ratio) and add them to your project as a resource.
If you have view-based toolbar items, create each view in Interface Builder, specify an outlet for a custom controller object, and connect the view to the outlet.
If the view is an off-the-shelf palette object, just make an outlet connection.
Specify or (for default toolbar items) identify the unique string identifiers that you intend to use for toolbars and toolbar items.
Add to an application menu (usually named View) the menu items Show Toolbar and Customize Toolbar..., connect these to the First Responder icon in the nib file window, and select the actions
toggleToolbarShown:
andrunToolbarCustomizationPalette:
. (Note thatNSWindow
automatically changes “Show Toolbar” to “Hide Toolbar” as appropriate.)
For further information, see Adding and Removing Toolbar Items.
What happens: The application launches or a document is created or opened, causing a nib file to be loaded and its object unarchived.
A custom controller class in
awakeFromNib
or, for document-based applications, anNSDocument
subclass inwindowControllerDidLoadNib:
completes the following steps for each toolbar it uses:It makes a new
NSToolbar
object usinginitWithIdentifier:
.It sets attributes of the toolbar if the defaults won’t do using
setAllowsUserCustomization:
,setAutosavesConfiguration:
, andsetDisplayMode:
.It sets the toolbar’s delegate (usually itself).
It associates the toolbar with a window by sending the NSWindow object a
setToolbar:
message.
For further information see Adding and Removing Toolbar Items
What happens: The NSToolbar
object begins communicating with its delegate in order to populate the toolbar with toolbar items.
The window gets the allowed and default toolbar item identifiers:
The toolbar object calls the delegate method
toolbarAllowedItemIdentifiers:
to get the total set of possible toolbar items.Unless it finds the default toolbar configuration in user preferences, the toolbar calls the delegate method
toolbarDefaultItemIdentifiers:
to get the default set.To have the default configuration saved to and read from user preferences, the
NSToolbar
object’sautosavesConfiguration
attribute must be set.If certain toolbar items should indicate a selected state, the delegate should implement
toolbarSelectableItemIdentifiers:
to return the identifiers of those toolbar items.
The window asks for each
NSToolbarItem
object (by identifier) to insert into the toolbar.To add each toolbar item to the toolbar, the
NSToolbar
object sendstoolbar:itemForItemIdentifier:willBeInsertedIntoToolbar:
to the delegate.If the
NSToolbarItem
object is image-based, get the image from the application bundle (for example, by using theNSImage
class methodimageNamed:
) and sendsetImage:
to the toolbar item. Also set the toolbar item’s label, palette label, target, and action. You may also set a menu form representation.If the toolbar item is view-based, send
setView:
to the toolbar-item object, passing in the outlet to the view. Also set the toolbar item’s label, palette label, its minimum size (minSize
), and its maximum size (maxSize
). (If you do not set aminSize
andmaxSize
, the view does not appear because it is sized to zero in both dimensions.) You may also set a menu form representation.If the delegate wants to customize a toolbar item before it is added, it can also implement the
toolbarWillAddItem:
notification method.
For further information see Adding and Removing Toolbar Items, Setting a Toolbar Item’s Representation, Setting a Toolbar Item’s Size and Setting a Toolbar Item’s Size.
What happens: Users click toolbar items; the runtime context of the application changes.
Declare and implement action methods for each of your custom toolbar items, usually in a custom controller class.
When you create a toolbar item you can identify the selector of each of these methods through the
setAction:
method ofNSToolbarItem
. Also set the target by calling thesetTarget:
, usually passing inself
.Validate toolbar items.
If the toolbar item is image-based, the target of an action should implement
validateToolbarItem:
if it wants validation more specialized than the default. If the toolbar item is view-based, you should create a subclass ofNSToolbarItem
for the item and override thevalidate
method.
For further information, see Validating Toolbar Items.
What happens: The user chooses the Customize Toolbar menu item.
As the customization sheet opens, the toolbar object calls the delegate methods
toolbarAllowedItemIdentifiers:
andtoolbarDefaultItemIdentifiers:
. Then as the toolbar adds each toolbar item to the customization palette, it sends to the delegate if the item kind is custom image or custom view.When the user adds an item to the toolbar, the toolbar invokes the delegate method
toolbar:itemForItemIdentifier:willBeInsertedIntoToolbar:
; if a new instance of the toolbar item is needed, the toolbar sendstoolbarWillAddItem:
to the delegate just before it adds the item.Just after the user removes an item from the toolbar, the toolbar sends
toolbarDidRemoveItem:
to the delegate.When the user drags the default set to the toolbar, the toolbar reuses as many items already in the toolbar as possible, calling
toolbarDidRemoveItem:
for the items it needs to remove and callingtoolbarWillAddItem:
for the ones it needs to add.
Note that the toolbar does not call any delegate methods when the user closes the customization sheet.
Copyright © 2002, 2009 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2009-02-04