NSStatusBar Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.0 and later.
Companion guide
Declared in
NSStatusBar.h

Overview

The NSStatusBar class defines an object that manages a collection of NSStatusItem objects displayed within the system-wide menu bar. A status item can be displayed with text or an icon, can provide a menu and a target-action message when clicked, or can be a fully customized view that you create.

Use status items sparingly and only if the alternatives (such as a Dock menu, preference pane, or status window) are not suitable. Because there is limited space in which to display status items, status items are not guaranteed to be available at all times. For this reason, do not rely on them being available and always provide a user preference for hiding your application’s status items to free up space in the menu bar.

Tasks

Getting the System-Wide Instance

Managing Status Items

Getting Status-Bar Attributes

Class Methods

systemStatusBar

Returns the system-wide status bar located in the menu bar.

+ (NSStatusBar *)systemStatusBar
Return Value

The shared status bar object.

Discussion

The status bar begins at the right side of the menu bar (to the left of Menu Extras and the menu bar clock) and grows to the left as NSStatusItem objects are added to it.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSStatusBar.h

Instance Methods

isVertical

Returns whether the receiver has a vertical orientation.

- (BOOL)isVertical
Return Value

YES if the receiver has a vertical orientation, otherwise NO.

Discussion

The status bar returned by systemStatusBar is horizontal, so it always returns NO.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSStatusBar.h

removeStatusItem:

Removes the specified status item from the receiver.

- (void)removeStatusItem:(NSStatusItem *)item
Parameters
item

The NSStatusItem object to remove.

Discussion

Status items to the left of the specified one in the status bar shift to the right to reclaim its space.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSStatusBar.h

statusItemWithLength:

Returns a newly created status item that has been allotted a specified space within the status bar.

- (NSStatusItem *)statusItemWithLength:(CGFloat)length
Parameters
length

A constant that specifies whether the status item is of fixed width, or variable width. The valid constants are described in “Status Bar Item Length.”

Return Value

An NSStatusItem object or nil if the item could not be created.

Discussion

The receiver does not retain a reference to the status item, so you need to retain it. Otherwise, the object is removed from the status bar when it is deallocated.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSStatusBar.h

thickness

Returns the thickness of the status bar.

- (CGFloat)thickness
Return Value

The thickness of the status bar in pixels.

Discussion

The status bar returned by systemStatusBar has a thickness of 22 pixels, the thickness of the menu bar.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSStatusBar.h

Constants

Status Bar Item Length

The following constants are used by statusItemWithLength:.

#define NSVariableStatusItemLength    (-1)
#define NSSquareStatusItemLength      (-2)
Constants
NSSquareStatusItemLength

Sets the status item length to the status bar thickness.

Available in OS X v10.0 and later.

Declared in NSStatusBar.h.

NSVariableStatusItemLength

Makes the status item length dynamic, adjusting to the width of its contents.

Available in OS X v10.0 and later.

Declared in NSStatusBar.h.