std::ui::style

Stability: Stable — the looks of UI controls.

std::ui::style describes how backgrounds and controls look: Paint fills a box, a Look pairs a background with a text style, a ButtonStyle gives a look for each interaction state of a button, toggle or select, and a SliderStyle paints a slider.

Styles are plain data built by const fn, so a studio declares them as const items and passes them to the style attribute of a control form or to Element::background.

use std::ui::style::{ButtonStyle, Look, Paint, SliderStyle, button_style};

Overview

Enum: Paint

pub enum Paint {
    None,
    Color(Color),
    Image(ImageAsset),
    /// An image whose corners stay unscaled; `insets` are the corner sizes.
    NineSlice { image: ImageAsset, insets: Insets },
}

Struct: Look

pub struct Look {
    pub background: Paint,
    pub text: TextStyle,
}

A background and a text style. The text style applies to labels inside the control (see Interaction looks).

Struct: ButtonStyle

pub struct ButtonStyle {
    pub idle: Look,
    pub hover: Option<Look>,
    pub focus: Option<Look>,
    pub pressed: Option<Look>,
    /// Replaces every other look while the control is disabled.
    pub disabled: Option<Look>,
    /// How look changes animate.
    pub change: Tween,
    pub hover_sound: Option<Sound>,
    pub click_sound: Option<Sound>,
}

The looks of a button-like control (button!, toggle!, select!) in each interaction state, how changes between them animate, and the sounds it plays. UI sounds play on the sound bus.

Interaction looks

• While the control is disabled, the disabled look replaces every other look. Without a disabled look, a disabled control shows idle at half opacity.
• Otherwise the first Some of pressed (while the pointer is held down over the control), focus (while the control has focus and focus is shown) and hover applies; idle is the fallback.
• A toggle whose value is true and that would show idle shows its on look instead: the pressed look if there is one, else the hover look, else idle with a 2 px outline in the idle text colour.
• Look changes animate with change.
• Labels inside a button or toggle use the current look’s text. Elsewhere, label and text! use System::text unless text! is given a style. There is no other cascade.

Function: button_style(idle)

pub const fn button_style(idle: Look) -> ButtonStyle {
    ButtonStyle {
        idle,
        hover: None,
        focus: None,
        pressed: None,
        disabled: None,
        change: instant(),
        hover_sound: None,
        click_sound: None,
    }
}

• idle Look — the look at rest.
• Returns: ButtonStyle — a style with only the idle look, instant changes and no sounds.
• Kind: const fn · Builtin: no

Add the other parts with the builder methods below. Each takes the style by value and returns it changed, so they chain.

ButtonStyle::hover(look)

pub const fn hover(mut self, look: Look) -> ButtonStyle

• Returns: this style with a hover look.

ButtonStyle::focus(look)

pub const fn focus(mut self, look: Look) -> ButtonStyle

• Returns: this style with a focus look, shown while the control has keyboard or pad focus.

ButtonStyle::pressed(look)

pub const fn pressed(mut self, look: Look) -> ButtonStyle

• Returns: this style with a pressed look.

ButtonStyle::disabled(look)

pub const fn disabled(mut self, look: Look) -> ButtonStyle

• Returns: this style with a disabled look.

ButtonStyle::change(tween)

pub const fn change(mut self, tween: Tween) -> ButtonStyle

• tween Tween — the duration, easing and delay of look changes (see std::screen::anim).
• Returns: this style with look changes animated by tween.

ButtonStyle::hover_sound(sound)

pub const fn hover_sound(mut self, sound: Sound) -> ButtonStyle

• sound Sound — a one-shot sound (see std::screen::audio).
• Returns: this style playing sound on hover.

ButtonStyle::click_sound(sound)

pub const fn click_sound(mut self, sound: Sound) -> ButtonStyle

• sound Sound — a one-shot sound.
• Returns: this style playing sound on click.

All builder methods are const fn · Builtin: no.

use std::narrative::text::text_style;
use std::screen::rgba;
use std::ui::style::{ButtonStyle, Look, Paint, button_style};

const CLICK: AudioAsset = asset("sound/click.ogg");

const MENU_BUTTON: ButtonStyle = button_style(Look { background: Paint::None, text: text_style(28, WHITE) })
    .hover(Look { background: Paint::Color(rgba(255, 255, 255, 40)), text: text_style(28, WHITE) })
    .change(tween(ms(150)))
    .click_sound(sound(CLICK));

An image button swaps its background image on hover and focus:

const fn image_style(idle: ImageAsset, hover: ImageAsset) -> ButtonStyle {
    let text = text_style(1, WHITE);
    button_style(Look { background: Paint::Image(idle), text })
        .hover(Look { background: Paint::Image(hover), text })
        .focus(Look { background: Paint::Image(hover), text })
}

Struct: SliderStyle

pub struct SliderStyle {
    pub track: Paint,
    pub fill: Paint,
    pub thumb: Paint,
    pub thumb_size: Size,
}

The paints of a slider!.

• track — the track, from the thumb’s centre at the minimum to its centre at the maximum.
• fill — the track from its start to the thumb’s centre, drawn over track.
• thumb — the handle, of size thumb_size, centred at the position of the value.
• thumb_size — the size of the handle, in pixels.