---

NSStatusItem Class Reference

Overview

The NSStatusItem class represents the individual elements displayed within an NSStatusBar object. Instances are created by the NSStatusBar method statusItemWithLength:, which automatically adds the new status item to the status bar. The appearance and behavior of the status item are then set using the various NSStatusItem methods, such as setTitle: and setAction:.

Tasks

Getting the Item’s Status Bar

• – statusBar

Configuring the Status Item’s Appearance

• – setTitle:
• – title
• – setAttributedTitle:
• – attributedTitle
• – setImage:
• – image
• – setAlternateImage:
• – alternateImage
• – setLength:
• – length
• – setHighlightMode:
• – highlightMode
• – setToolTip:
• – toolTip

Managing the Status Item’s Behavior

• – setEnabled:
• – isEnabled
• – setTarget:
• – target
• – setAction:
• – action
• – setDoubleAction:
• – doubleAction
• – sendActionOn:
• – setMenu:
• – menu
• – popUpStatusItemMenu:

Managing a Custom View

• – setView:
• – view

Drawing a Status Item

• – drawStatusBarBackgroundInRect:withHighlight:

Instance Methods

action

Returns the selector that is sent to the receiver’s target when the user clicks the receiver.

- (SEL)action

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setAction:
• – target

Declared In

NSStatusItem.h

alternateImage

Returns the alternate image that is displayed when a status bar item is highlighted.

- (NSImage *)alternateImage

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – setAlternateImage:
• – image

Declared In

NSStatusItem.h

attributedTitle

Returns the attributed string that is displayed at the receiver’s position in the status bar

- (NSAttributedString *)attributedTitle

Discussion

.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setAttributedTitle:
• – setTitle:
• – title

Declared In

NSStatusItem.h

doubleAction

Returns the selector that is sent to the receiver’s target when the user double-clicks the receiver.

- (SEL)doubleAction

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setDoubleAction:
• – target

Declared In

NSStatusItem.h

drawStatusBarBackgroundInRect:withHighlight:

Draws the menu background pattern for a custom status-bar item in regular or highlight pattern.

- (void)drawStatusBarBackgroundInRect:(NSRect)rect withHighlight:(BOOL)highlight

Parameters

rect

A rectangle defining the area of a custom status-bar item.

highlight

YES to draw the background pattern in the standard highlight pattern, NO to not highlight the pattern..

Discussion

You can use this method to help a custom status-bar item emulate the behavior of a standard item.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – setView:

Declared In

NSStatusItem.h

highlightMode

Returns whether the receiver is highlighted when clicked.

- (BOOL)highlightMode

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setHighlightMode:

Declared In

NSStatusItem.h

image

Returns the image that is displayed at the receiver’s position in the status bar.

- (NSImage *)image

Discussion

Returns nil if an image has not been set.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setImage:
• – alternateImage

Declared In

NSStatusItem.h

isEnabled

Returns whether the receiver is enabled and responding to clicks.

- (BOOL)isEnabled

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setEnabled:

Declared In

NSStatusItem.h

length

Returns the amount of space allocated to the receiver within its status bar.

- (CGFloat)length

Discussion

If the status bar is horizontal, the return value is the width of the status item. Besides a physical length, the return value may be NSSquareStatusItemLength or NSVariableStatusItemLength (see NSStatusBar “Constants”), if the status item size is either determined by the status bar thickness or allowed to vary according to the status item’s true size, respectively.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setLength:
• – statusItemWithLength: (NSStatusBar)

Declared In

NSStatusItem.h

menu

Returns the drop-down menu that is displayed when the receiver is clicked.

- (NSMenu *)menu

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setMenu:

Declared In

NSStatusItem.h

popUpStatusItemMenu:

Displays a menu under a custom status bar item.

- (void)popUpStatusItemMenu:(NSMenu *)menu

Parameters

menu

The NSMenu object to display.

Discussion

You can use this method to cause a popup menu to appear under a custom status bar item when the user clicks the item. Note that the view of the receiver must exist (that is, it must not be nil).

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – setMenu:
• – setView:

Declared In

NSStatusItem.h

sendActionOn:

Sets the conditions on which the receiver sends action messages to its target.

- (NSInteger)sendActionOn:(NSInteger)mask

Parameters

mask

Takes one or more of the following bit masks described in “Constants” section of the NSEvent class reference: NSLeftMouseUpMask, NSLeftMouseDownMask, NSLeftMouseDraggedMask, and NSPeriodicMask. Bitwise-OR multiple bit masks.

Return Value

A bit mask containing the previous settings. This bit mask uses the same values as specified in the mask parameter.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSStatusItem.h

setAction:

Sets the selector that is sent to the receiver’s target when the receiver is clicked.

- (void)setAction:(SEL)action

Discussion

If the receiver has a menu set, action is not sent to the target when the receiver is clicked; instead, the click causes the menu to appear.

See Action Messages for additional information on action messages.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – action
• – setMenu:

Declared In

NSStatusItem.h

setAlternateImage:

Sets an alternate image to be displayed when a status bar item is highlighted.

- (void)setAlternateImage:(NSImage *)image

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – alternateImage
• – setImage:

Declared In

NSStatusItem.h

setAttributedTitle:

Sets the attributed string that is displayed at the receiver’s position in the status bar.

- (void)setAttributedTitle:(NSAttributedString *)title

Discussion

If an image is also set, the title appears to the right of the image.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – attributedTitle
• – setImage:
• – setTitle:

Declared In

NSStatusItem.h

setDoubleAction:

Sets the selector that is sent to the receiver’s target when the receiver is double-clicked.

- (void)setDoubleAction:(SEL)action

Discussion

For the method to have any effect, the receiver’s action and target must be set to the class in which the selector is declared. See Action Messages for additional information on action messages.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – doubleAction

Declared In

NSStatusItem.h

setEnabled:

Sets whether the receiver is enabled to respond to clicks.

- (void)setEnabled:(BOOL)flag

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – isEnabled

Declared In

NSStatusItem.h

setHighlightMode:

Sets whether the receiver is highlighted when it is clicked.

- (void)setHighlightMode:(BOOL)flag

Discussion

The default is NO, which means the receiver isn’t highlighted when it is clicked.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – highlightMode

Declared In

NSStatusItem.h

setImage:

Sets the image that is displayed at the receiver’s position in the status bar to image.

- (void)setImage:(NSImage *)image

Discussion

If a title is also set, the image appears to the left of the title.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – image
• – setAlternateImage:
• – setAttributedTitle:
• – setTitle:

Declared In

NSStatusItem.h

setLength:

Sets the amount of space in the status bar that should be allocated to the receiver.

- (void)setLength:(CGFloat)len

Parameters

len

If the status bar is horizontal, len is the horizontal space to allocate. In addition to a fixed length, len can be NSSquareStatusItemLength or NSVariableStatusItemLength (see “Constants” in the NSStatusBar class reference) to allow the status bar to allocate (and adjust) the space according to either the status bar’s thickness or the status item’s true size.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – length
• – statusItemWithLength: (NSStatusBar)

Declared In

NSStatusItem.h

setMenu:

Sets the pull-down menu that is displayed when the receiver is clicked.

- (void)setMenu:(NSMenu *)menu

Parameters

menu

The NSMenu object to display.

Discussion

When set, the receiver’s single click action behavior is not used. The menu can be removed by setting menu to nil.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – menu
• – setAction:
• – setTarget:
• – popUpStatusItemMenu:

Declared In

NSStatusItem.h

setTarget:

Sets the target object to which the receiver’s action message is sent when the receiver is clicked.

- (void)setTarget:(id)target

Discussion

If the receiver has a menu set, the action is not sent to target when the receiver is clicked; instead, the click causes the menu to appear.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – target
• – setMenu:

Declared In

NSStatusItem.h

setTitle:

Sets the string that is displayed at the receiver’s position in the status bar.

- (void)setTitle:(NSString *)title

Discussion

If an image is also set, the title appears to the right of the image.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – title
• – setAttributedTitle:
• – setImage:

Declared In

NSStatusItem.h

setToolTip:

Sets the tool tip string that is displayed when the cursor pauses over the receiver.

- (void)setToolTip:(NSString *)toolTip

Parameters

toolTip

A string that functions as the title of the status item.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – toolTip

Declared In

NSStatusItem.h

setView:

Sets the custom view that is displayed at the receiver’s position in the status bar.

- (void)setView:(NSView *)view

Parameters

view

The NSView object representing the custom view.

Discussion

Setting a custom view overrides all the other appearance and behavior settings defined by NSStatusItem. The custom view is responsible for drawing itself and providing its own behaviors, such as processing mouse clicks and sending action messages.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – view

Declared In

NSStatusItem.h

statusBar

Returns the status bar in which the receiver is displayed.

- (NSStatusBar *)statusBar

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSStatusItem.h

target

Returns the target to which the receiver’s action message is sent when the user clicks the receiver.

- (id)target

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setTarget:
• – action

Declared In

NSStatusItem.h

title

Returns the string that is displayed at the receiver’s position in the status bar.

- (NSString *)title

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setAttributedTitle:
• – setTitle:

Declared In

NSStatusItem.h

toolTip

Returns the tool tip string that is displayed when the cursor pauses over the receiver.

- (NSString *)toolTip

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setToolTip:

Declared In

NSStatusItem.h

view

Returns the custom view that is displayed at the receiver’s position in the status bar.

- (NSView *)view

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setView:

Declared In

NSStatusItem.h

---