[−][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
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 |
| 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 |
| 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 |