Mac Developer Library

Developer

AppKit Framework Reference NSStatusItem Class Reference

Options
Deployment Target:

On This Page
Language:

NSStatusItem

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 button property. (For additional guidance, see Menu Bar Extras.)

  • The status bar in which the status item is displayed. (read-only)

    Declaration

    Swift

    unowned(unsafe) var statusBar: NSStatusBar { get }

    Objective-C

    @property(readonly, assign) NSStatusBar *statusBar

    Availability

    Available in OS X v10.0 and later.

  • The button that is displayed in the status bar. (read-only)

    Declaration

    Swift

    var button: NSStatusBarButton? { get }

    Objective-C

    @property(readonly, strong) NSStatusBarButton *button

    Discussion

    This button is created automatically on the creation of the status item. Behavior customization for the button, such as image, target, action, tooltip, and so on can be set with this property.

    Availability

    Available in OS X v10.10 and later.

  • menu menu Property

    The pull-down menu that is displayed when the status item is clicked.

    Declaration

    Swift

    var menu: NSMenu?

    Objective-C

    @property(strong) NSMenu *menu

    Discussion

    When non-nil, the status item’s single click action behavior is not used. The menu can be removed by setting the value of this property to nil.

    Availability

    Available in OS X v10.0 and later.

  • The amount of space in the status bar that should be allocated to the status item.

    Declaration

    Swift

    var length: CGFloat

    Objective-C

    @property CGFloat length

    Discussion

    If the status bar is horizontal, the value of this property is the width of the status item. In addition to a fixed length, this value can be NSSquareStatusItemLength or NSVariableStatusItemLength (see NSStatusBar Constants) 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 OS X v10.0 and later.

  • isEnabled enabled (OS X v10.10) Property

    A Boolean that indicates whether the status item is enabled to respond to clicks.

    Deprecation Statement

    Use the button property.

    Declaration

    Swift

    var enabled: Bool

    Objective-C

    @property(getter=isEnabled) BOOL enabled

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

  • target target (OS X v10.10) Property

    The target object to which the status item’s action message is sent when the status item is clicked.

    Deprecation Statement

    Use the button property.

    Declaration

    Swift

    weak var target: AnyObject?

    Objective-C

    @property(weak) id target

    Discussion

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

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

    See Also

    action

  • action action (OS X v10.10) Property

    The selector that is sent to the status item’s target when the status item is clicked.

    Deprecation Statement

    Use the button property.

    Declaration

    Swift

    var action: Selector

    Objective-C

    @property SEL action

    Discussion

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

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

    See Also

    target

  • doubleAction doubleAction (OS X v10.10) Property

    The selector that is sent to the status item’s target when the status item is double-clicked.

    Deprecation Statement

    Use the button property.

    Declaration

    Swift

    var doubleAction: Selector

    Objective-C

    @property SEL doubleAction

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.10.

  • Sets the conditions on which the status item sends action messages to its target.

    Deprecation Statement

    Use the button property.

    Declaration

    Swift

    func sendActionOn(_ mask: Int) -> Int

    Objective-C

    - (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 OS X v10.0 and later.

    Deprecated in OS X v10.10.

  • Displays a menu under a custom status bar item.

    Deprecation Statement

    Custom views should not be set on a status item. Use the button property instead.

    Declaration

    Swift

    func popUpStatusItemMenu(_ menu: NSMenu)

    Objective-C

    - (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 status item must exist (that is, it must not be nil).

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.10.

  • title title (OS X v10.10) Property

    The string that is displayed at the status item’s position in the status bar.

    Deprecation Statement

    Use the button property.

    Declaration

    Swift

    var title: String?

    Objective-C

    @property(copy) NSString *title

    Discussion

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

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

  • The attributed string that is displayed at the status item’s position in the status bar.

    Deprecation Statement

    Use the button property.

    Declaration

    Swift

    @NSCopying var attributedTitle: NSAttributedString?

    Objective-C

    @property(copy) NSAttributedString *attributedTitle

    Discussion

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

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

  • image image (OS X v10.10) Property

    The image that is displayed at the status item’s position in the status bar.

    Deprecation Statement

    Use the button property.

    Declaration

    Swift

    var image: NSImage?

    Objective-C

    @property(strong) NSImage *image

    Discussion

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

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

  • alternateImage alternateImage (OS X v10.10) Property

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

    Deprecation Statement

    Use the button property.

    Declaration

    Swift

    var alternateImage: NSImage?

    Objective-C

    @property(strong) NSImage *alternateImage

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.10.

  • highlightMode highlightMode (OS X v10.10) Property

    A Boolean that indicates whether the status item is highlighted when it is clicked.

    Deprecation Statement

    Use the button property.

    Declaration

    Swift

    var highlightMode: Bool

    Objective-C

    @property BOOL highlightMode

    Discussion

    When the value of this property is YEStrue, the status item is highlighted when it is clicked. The default value of this property is NOfalse.

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

  • toolTip toolTip (OS X v10.10) Property

    The tool tip string that is displayed when the cursor pauses over the status item.

    Deprecation Statement

    Use the button property.

    Declaration

    Swift

    var toolTip: String?

    Objective-C

    @property(copy) NSString *toolTip

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

  • view view (OS X v10.10) Property

    The custom view that is displayed at the status item’s position in the status bar.

    Deprecation Statement

    Custom views should not be set on a status item. Use the button property instead.

    Declaration

    Swift

    var view: NSView?

    Objective-C

    @property(strong) NSView *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 OS X v10.0 and later.

    Deprecated in OS X v10.10.

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

    Deprecation Statement

    Custom views should not be set on a status item. Use the button property instead.

    Declaration

    Swift

    func drawStatusBarBackgroundInRect(_ rect: NSRect, withHighlight highlight: Bool)

    Objective-C

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

    Parameters

    rect

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

    highlight

    YEStrue to draw the background pattern in the standard highlight pattern, NOfalse 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 OS X v10.3 and later.

    Deprecated in OS X v10.10.