NSChangeSpelling

Adopted by:	NSText
Declared In:	AppKit/NSSpellProtocol.h

Protocol Description

An object in the responder chain that can correct a misspelled word implements this protocol. See the description of the NSSpellChecker class for more information.

Instance Methods

changeSpelling:

- (void)changeSpelling:(id)sender

Implement to replace the selected word in the receiver with a corrected version from the Spelling panel. This message is sent by the NSSpellChecker instance to the object whose text is being checked. To get the corrected spelling, the receiver asks the sender for the string value of its selected cell.

NSColorPickingCustom

Adopted by:	NSColorPicker
Declared In:	AppKit/NSColorPicking.h

Protocol Description

Together with the NSColorPickingDefault protocol, NSColorPickingCustom provides a way to add color pickers--custom user interfaces for color selection--to an application's NSColorPanel. The NSColorPickingDefault protocol provides basic behavior for a color picker. The NSColorPicker class adopts the NSColorPickingDefault protocol. The easiest way to implement a color picker is to create a subclass of NSColorPicker and use it as a base upon which to add the NSColorPickingCustom protocol. See also NSColorPickingDefault, NSColorPicker.

Method Types

Activity	ClassMethod
Getting the Mode	- currentMode - supportsMode:
Gettting the View	- provideNewView:
Setting the Current Color	- setColor:

Instance Methods

currentMode

- (int)currentMode

Returns the color picker's current mode (or submode, if applicable). The returned value should be unique to your color picker. The return value can be one of the following values:

• NSGrayModeColorPanel
• NSRGBModeColorPanel
• NSCMYKModeColorPanel

• NSHSBModeColorPanel
• NSCustomPaletteModeColorPanel
• NSColorListModeColorPanel
• NSWheelModeColorPanel

provideNewView:

- (NSView *)provideNewView:(BOOL)firstRequest

Returns the view containing the color picker's user interface. This message is sent to the color picker whenever the color panel attempts to display it. The argument indicates whether this is the first time the message has been sent; if firstRequest is YES, the method should perform any initialization required (such as lazily loading a nib file), or any custom initialization required for your color picker.

setColor:

- (void)setColor:(NSColor *)aColor

Adjusts the color picker to make aColor the currently selected color. This method is invoked on the current color picker each time NSColorPanel's setColor: method is invoked. If aColor is actually different from the color picker's color (as it would be if, for example, the user dragged a color into the color panel's color well) this method could be used to update the color picker's color to reflect the change. See also setColor: (NSColorPanel).

supportsMode:

- (BOOL)supportsMode:(int)mode

Returns YES if the receiver supports the specified picking mode. This method attempts to restore the user's previously selected mode, and is invoked when the NSColorPanel is first initialized. It is also invoked by NSColorPanel's setMode: to find the color picker that supports a particular mode. See also currentMode for a list of current modes.

NSColorPickingDefault

Adopted by:	NSColorPicker
Declared In:	AppKit/NSColorPicking.h

Protocol Description

The NSColorPickingDefault protocol, together with the NSColorPickingCustom protocol, provides an interface for adding color pickers--custom user interfaces for color selection--to an application's NSColorPanel. The NSColorPickingDefault protocol provides basic behavior for a color picker. The NSColorPickingCustom protocol provides implementation-specific behavior.

The NSColorPicker class implements the NSColorPickingDefault protocol. The simplest way to implement your own color picker is to create a subclass of NSColorPicker, implementing the NSColorPickingCustom protocol in that subclass. However, it's possible to create a subclass of another class, such as NSView, and use it as a base upon which to add the methods of both NSColorPickingDefault and NSColorPickingCustom.

Color Picker Bundles

A class that implements the NSColorPickingDefault and NSColorPickingCustom protocols needs to be compiled and linked in an application's object file. However, your application need not explicitly create an instance of this class. Instead, your application's file package should include a directory named ColorPickers; within this directory you should place a directory MyPickerClass.bundle for each custom color picker your application implements. This bundle should contain all resources required for your color picker: nib files, TIFF files, and so on.

NSColorPanel will allocate and initialize an instance of each class for which a bundle is found in the ColorPickers directory. The class name is assumed to be the bundle directory name minus the .bundle extension.

Color Picker Buttons

NSColorPanel lets the user select a color picker from a matrix of NSButtonCells. This protocol includes methods for providing and manipulating the image that gets displayed on the button. See also NSColorPickingCustom, NSColorPicker, NSColorPanel.

Method Types

Activity	ClassMethod
Initializing a Color Picker	- initWithPickerMask:colorPanel:
Adding Button Images	- insertNewButtonImage:in: - provideNewButtonImage
Setting the Mode	- setMode:
Using Color Lists	- attachColorList: - detachColorList:
Showing Opacity Controls	- alphaControlAddedOrRemoved:
Responding to a Resize View	- viewSizeChanged:

Instance Methods

alphaControlAddedOrRemoved:

- (void)alphaControlAddedOrRemoved:(id)sender

Sent by the color panel when the opacity controls have been hidden or displayed. If the color picker has its own opacity controls, it should hide or display them, depending on whether the sender's showsAlpha method returns NO or YES.

attachColorList:

- (void)attachColorList:(NSColorList *)aColorList

Attaches the given color list to the receiver, if it isn't already displaying the list. You never need to inovke this method; it is invoked automatically by the NSColorPanel when its attachColorList: method is invoked. Since

NSColorPanel's list mode manages NSColorLists, this method need only be implemented by a custom color picker that manages NSColorLists itself. See also detachColorList:.

detachColorList:

- (void)detachColorList:(NSColorList *)aColorList

Removes the given color list from the receiver, unless the receiver isn't displaying the list. You never need to invoke this method; it is invoked automatically by the NSColorPanel when its detachColorList: method is invoked. Since NSColorPanel's list mode manages NSColorLists, this method need only be implemented by a custom color picker that manages NSColorLists itself. See also attachColorList:.

initWithPickerMask:colorPanel:

- (id)initWithPickerMask:(int)mask
    colorPanel:(NSColorPanel *)colorPanel

Initializes the receiver for the specified mask and colorPanel. This method is sent by the NSColorPanel to all implementors of the color picking protocols when the application's color panel is first initialized. If the color picker responds to any of the modes represented in mask, it should perform its initialization (if desired) and return self; otherwise it should do nothing and return nil. However, a custom color picker can instead delay initialization until it receives a provideNewView: message. In order for your color picker to receive this message, it must have a bundle in your application's "ColorPickers" directory (described in the Color Picker Bundles of the Protocol Description above).

mask is determined by the argument to the NSColorPanel method setPickerMask:. If no mask has been set, mask is NSColorPanelAllModesMask. If your color picker supports any additional modes, you should invoke the setPickerMask: method when your application intializes to notify the NSColorPanel class. This method should examine the mask and determine whether it supports any of the modes included there. You may also check the value in mask to enable or disable any subpickers or optional controls implemented by your color picker. Your color picker may also retain colorPanel in an instance variable for future

communication with the color panel. See the Color section of the Application Kit's Types and Constants chapter for more information on color-picker modes and mask.

insertNewButtonImage:in:

- (void)insertNewButtonImage:(NSImage *)newImage
    in:(NSButtonCell *)newButtonCell

Sets newImage as newButtonCell's image. newButtonCell is the NSButtonCell object that lets the user choose the picker from the color panel. This method should perform application-specific manipulation of the image before it's inserted and displayed by the button cell. See also provideNewButtonImage.

provideNewButtonImage

- (NSImage *)provideNewButtonImage

Returns the image for the mode button that the user uses to select this picker in the color panel. This is the same image that the color panel uses as an argument when sending the insertNewButtonImage:in: message.

setMode:

- (void)setMode:(int)mode

Sets the color picker's mode. This method is invoked by NSColorPanel's setMode: method to ensure that the color picker reflects the current mode. Most color pickers have only one mode, and thus don't need to do any work in this method. Others, like the standard sliders picker, have multiple modes. The standard mode values are

• NSGrayModeColorPanel
• NSRGBModeColorPanel
• NSCMYKModeColorPanel
• NSHSBModeColorPanel
• NSCustomPaletteModeColorPanel
• NSColorListModeColorPanel
• NSWheelModeColorPanel

viewSizeChanged:

- (void)viewSizeChanged:(id)sender

Sent when the color picker's superview has been resized in a way that might affect the color picker. sender is the NSColorPanel that contains the color picker. Use this method to perform special preparation when resizing the color picker's view.

NSDraggingDestination (Informal Protocol)

Category Of:	NSObject
Declared In:	AppKit/NSDragging.h

Protocol Description

The NSDraggingDestination protocol declares methods that the destination (or recipient) of a dragged image must implement. The destination automatically receives NSDraggingDestination messages as an image enters, moves around inside, and then exits or is released within the destination's boundaries.

---

Note - Within this text the term dragging session means the entire process during which an image is selected, dragged, released, and is absorbed or rejected by the destination. A dragging operation is the action that the destination takes in absorbing the image when it's released. The dragging source is the object that "owns" the image that's being dragged. It's specified as an argument to the dragImage:... message, sent to a NSWindow or NSView, that instigated the dragging session.

---

The Dragged Image

The image that's dragged in an image-dragging session is an NSImage object that represents data that's put on the pasteboard. Although a dragging destination can access the NSImage (through a method described in the NSDraggingInfo protocol), its primary concern is with the pasteboard data that the NSImage represents--the dragging operation that a destination ultimately performs is on the pasteboard data, not on the image itself.

Valid Destinations

Dragging is a visual phenomenon. To be an image-dragging destination, an object must represent a portion of screen real estate; thus, only NSWindows and NSViews can be destinations. Furthermore, you must announce the destination-candidacy of an NSWindow or NSView by sending it a registerForDraggedTypes: message. This method, defined in both classes, registers the pasteboard types that the object will accept. During a dragging session, a candidate destination will only receive NSDraggingDestination messages if the pasteboard types for which it is registered matches a type that's represented by the image that's being dragged.

Although NSDraggingDestination is declared as a protocol, the NSView and NSWindow subclasses that you create to adopt the protocol need only implement those methods that are pertinent. (The NSView and NSWindow classes provide private implementations for all of the methods.) In addition, an NSWindow or its delegate may implement these methods; the delegate's implementation takes precedent.

The Sender of Destination Messages

Each of the NSDraggingDestination methods sports a single argument: sender, the object that invoked the method. Within its implementations of the NSDraggingDestination methods, the destination can send NSDraggingInfo messages to sender to get more information on the current dragging session.

The Order of Destination Messages

The six NSDraggingDestination methods are invoked in a distinct order:

• As the image is dragged into the destination's boundaries, the destination is sent a draggingEntered: message.
• While the image remains within the destination, a series of draggingUpdated: messages are sent.
• If the image is dragged out of the destination, draggingExited: is sent and the sequence of NSDraggingDestination messages stops. If it re-enters, the sequence begins again (with a new draggingEntered: message).

• When the image is released, it either slides back to its source (and breaks the sequence) or a prepareForDragOperation: message is sent to the destination, depending on the value that was returned by the most recent invocation of draggingEntered: or draggingUpdated:.
• If the prepareForDragOperation: message returned YES, a performDragOperation: message is sent.
• Finally, if performDragOperation: returned YES, concludeDragOperation: is sent.

Method Types

Activity	ClassMethod
Before the Image is Released	- draggingEntered: - draggingExited: - draggingUpdated:
After the Image is Released	- concludeDragOperation: - performDragOperation: - prepareForDragOperation:

Instance Methods

concludeDragOperation:

- (void)concludeDragOperation:(id <NSDraggingInfo>)sender

Invoked when the dragging operation is complete (but only if the previous performDragOperation: returned YES). The destination implements this method to perform any tidying up that it needs to do. This is the last message that's sent from sender to the destination during a dragging session. See also prepareForDragOperation:, performDragOperation:.

draggingEntered:

- (unsigned int)draggingEntered:(id <NSDraggingInfo>)sender

Invoked when the dragged image enters the destination. Specifically, the message is sent when the hot spot on the cursor that's dragging the image enters any portion of the destination's bounds rectangle (if it's an NSView) or its frame rectangle (if it's an NSWindow).

This method must return a single value that indicates which dragging operation the destination will perform when the image is released. It should be one of the operations specified in the value returned by sender's draggingSourceOperationMask method (see the NSDragInfo protocol). If none of the operations are appropriate, this method should return NSDragOperationNone (this is the default response if the method isn't implemented by the destination). See the Drag Operation section of the Application Kit's Types and Constants chapter for a list of dragging operation constants. See also draggingExited:, draggingUpdated:.

draggingExited:

- (void)draggingExited:(id <NSDraggingInfo>)sender

Invoked when the dragged image exits the destination (following, inversely, the geometric specification given in the description of draggingEntered:). See also draggingEntered:, draggingUpdated:.

draggingUpdated:

- (unsigned int)draggingUpdated:(id <NSDraggingInfo>)sender

Invoked periodically while the image is over the destination. The messages continue until the image is either released or exits. The return value follows the same rules as that for the draggingEntered: method. The default return value (if this method isn't implemented by the destination) is the value returned by the previous draggingEntered: message.

Only one destination at at time receives a sequence of draggingUpdated: messages. For example, if the cursor is within the bounds of two overlapping NSViews that are both valid destinations, the uppermost NSView receives these messages until the image is either released or exits. See also draggingEntered:, draggingExited:.

performDragOperation:

 - (BOOL)performDragOperation:(id <NSDraggingInfo>)sender

Gives the destination an opportunity to perform the dragging operation. This method is invoked after the released image has been removed from the screen (but only if the previous prepareForDragOperation: message returned YES). The destination should implement this method to do the real work of importing the data represented by the image. If the destination accepts the data, it returns YES, otherwise it returns NO. The default (if the destination doesn't implement the method) is to return NO. See also prepareForDragOperation:, concludeDragOperation:.

prepareForDragOperation:

- (BOOL)prepareForDragOperation:(id <NSDraggingInfo>)sender

Invoked when the image is released (but only if the most recent draggingEntered: or draggingUpdated: message returned an acceptable drag-operation value). This method returns YES if it will perform the drag operation and NO if not. See also performDragOperation:, concludeDragOperation:.

NSDraggingInfo

Adopted by:	No OpenStep classes
Declared In:	AppKit/NSDragging.h

Protocol Description

The NSDraggingInfo protocol declares methods that supply information about a dragging session (see the NSDraggingDestination protocol, an informal protocol of NSObject, for definitions of dragging terms). A view or window first registers dragging types; it may then send NSDraggingInfo protocol messages while dragging occurs to get details about that dragging session.

NSDraggingInfo methods are designed to be invoked from within an object's implementation of the NSDraggingDestination protocol methods. An object that conforms to NSDraggingInfo is passed as the argument to each of the methods defined by NSDraggingDestination; NSDraggingInfo messages

should be sent to this conforming object. The Application Kit supplies an NSDraggingInfo object automatically so that you never need to create a class that implements this protocol.

Method Types

Activity	ClassMethod
Dragging-Session Information	- draggingDestinationWindow - draggingLocation - draggingPasteboard - draggingSequenceNumber - draggingSource - draggingSourceOperationMask
Image Information	- draggedImage - draggedImageLocation
Sliding the Image	- slideDraggedImageTo:

Instance Methods

draggedImage

- (NSImage *)draggedImage

Returns the image object that's being dragged. Don't invoke this method after the user has released the image, and don't release the object that this method returns. See also draggedImageLocation.

draggedImageLocation

- (NSPoint)draggedImageLocation

Returns the current location of the dragged image's origin. The image moves in lockstep with the cursor (the position of which is given by draggingLocation) but may be positioned at some offset. The point that's returned is reckoned in the base coordinate system of the destination object's NSWindow. See also draggedImage.

draggingDestinationWindow

- (NSWindow *)draggingDestinationWindow

Returns the destination's NSWindow. See also draggingLocation,

draggingPasteboard, draggingSequenceNumber, draggingSource,
draggingSourceOperationMask.

draggingLocation

- (NSPoint)draggingLocation

Returns the current location of the cursor's hot spot, reckoned in the base coordinate system of the destination object's NSWindow. See also draggingDestinationWindow.

draggingPasteboard

- (NSPasteboard *)draggingPasteboard

Returns the pasteboard that holds the dragged data. See also draggingDestinationWindow.

draggingSequenceNumber

- (int)draggingSequenceNumber

Returns a number that uniquely identifies the dragging session. See also draggingDestinationWindow.

draggingSource

- (id)draggingSource

Returns the source, or "owner," of the dragged image. Returns nil if the source isn't in the same application as the destination. See also draggingDestinationWindow.

draggingSourceOperationMask

- (unsigned int)draggingSourceOperationMask

Returns the dragging operation mask declared by the dragging source's draggingSourceOperationMaskForLocal: method. The elements in the mask will be one or more of the following:

• NSDragOperationCopy
• NSDragOperationLink
• NSDragOperationGeneric
• NSDragOperationPrivate

If the user is holding down a modifier key during the drag, the value that corresponds to the key (as shown in the table below) is AND 'ed with the source's mask.

Table 2-1

Modifier Key	Value
Control	NSDragOperationLink
Alternate	NSDragOperationCopy
Command	NSDragOperationGeneric

See also draggingSourceOperationMaskForLocal: (NSDraggingSource protocol).

slideDraggedImageTo:

- (void)slideDraggedImageTo:(NSPoint)screenPoint

Slides the image to the given location in the screen coordinate system. This method should only be invoked from within the destination's implementation of prepareForDragOperation:--in other words, after the user has released the image but before it's removed from the screen.

NSDraggingSource (Informal Protocol)

Category Of:	NSObject
Declared In:	AppKit/NSDragging.h

Protocol Description

NSDraggingSource declares methods that can (or must) be implemented by the source object in a dragging session. (See the NSDraggingDestination protocol for definitions of dragging terms.) This dragging source is specified as an argument to the dragImage:... message, sent to an NSWindow or NSView, that instigated the dragging session.

Of the methods declared below, only the draggingSourceOperationMaskForLocal: method must be implemented. The other methods are invoked only if the dragging source implements them. All four methods are invoked automatically during a dragging session--you never send an NSDraggingSource message directly to an object.

Method Types

Activity	ClassMethod
Querying the Source	- draggingSourceOperationMaskForLocal: - ignoreModifierKeysWhileDragging
Informing the Source	- draggedImage:beganAt: - draggedImage:endedAt:deposited:

Instance Methods

draggedImage:beganAt:

- (void)draggedImage:(NSImage *)image beganAt:(NSPoint)screenPoint

Invoked when the dragged image is displayed, but before it starts following the mouse. screenPoint is the origin of the image in screen coordinates.

draggedImage:endedAt:deposited:

- (void)draggedImage:(NSImage *)image endedAt:(NSPoint)screenPoint
    deposited:(BOOL)didDeposit

Invoked after the dragged image has been released and the dragging destination has been given a chance to operate on the data it represents. screenPoint is the location of image's origin when it was released reckoned in screen coordinates. deposited indicates whether the destination accepted the image.

draggingSourceOperationMaskForLocal:

-(unsigned int)draggingSourceOperationMaskForLocal:
    (BOOL)isLocal

Returns a mask giving the operations that can be performed on the dragged image's data. This is the only NSDraggingSource method that must be implemented by the source object. isLocal indicates whether the candidate destination object (the window or view over which the dragged image is poised) is in the same application as the source. This method should return a mask, built by OR'ing together applicable combinations of the following constants:

Drag Operation	Meaning
NSDragOperationNone	No operation possible
NSDragOperationCopy	The data represented by the image can be copied
NSDragOperationLink	The data can be shared
NSDragOperationGeneric	The operation can be defined by the destination
NSDragOperationPrivate	Private source/destination negotiation
NSDragOperationAll	Combines all the above

ignoreModifierKeysWhileDragging

 (BOOL)ignoreModifierKeysWhileDragging

Returns YES if modifier keys should have no effect on the type of operation performed, and returns NO otherwise.

NSIgnoreMisspelledWords

Adopted by:	NSText
Declared In:	AppKit/NSSpellProtocol.h

Protocol Description

Implement this protocol to have the Ignore button in the Spelling panel function properly. The Ignore button allows the user to accept a word that the spelling checker believes is misspelled. In order for this action to update the "ignored words" list for the document being checked, the NSIgnoreMisspelledWords protocol must be implemented.

This protocol is necessary because a list of ignored words is useful only if it pertains to the entire document being checked, but the spelling checker (NSSpellChecker object) does not check the entire document for spelling at once. The spelling checker returns as soon as it finds a misspelled word. Thus, it checks only a subset of the document at any one time. The user usually wants to check the entire document, and so usually several spelling checks are run in succession until no misspelled words are found. This protocol allows the list of ignored words to be maintained per-document, even though the spelling checks are not run per-document.

The NSIgnoreMisspelledWords protocol specifies a method, ignoreSpelling:, which should be implemented like this:

- (void)ignoreSpelling:(id)sender
{
    [[NSSpellChecker sharedSpellChecker]
        ignoreWord:[[sender selectedCell] stringValue]
        inSpellDocumentWithTag:myDocumentTag];
}

The second argument to the NSSpellChecker method ignoreWord:inSpellDocumentWithTag: is a tag that the NSSpellChecker can use to distinguish the documents being checked. (See the discussion of "Matching a List of Ignored Words With the Document It Belongs To" in the description of the NSSpellChecker class.) Once the NSSpellChecker has a way to distinguish the various documents, it can append new ignored words to the appropriate list.

To make the ignored words feature useful, the application must store a document's ignored words list with the document. See the NSSpellChecker class description for more information.

Instance Methods

ignoreSpelling:

- (void)ignoreSpelling:(id)sender

Implement to allow an application to ignore misspelled words on a document-by-document basis. This message is sent by the NSSpellChecker instance to the object whose text is being checked. To inform the NSSpellChecker that a particular spelling should be ignored, the receiver asks the NSSpellChecker for the string value of its selected cell. It then sends the NSSpellChecker an ignoreWord:inSpellDocumentWithTag: message.

NSMenuActionResponder (Informal Protocol)

Category Of:	NSObject
Declared In:	AppKit/NSMenu.h

Protocol Description

This informal protocol allows your application to update the enabled or disabled status of an NSMenuItem. It declares only one method, validateItem:. By default, every time a user event occurs, NSMenu automatically enables and disables each visible menu item based on criteria described later in this specification. Implement validateItem: in cases where you want to override NSMenu's default enabling scheme. This is described in more detail later.

There are two ways that NSMenuItems can be enabled or disabled: Explicitly, by sending the setEnabled: message, or automatically, as described below. NSMenuItems are updated automatically unless you send the message setAutoenablesItems:NO to the NSMenu object. You should never mix the two. That is, never use setEnabled: unless you have disabled the automatic updating.

Automatic Updating of NSMenuItems

Whenever a user event occurs, the NSMenu object updates the status of every visible menu item. To update the status of a menu item, NSMenu tries to find the object that responds to the NSMenuItem's action message. It searches the following objects in the following order until it finds one that responds to the action message.

• The NSMenuItem's target
• The key window's first responder
• The key window's delegate
• The main window's first responder
• The main window's delegate
• The NSApplication object
• The NSApplication's delegate
• The NSMenu's delegate

If none of these objects responds to the action message, the menu item is disabled. If NSMenu finds an object that responds to the action message, it then checks to see if that object responds to the validateItem: message (the method defined in this informal protocol). If validateItem: is not implemented in that object, the menu item is enabled. If it is implemented, the return value of validateItem: indicates whether the menu item should be enabled or disabled.

For example, the NSText object implements the copy: method. If your application has a Copy menu item that sends the copy: action message to the first responder, that menu item is automatically enabled any time an NSText object is the first responder of the key or main window. If you have an object that might become the first responder and that object could allow users to select something that they aren't allowed to copy, you can implement the validateItem: method in that object. validateItem: can return NO if the forbidden items are selected and YES if they aren't. By implementing validateItem:, you can have the Copy menu item disabled even though its target object implements the copy: method. If instead your object never permits copying, then you would simply not implement copy: in that object, and the item would be disabled automatically whenever the object is first responder.

If you send a setEnabled: message to enable or disable a menu item when the automatic updating is turned on, other objects might reverse what you have done after another user event occurs. Using setEnabled:, you can never

be sure that a menu item is enabled or disabled or will remain that way. If your application must use setEnabled:, you must turn off the automatic enabling of menu items (by sending setAutoEnablesItems:NO to NSMenu) in order to get predictable results.

Instance Methods

validateItem:

- (BOOL)validateItem:(id <NSMenuItem>)aItem

Implemented to override the default action of updating an NSMenuItem. Returns YES to enable the NSMenuItem, and returns NO to disable it.

NSMenuItem

Adopted By:	NSMenuCell
Declared In:	AppKit/NSMenuItem.h

Protocol Description

NSMenuItem defines objects that are used as command items in menus. How these items appear depends on the host system's user interface. See the NSMenu class specification for more information on menus.

Methods

action

-(SEL)action

Returns the menu item's action method selector.

hasSubmenu

- (BOOL)hasSubmenu

Returns YES if the menu item has a submenu.

isEnabled

-(BOOL)isEnabled

Returns YES if the menu item is enabled, and NO if not.

keyEquivalent

-(NSString*)keyEquivalent

Returns the receiver's basic keyboard equivalent.

setAction:

-(void)setAction:(SEL)aSelector

Sets the menu item's action method selector to aSelector.

setEnabled:

- (void)setEnabled:(BOOL)flag

Enables the menu item if flag is YES, and disables the menu item if flag is NO.

setKeyEquivalent:

-(void)setKeyEquivalent:(NSString*)aString

Sets the menu item's basic key equivalent to aString.

setTag:

- (void)setTag:(unsigned int)anInt

Sets the menu item's tag to anInt.

setTarget:

- (void)setTarget:(id)anObject

Sets the menu item's target to anObject.

setTitle:

- (void)setTitle:(NSString*)aString

Sets the receiving menu item's title to aString.

tag

-(unsignedint)tag

Returns the menu item's tag.

target

-(id)target

Returns the menu item's target.

title

-(NSString*)title

Returns the menu item's title.

NSNibAwaking (Informal Protocol)

Category Of:	NSObject
Declared In:	AppKit/NSNibLoading.h

Protocol Description

This informal protocol consists of a single method, awakeFromNib. It's implemented to receive a notification message that's sent after objects have been loaded from an Interface Builder archive.

When loadNibFile:owner: or a related method loads an Interface Builder archive into an application, each custom object from the archive is first initialized with an init message (initFrame: if the object is a kind of NSView). Outlets are initialized via any setVariable: methods that are available, where Variable is the name of an instance variable. (These methods

are optional; the Objective C run time system automatically initializes outlets.) Finally, after all the objects are fully initialized, they each receive an awakeFromNib message.

The order in which objects are loaded from the archive is not guaranteed. Therefore, it's possible for a setVariable: message to be sent to an object before its companion objects have been unarchived. For this reason, setVariable: methods should not send messages to other objects in the archive. However, messages to other objects can safely be sent from within awakeFromNib--by this point it's assured that all the objects are unarchived and fully initialized.

Typically, awakeFromNib is implemented for only one object in the archive, the controlling or "owner" object for the other objects that are archived with it. For example, suppose that a nib file contained two views that must be positioned relative to each other at run time. Trying to position them when either one of the views is initialized (in a setVariable: method) might fail, since the other view might not be unarchived and initialized yet. However, it can be done in an awakeFromNib method:

- (void)awakeFromNib
{
    NSRect viewFrame;

    [firstView getFrame:&viewFrame];
    [secondView moveTo:viewFrame.origin.x +
                      someVariable :viewFrame.origin.y];
}

There's no default awakeFromNib method; an awakeFromNib message is only sent if an object implements it. The Application Kit declares a prototype for this method, but doesn't implement it.

Instance Methods

awakeFromNib

- (void)awakeFromNib

Implemented to prepare an object for service after it has been loaded from an Interface Builder archive--a so-called "nib file". An awakeFromNib message is sent to each object loaded from the archive, but only if it can respond to the message, and only after all the objects in the archive have been loaded and

initialized. When an object receives an awakeFromNib message, it's already guaranteed to have all its outlet instance variables set. There is no default awakeFromNib method.

NSServicesRequests (Informal Protocol)

Category Of:	NSObject
Declared In:	AppKit/NSApplication.h

Protocol Description

This informal protocol consists of two methods, writeSelectionToPasteboard:types: and readSelectionFromPasteboard:. The first is implemented to provide data to a remote service, and the second to receive any data the remote service might send back. Both respond to messages that are generated when the user chooses a command from the Services menu.

Instance Methods

readSelectionFromPasteboard:

- (BOOL)readSelectionFromPasteboard:(NSPasteboard *)pboard

Implemented to replace the current selection (that is, the text or objects that are currently selected) with data from pboard. The data would have been placed in the pasteboard by another application in response to a remote message from the Services menu. A readSelectionFromPasteboard: message is sent to the same object that previoustly received a writeSelectionToPasteboard:types: message. There is no default readSelectionFromPasteboard: method.

writeSelectionToPasteboard:types:

- (BOOL)writeSelectionToPasteboard:(NSPasteboard *)pboard
    types:(NSArray *)types

Implemented to write the current selection to pboard. The selection should be written as one or more the the data types listed in types. After writing the data, this method should return YES. If for any reason it can't write the data, it should return NO. A writeSelectionToPasteboards:types: message is sent to the first responder when the user chooses a command from the Services menu, but only if the receiver didn't return nil to a previous validRequestorForSendType:andReturnType: message (NSResponder, NSApplication). After this method writes the data to the pasteboard, a remote message is sent to the application that provides the service that the user requested. If the service provider supplies return data to replace the selection, the first responder will then receive a readSelectionFromPasteboard: message. There is no default version of this method.

NSTableDataSource (Informal Protocol)

Characteristic	Description
Category Of:	NSObject
Declared In:	AppKit/NSTableView.h

Protocol Description

NSTableDataSource declares the methods that an NSTableView uses to access the contents of its data source object. It determines how many rows to display by sending a numberOfRowsInTableView: message, and accesses individual values with the

tableView:objectValueForTableColumn:row: and
tableView:setObjectValue:forTableColumn:row: methods. A data

source must implement the first two methods to work with an NSTableView, but if it doesn't implement the third. The NSTableView simply provides read-only access to its contents.

The NSTableView treats objects provided by its data source as values to be displayed in NSCell objects. If these objects aren't of common value classes such as NSString, NSNumber, and so on you'll need to create a custom NSFormatter to display them. See the NSFormatter class specification for more information.

Suppose that an NSTableView's column identifiers are set up as NSStrings containing the names of attributes for the column, such as *Last Name:, *City:, and so on, and that the data source stores its records as an NSArray, called records, of NSDictionary objects using those names as keys. In such a case, this implementation of tableView:objectValueForTableColumn:row: suffices to retrieve values for the table view:

- (id)tableView:(NSTableView
    objectValueForTableColumn:(NSTableColumn
    row:(int)rowIndex
{
    id theRecord, theValue;

    NSParameterAssert(rowIndex >= 0 && rowIndex < [records count]);
    theRecord = [records objectAtIndex:rowIndex];
    theValue = [theRecord objectForKey:[aTableColumn identifier]];
    return theValue;
}

Here's the corresponding method for setting values:

- (void)tableView:(NSTableView *) tableView
    setObjectValue:anObject
    forTableColumn:(NSTableColumn *) aTableColumn
    row:(int)rowIndex
{
id theRecord;
NSParameterAssert(rowIndex >= 0 && rowIndex < [records count]);
theRecord = [records objectAtIndex:rowIndex];
[theRecord setObject:anObject forKey:[aTableColumn identifier]];
return;
}

Finally, for completeness' sake, numberOfRowsInTableView: simply returns the count of the NSArray:

- (int)numberOfRowsInTableView:(NSTableView *)aTableView
{
    return [records count];
}

In each case, the NSTableView that sends the message is provided as aTableView. A data source object that manages several sets of data can choose the appropriate set based on which NSTableView sends the message.

Instance Methods

numberOfRowsInTableView:

-numberOfRowsInTableView:(NSTableView *)TableView

Returns the number of records managed for aTableView by the data source object. An NSTableView uses this method to determine how many rows it should create and display.

tableView:objectValueForTableColumn:row:

- (id)tableView:(NSTableView *)tableView
    objectValueForTableColumn:(NSTableColumn *)tableColumn
    row:(int)row

Returns an attribute value for the record in aTableView at rowIndex. aTableColumn contains the identifier for the attribute, which you get by using NSTableColumn's identifier method. For example, if aTableColumn stands for the city that an employee lives in and rowIndex specifies the record for an employee who lives in Portland, this method returns an object with a string value of *Portland:. See the category description for an example.

tableView:setObjectValue:forTableColumn:row:

- (void)tableView:(NSTableView *)tableView
    setObjectValue:(id)object
    forTableColumn:(NSTableColumn *)tableColumn
    row:(int)row

Sets an attribute value for the record in aTableView at rowIndex. anObject is the new value, and aTableColumn contains the identifier for the attribute, which you get by using NSTableColumn's identifier method. See the category description for an example.