macOS NSStatusBar

From Lazarus wiki
Revision as of 12:18, 12 December 2021 by Trev (talk | contribs) (New macOS content stub - under construction)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigationJump to search
<translate> Warning: </translate> Warning Under construction

Overview

NSStatusBar is an object that manages a collection of status items that provide interaction with or feedback to the user. A status item can be displayed with text or an icon, can provide a menu or send a target-action message when clicked. As there is limited space in which to display status items, status items are not guaranteed to be available at all times. For this reason, Apple recommends that you 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.

macOS Status Bar.png

Only one status bar, the system status bar, is available in macOS. It resides in the system-wide menu bar as shown above. Status items appear on the right side of the menu bar, just to the left of the menu bar clock and Menu Extras, such as the Displays and Sound menus. The items remain in the menu bar even when your application is not in the foreground.

Creating status items

1. Obtain the system status bar with the systemStatusBar class method; you should not allocate an instance of it yourself. ' 2A. If you are displaying an icon, invoke statusItemWithLength to create a new status item and allocate space for it in the menu bar. Pass the amount of space in pixels you need to display your status item. You can use the constant NSSquareStatusItemLength' to make the width the same as the status bar’s thickness.

2B. If you are displaying text, invoke statusItemWithLength to create a new status item and allocate space for it in the menu bar. Pass the amount of space in pixels you need to display your status item. You can use the constant NSVariableStatusItemLength to make the width variable based on the contents of the item.

The system status bar is shared by all applications and therefore cannot retain references to each application’s status item objects. Instead, each application is responsible for retaining its own status items. Each status item then communicates with the status bar as its configuration changes. When deallocated, the status item removes itself from the status bar. Following normal Cocoa memory management rules, you must retain the object returned by statusItemWithLength to keep it around.

Once you have the new status item object, you can assign it a title, a menu, a target-action, a tool tip, and so on.

Example code

To Come...