Trait rubrail::TTouchbar

pub trait TTouchbar {
    type T: TTouchbar;
    pub fn alloc(title: &str) -> Self::T;

    pub fn set_icon(&self, image: &str) { ... }
    pub fn create_bar(&mut self) -> BarId { ... }
    pub fn add_items_to_bar(&mut self, bar_id: &BarId, items: Vec<ItemId>) { ... }
    pub fn set_bar_as_root(&mut self, bar_id: BarId) { ... }
    pub fn create_popover_item(
        &mut self, 
        image: Option<&TouchbarImage>, 
        text: Option<&str>, 
        bar_id: &BarId
    ) -> ItemId { ... }
    pub fn create_label(&mut self, text: &str) -> ItemId { ... }
    pub fn update_label(&mut self, label_id: &ItemId, text: &str) { ... }
    pub fn update_label_width(&mut self, label_id: &ItemId, width: u32) { ... }
    pub fn create_text_scrubber(
        &mut self, 
        data: Rc<dyn TScrubberData>
    ) -> ItemId { ... }
    pub fn select_scrubber_item(&mut self, scrub_id: &ItemId, index: u32) { ... }
    pub fn refresh_scrubber(&mut self, scrub_id: &ItemId) { ... }
    pub fn add_item_tap_gesture(
        &mut self, 
        item_id: &ItemId, 
        taps: u32, 
        fingers: u32, 
        cb: ButtonCb
    ) { ... }
    pub fn add_item_swipe_gesture(&mut self, item: &ItemId, cb: SwipeCb) { ... }
    pub fn create_spacer(&mut self, space: SpacerType) -> ItemId { ... }
    pub fn create_image_from_path(&mut self, path: &str) -> TouchbarImage { ... }
    pub fn create_image_from_template(
        &mut self, 
        template: ImageTemplate
    ) -> TouchbarImage { ... }
    pub fn create_button(
        &mut self, 
        image: Option<&TouchbarImage>, 
        text: Option<&str>, 
        cb: ButtonCb
    ) -> ItemId { ... }
    pub fn update_button(
        &mut self, 
        item: &ItemId, 
        image: Option<&TouchbarImage>, 
        text: Option<&str>
    ) { ... }
    pub fn update_button_width(&mut self, button_id: &ItemId, width: u32) { ... }
    pub fn create_slider(
        &mut self, 
        min: f64, 
        max: f64, 
        label: Option<&str>, 
        continuous: bool, 
        cb: SliderCb
    ) -> ItemId { ... }
    pub fn update_slider(&mut self, id: &ItemId, value: f64) { ... }
}

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

TTouchbar is the trait that defines the API for all interactions with the Touch Bar.

See the documentation of the Touchbar type for information on the default implementation.

An additional 'dummy' implementation is available by building Rubrail with the --no-default-features flags. This allows you to build an application that assumes a Touch Bar exists, but to remove it without code changes on platforms that don't have a Touch Bar, or for distributing through official Apple channels which don't permit private API usage.

Associated Types

type T: TTouchbar

A concrete implementation of TTouchbar

Loading content...

Required methods

pub fn alloc(title: &str) -> Self::T

Allocate a new Touch Bar interface

This allocates a new Touch Bar interface, but does not cause anything to be displayed yet.

Arguments

• title - The text to display on the icon in the Control Strip area of the Touch Bar. The title is only displayed if no icon is set. Note that any length is permitted, but the width of the icon is controlled by the OS, and typically truncates anything over 5 chars.

Returns

A newly allocated instance of the type.

Loading content...

Provided methods

pub fn set_icon(&self, image: &str)

Set an icon to display in the Control Strip

It is preferrable to associate your Touch Bar menus with an icon instead of a text string. This registers an icon, which will be displayed in the Control Strip region of the Touch Bar when you register a bar.

This function takes a path to an image, which should follow all of the standard Apple guidelines for icons on Retina displays. This typically means a PNG that is 40px x 40px @ 150dpi, or a multiple of this (80px x 80px @ 300dpi).

Note that Rubrail must run from a Mac app bundle, which means the icon will typically be in the bundle's Resources directory, and you must take care to provide the path to it correctly.

Arguments

• image - Full path to an image following the Apple icon guidelines

pub fn create_bar(&mut self) -> BarId

Create a new horizontal bar UI

This allocates a bar container, which will be either the root bar or a 'popover' for recursive menus. It contains no items and is not displayed or registered when it is created.

Returns

A newly allocated, empty bar.

pub fn add_items_to_bar(&mut self, bar_id: &BarId, items: Vec<ItemId>)

Adds a group of ordered items to a bar

This adds an array of allocated items, in the order provided, to an allocated bar. This does not cause the bar to be displayed or registered.

Arguments

• bar_id - Bar to add the items to
• items - Vector of items to add to the bar

pub fn set_bar_as_root(&mut self, bar_id: BarId)

Sets the given bar as the 'root' bar in the Control Strip

Registers the given bar as the 'root' bar. This creates an icon in the Control Strip region of the Touch Bar (the section on the right side), and causes this bar to be displayed when the icon is pressed.

This function causes the UI to be updated and the bar to become useable by the user.

Arguments

• bar_id - The bar to present when the Control Strip icon is pressed

pub fn create_popover_item(
    &mut self,
    image: Option<&TouchbarImage>,
    text: Option<&str>,
    bar_id: &BarId
) -> ItemId

Create a button to open a 'popover' submenu.

Creates a button UI element that, when pressed, recursively opens another bar as a submenu. Popovers allow you to create infinitely nested heirarchies of touch bar menus. Bars registered as popovers can themselves contain more popover items.

All buttons accept an image, text, or both. If both are provided, they will both be displayed at the same time.

Arguments

• image - An image allocated with a create_image_* function
• text - Text to display on the button
• bar_id - Bar to present when this button is pressed

Returns

A newly allocated item which can be added to a bar.

pub fn create_label(&mut self, text: &str) -> ItemId

Create a new label

Creates a text label, which simply displays a line of non-interactive text. Newlines are permitted, though only two lines will render properly.

Arguments

• text - Text to display in label

Returns

A newly allocated label item

pub fn update_label(&mut self, label_id: &ItemId, text: &str)

Changes the text in an existing label

This changes the text of an existing label, allowing updating of text displays without rebuilding the whole bar.

Arguments

• label_id - Label item to change
• text - New text to display in the existing label

pub fn update_label_width(&mut self, label_id: &ItemId, width: u32)

Changes the width of an existing label

Set a fixed width for a label, in pixels.

Arguments

• label_id - Label item to change
• width - New width of label, in pixels

pub fn create_text_scrubber(&mut self, data: Rc<dyn TScrubberData>) -> ItemId

Create a horizontally scrolling 'scrubber' of text

Creates a Scrubber, which is a horizontally scrolling widget filled with items which can be dynamically changed, and selected. This is the primary interface for choosing from a list of (possibly dynamic) options.

Scrubbers are filled with data using a collection of callbacks. This is implemented by the TScrubberData trait, which allows you to build a custom backing data store for scrubbers.

At creation, no item is selected. Call select_scrubber_item() after this to render an item as selected.

Arguments

• data - An object implementing the TScrubberData trait, wrapped in a reference counter (Rc).

Returns

A newly allocated scrubber item

pub fn select_scrubber_item(&mut self, scrub_id: &ItemId, index: u32)

Selects the given index in a scrubber

Marks the given index in the given scrubber as selected, so that item will be displayed with highlighting.

Arguments

• scrub_id - Scrubber to select in
• index - Index of the item to mark as selected

pub fn refresh_scrubber(&mut self, scrub_id: &ItemId)

Inform a scrubber to redraw after a change to its backing data

If the data store backing a scrubber (TScrubberData) has its data change, this function should be called to inform the scrubber to redraw.

Arguments

• scrub_id - Scrubber to refresh

pub fn add_item_tap_gesture(
    &mut self,
    item_id: &ItemId,
    taps: u32,
    fingers: u32,
    cb: ButtonCb
)

Register a tap gesture handler with a Touch Bar item

Registers a callback to be called when the given item is tapped with a one or more fingers. This works even for items that are normally non-interactive (like labels).

Supports specifying number of taps (i.e. double- or triple-click), and number of fingers independently. For instance, set taps to 2 and fingers to 3 to require double-clicking with 3 fingers at the same time.

Arguments

• item_id - Item to add the gesture detection to
• taps - Number of discrete taps to trigger callback
• fingers - Number of simultaneous fingers needed
• cb - Callback to call when a tap is detected

pub fn add_item_swipe_gesture(&mut self, item: &ItemId, cb: SwipeCb)

Register a swipe gesture handler with a Touch Bar item

Registers a callback to be called when the given item is swiped with a horizontal motion. This can be used to detect a finger sliding back and forth on a Touch Bar item, even for items that are normally non-interactive (like labels).

Arguments

• item - Item to add the gesture detection to
• cb - Callback to call when a touch is detected

pub fn create_spacer(&mut self, space: SpacerType) -> ItemId

Create space between items in a bar

Arguments

• space - The type of spacer to create

Returns

A newly allocated spacer item that can be added to a bar

pub fn create_image_from_path(&mut self, path: &str) -> TouchbarImage

Create an image from a file path

Creates an image that can be assigned to UI items that display them, like buttons and popovers.

Specify a relative or absolute path to the image.

When specifying an image, follow Apple's guidelines for icons on Retina displays (40px x 40px @ 150dpi PNG recommended), and remember to handle paths into the app bundle correctly.

WARNING image memory is deallocated after it is assigned to an item. Do not use the same image twice. If two buttons will have the same image, you must allocate the image twice.

Arguments

• path - Path to an image file

Returns

A newly allocated image that can be added to an item

pub fn create_image_from_template(
    &mut self,
    template: ImageTemplate
) -> TouchbarImage

Create an image from a template

Creates an image that can be assigned to UI items that display them, like buttons and popovers.

See ImageTemplate for the supported options. These templates are provided by Apple.

WARNING image memory is deallocated after it is assigned to an item. Do not use the same image twice. If two buttons will have the same image, you must allocate the image twice.

Arguments

• template - Identifier of the image template to use

Returns

A newly allocated image that can be added to an item

pub fn create_button(
    &mut self,
    image: Option<&TouchbarImage>,
    text: Option<&str>,
    cb: ButtonCb
) -> ItemId

Create a button that triggers a callback when pressed

All buttons accept an image, text, or both. If both are provided, they will both be displayed at the same time.

Arguments

• image - An image allocated with a create_image_* function
• text - Text to display on the button
• cb - Callback to call when the button is pressed

Returns

A newly allocated item which can be added to a bar.

pub fn update_button(
    &mut self,
    item: &ItemId,
    image: Option<&TouchbarImage>,
    text: Option<&str>
)

Changes the image and/or text of a button

Arguments

• item - Button item to change
• image - New image to draw on button (optional)
• text - New text to draw on button (optional)

pub fn update_button_width(&mut self, button_id: &ItemId, width: u32)

Changes the width of an existing button

Set a fixed width for a button, in pixels.

Arguments

• button_id - Button item to change
• width - New width of button, in pixels

pub fn create_slider(
    &mut self,
    min: f64,
    max: f64,
    label: Option<&str>,
    continuous: bool,
    cb: SliderCb
) -> ItemId

Create a slider item

Creates an item that displays as a continuously variable horizontal slider, reporting its value as a floating point between the provided minimum and maximum values.

When the slider value changes, the associated callback is called. Note that it triggers frequently as the user slides it, so 'debouncing' or buffering might be required if high-frequency changes are not desired.

Newly created sliders default to the minimum value. If you need to change this, set the current value with update_slider().

Arguments

• min - Minimum value (slider all the way left)
• max - Maximum value (slider all the way right)
• label - Text label displayed on left of slider (optional)
• continuous - Whether callback is called while sliding, or only
• cb - Callback called when the slider value is changed after it is released.

Returns

A newly allocated slider item

pub fn update_slider(&mut self, id: &ItemId, value: f64)

Update the current position of a slider

Sets the current value of an existing slider.

Arguments

• id - Slider item to update
• value - New value of the slider. Must be between the min and max specified when the slider was created.

Loading content...

Implementors

impl TTouchbar for DummyTouchbar

type T = DummyTouchbar

pub fn alloc(_title: &str) -> DummyTouchbar

Loading content...