[][src]Crate rubrail

Rubrail

Rubrail is a library for building persistent, always-available UIs for the Mac Touch Bar.

Rubrail uses private Apple APIs to add an expandable icon to the Touch Bar's "Control Strip" region, the section that is, by default, always displayed on the right side of the bar. This lets you create a Touch Bar menu that is always available, regardless of which app is currently in focus. It supports a variety of common UI elements, including recursive "popbar" submenus, and uses callbacks to your own functions or closures to inform your app of touch interactions.

Getting Rubrail

Cargo Crate

GitHub Source

Execution Environment

Rubrail can only communicate with Apple's Touch Bar service when it is executed from a Mac Application environment: a valid .app bundle with an Info.plist and the correct directory structure.

When run outside of an app bundle, like when running with cargo run, Rubrail will work correctly behind the scenes, but your Touch Bar will not be registered with the system and will not display on the Control Strip, making it inaccessible to the user.

The included example uses fruitbasket to automatically bundle itself into an OS X app at runtime. You can run the example with:

$ cargo test && cargo run --example example

Memory Management

Rubrail manually manages the lifecycle of allocated Foundation and Cocoa elements (the Objective-C classes that provide the UI features). Because of this, it is possible to leak memory. Care should be taken to use the API as intended to avoid leaks.

The internal memory allocation strategy is to freely allocate objects whenever a create*() function is called, to associate all allocated objects with a bar, and to register that bar with the system. If the bar is replaced (by registering a new bar with the sytem), the replacement logic is responsible for recursively deallocating all items associated with the bar and its subbars, and then deallocating the bar itself.

Any objects created with a create*() function that are never added to a bar that is set as the system bar will be leaked.

Modules

util

Utility functions for working with the Apple/TouchBar environment

Macros

objc_subclass

Wrap an Objective-C class in a subclass that tracks allocations

Enums

ImageTemplate

Identifiers for Apple's standard button image templates

SpacerType

Identifiers for the type of spacing available between items

SwipeState

State of the current swipe gesture on an item

Traits

TScrubberData

The callback API for managing data in a Scrubber

TTouchbar

API for creating, managing, and getting feedback from Touch Bar UIs

Type Definitions

BarId

Reference to a horizontal bar created by a TTouchbar

ButtonCb

A callback that is called when a button on a Touch Bar is pressed

ItemId

Reference to an item that can be added to a bar created by a TTouchbar

SliderCb

A callback that is called when the value of a slide on a Touch Bar changes

SwipeCb

A callback that is called when an item is swiped

Touchbar

Controller for creating and using Touch Bar UIs

TouchbarImage

An allocated image that can be added to items