Documentation

Permissions

Apple has been increasing the security transparency of macOS across the past several releases by requiring user permission for many APIs that were previously accessible by all applications. Accordingly, uBar now requires a few of these be enabled to function, while others remain optional.

Accessibility

The Accessibility API is used to control windows and applications:

• Quitting applications
• Closing windows
• Maximizing windows
• Minimizing windows

Screen Recording

As of macOS 10.15 Catalina, various APIs require the Screen Recording permission. These APIs are used to:

• Read window titles
• Reflect new windows being opened
• Capture window contents for window previews

Please note that at no time is your screen actually being recorded.

Full Disk Access

As of macOS 10.14 Mojave, various trash-related APIs require the Full Disk Access permission. These APIs are used to:

• Open the Trash
• Empty the Trash

While recommended, this permission is optional as it is limited to Trash-related functionality.

Miscellaneous

App statuses

The following app statuses are indicated by colored diagonal line patterns:

• Launching (white): The app is being launched by the system.
• Restorable (blue): The app may have previously crashed, and can be restored by the system.
• Unresponsive (red): The app is currently unresponsive.

Rows

To increase or decrease the number of rows, drag the very edge of uBar up or down. The maximum number of rows is five.

Favorites

To add an open application to the Favorites Area, control or right-click it and select "Add to Favorites". To add any file, folder, or application, you can control or right-click it in the Finder and select "Services" and then "Add to uBar Favorites". To enable this service, check it via System Preferences > Keyboard > Shortcuts > Services.

Activity mode

Hold a custom modifier key (default is right-control) on your keyboard to activate Activity Mode. Applications will show % CPU utilization and Memory Usage.

Special shortcuts

In addition to the shortcuts available in the Shortcuts pane under Preferences, the following shortcuts are available:

Tile behaviour

When clicking on a tile in uBar, the resulting behaviour depends on how many windows are associated with the tile:

• 0 windows: This is an application tile. Clicking toggles the visibility of the application.
• 1+ windows: This is a window stack tile. Clicking it displays a menu listing the windows and the application.

Manually ordering apps

To manually order your applications, set Application Order to Manual in the Preferences window under General. Then switch to the Application pane in the Preferences window, and you can re-order the Included Applications list.

Default Calendar

When you click on the clock area, your default Calendar app will launch. This can be set in Calendar.app Preferences > General > Default calendar app.

Clock Format

The format of the clock area is determined by the formatting settings found in System Preferences > Language & Region. Please note that the settings found under Date & Time > Clock only apply to the macOS menu bar and not uBar.

Preferences

Size

The size setting in the Preferences window allows you to select five options: Automatic, Small, Medium, Large, and Huge. The advantage of Automatic is that uBar will automatically adapt itself to your screen size. A primary screen with a width of 1600 or more pixels will result in a Large uBar, while anything smaller will result in a Small uBar. This is especially useful with laptops.

Screen

The screen setting in the Preferences window allows you to display uBar on the Main screen (the one with the active menu bar), the Primary screen, or a secondary screen.

Window grouping

The Window Grouping feature in the Preferences window allows you to determine whether uBar will group windows belonging to the same application together. There are three settings: Always, Never, and Automatic. Automatic means the windows are ungrouped unless there is not enough room, in which case windows will automatically group together.

App flashes

The "Flash apps that want attention" option allows you to toggle whether or not you want applications that are seeking user attention to flash in uBar. This is the equivalent of Dock bounces. There are two types of attention requests — informational and critical. When an app issues an informational attention request, the app will flash for a second. With a critical request, the app will flash until you switch to it and make it the active app. For the Dock, the equivalent is a single bounce versus repeated bounces. Please note that Skype is a popular application which makes very frequent use of attention requests by default. If Skype is constantly flashing, you must disable the Dock bounce option for multiple events in Skype Preferences > Notifications > Details.

Dock defaults

The following settings will be set:

• Rows: 1
• Pinning: None
• Show app titles: No
• Window grouping: Always
• Left-click to display grouped window list: No
• Favorites — Show separators: Yes
• Clock — Show clock: No
• Clicking the active app hides it: No

Taskbar defaults

The following settings will be set:

• Pinning: Left and Right
• Show app titles: Yes
• Window grouping: Automatic
• Left-click to display grouped window list: Yes
• Favorites — Show separators: No
• Clock — Show clock: Yes
• Clicking the active app hides it: Yes

Theme

• System: Under OS X 10.10 Yosemite and above, uBar will use Light or Dark mode depending on whether Dark mode is enabled in System Preferences under General. Under OS X 10.9 Mavericks, uBar will use Light mode if Appearance is set to Aqua and Dark mode if it is set to Graphite in System Preferences under General.
• Light: uBar will resemble the default menu bar style.
• Dark: uBar will resemble the dark menu bar style introduced in OS X 10.10 Yosemite.
• Platinum Neue: uBar will resemble the "unified" OS X window style.
• Now Playing: uBar will be styled based on the Album Artwork of the currently playing audio or video in iTunes. If none is available, this setting behaves the same as the "System" setting.
• Custom: uBar will be styled based on the background color, foreground color, highlight color, and opacity that you select.

Renaming apps

To edit an app's display name, double-click its entry in the Preferences > Apps lists, change the name, and press return. To set it back to its default, repeat the process while deleting the entire name.

Developer mode

You can enable developer mode in the Preferences window. Developer mode shows the Process ID (PID) for Applications, and the Window ID (WID) for Windows.

App Support Customization

Icon Overrides

Icons in uBar can be overridden by PNG files in the ~/Library/Application Support/uBar/Icons folder.

To override an application icon, the filename must be the bundle identifier of the app, followed by the .png extension. For example: com.apple.AddressBook.png

The following names may be used for special icons:

• Folder: Folder.png
• Applications Folder: FolderApplications.png
• Desktop Folder: FolderDesktop.png
• Documents Folder: FolderDocuments.png
• Movies Folder: FolderMovies.png
• Music Folder: FolderMusic.png
• Pictures Folder: FolderPictures.png
• Public Folder: FolderPublic.png
• Trash Empty: TrashEmpty.png
• Trash Full: TrashFull.png

Custom Timepieces

In addition to the built-in timepieces, custom timepieces may be added to uBar in ~/Library/Application Support/uBar/Timepieces.

Each timepiece must be in its own folder, and contain a Timepiece.plist and relevant PNG files. You may download the following example: Brawer_A300-1.zip.

Terminal

Terminal commands

The following terminal commands allow you to change certain behaviours that cannot be set via GUI. They require a relaunch of uBar to take effect.