Struct widgetry::ButtonBuilder

pub struct ButtonBuilder<'a, 'c> {
    padding: EdgeInsets,
    stack_spacing: f64,
    hotkey: Option<MultiKey>,
    tooltip: Option<Text>,
    stack_axis: Option<Axis>,
    is_label_before_image: bool,
    corner_rounding: Option<CornerRounding>,
    is_disabled: bool,
    default_style: ButtonStateStyle<'a, 'c>,
    hover_style: ButtonStateStyle<'a, 'c>,
    disable_style: ButtonStateStyle<'a, 'c>,
    disabled_tooltip: Option<Text>,
}

Fields

padding: EdgeInsets

stack_spacing: f64

hotkey: Option<MultiKey>

tooltip: Option<Text>

stack_axis: Option<Axis>

is_label_before_image: bool

corner_rounding: Option<CornerRounding>

is_disabled: bool

default_style: ButtonStateStyle<'a, 'c>

hover_style: ButtonStateStyle<'a, 'c>

disable_style: ButtonStateStyle<'a, 'c>

disabled_tooltip: Option<Text>

Implementations

impl<'b, 'a: 'b, 'c> ButtonBuilder<'a, 'c>

pub fn new() -> Self

pub fn padding<EI: Into<EdgeInsets>>(self, padding: EI) -> Self

Extra spacing around a button’s items (label and/or image).

If not specified, a default will be applied.

// Custom padding for each inset
let b = ButtonBuilder::new().padding(EdgeInsets{ top: 1.0, bottom: 2.0,  left: 12.0, right: 14.0 });
// uniform padding
let b = ButtonBuilder::new().padding(6);

pub fn padding_top(self, padding: f64) -> Self

Extra spacing around a button’s items (label and/or image).

pub fn padding_left(self, padding: f64) -> Self

Extra spacing around a button’s items (label and/or image).

pub fn padding_bottom(self, padding: f64) -> Self

Extra spacing around a button’s items (label and/or image).

pub fn padding_right(self, padding: f64) -> Self

Extra spacing around a button’s items (label and/or image).

pub fn label_text<I: Into<String>>(self, text: I) -> Self

Set the text of the button’s label.

If label_text is not set, the button will not have a label.

pub fn label_underlined_text(self, text: &'a str) -> Self

Set the text of the button’s label. The text will be decorated with an underline.

See label_styled_text if you need something more customizable text styling.

pub fn label_styled_text(
    self,
    styled_text: Text,
    for_state: ControlState
) -> Self

Assign a pre-styled Text instance if your button need something more than uniformly colored text.

pub fn label_color(self, color: Color, for_state: ControlState) -> Self

Set the color of the button’s label.

If not specified, a default font color will be used.

pub fn font(self, font: Font) -> Self

Set the font used by the button’s label.

If not specified, a default font will be used.

pub fn font_size(self, font_size: usize) -> Self

Set the size of the font of the button’s label.

If not specified, a default font size will be used.

pub fn image_path(self, path: &'a str) -> Self

Set the image for the button. If not set, the button will have no image.

This will replace any image previously set.

pub fn image_bytes(self, labeled_bytes: (&'a str, &'a [u8])) -> Self

Set the image for the button. If not set, the button will have no image.

This will replace any image previously set.

• labeled_bytes: is a (label, bytes) tuple you can generate with include_labeled_bytes!
• label: a label to describe the bytes for debugging purposes
• bytes: UTF-8 encoded bytes of the SVG

pub fn image_batch(self, batch: GeomBatch, bounds: Bounds) -> Self

Set the image for the button. If not set, the button will have no image.

This will replace any image previously set.

This method is useful when doing more complex transforms. For example, to re-write more than one color for your button image, do so externally and pass in the resultant GeomBatch here.

pub fn image_color<C: Into<RewriteColor>>(
    self,
    color: C,
    for_state: ControlState
) -> Self

Rewrite the color of the button’s image.

This has no effect if the button does not have an image.

If the style hasn’t been set for the current ControlState, the style for ControlState::Default will be used.

pub fn image_bg_color(self, color: Color, for_state: ControlState) -> Self

Set a background color for the image, other than the buttons background.

This has no effect if the button does not have an image.

If the style hasn’t been set for the current ControlState, the style for ControlState::Default will be used.

pub fn image_dims<D: Into<ScreenDims>>(self, dims: D) -> Self

Scale the bounds containing the image. If image_dims are not specified, the images intrinsic size will be used.

See ButtonBuilder::image_content_mode to control how the image scales to fit its custom bounds.

pub fn image_content_mode(self, content_mode: ContentMode) -> Self

If a custom image_dims was set, control how the image should be scaled to its new bounds

If image_dims were not specified, the image will not be scaled, so content_mode has no affect.

The default, ContentMode::ScaleAspectFit will only grow as much as it can while maintaining its aspect ratio and not exceeding its bounds.

pub fn image_corner_rounding<R: Into<CornerRounding>>(self, value: R) -> Self

Set independent rounding for each of the button’s image’s corners

pub fn image_padding<EI: Into<EdgeInsets>>(self, value: EI) -> Self

Set padding for the image

pub fn bg_color(self, color: Color, for_state: ControlState) -> Self

Set a background color for the button based on the button’s ControlState.

If the style hasn’t been set for the current ControlState, the style for ControlState::Default will be used.

pub fn outline(self, outline: OutlineStyle, for_state: ControlState) -> Self

Set an outline for the button based on the button’s ControlState.

If the style hasn’t been set for the current ControlState, the style for ControlState::Default will be used.

pub fn custom_batch(self, batch: GeomBatch, for_state: ControlState) -> Self

Set a pre-rendered GeomBatch to use for the button instead of individual fields.

This is useful for applying one-off button designs that can’t be accommodated by the the existing ButtonBuilder methods.

pub fn hotkey<MK: Into<Option<MultiKey>>>(self, key: MK) -> Self

Set a hotkey for the button

pub fn tooltip(self, tooltip: impl Into<Text>) -> Self

Set a non-default tooltip Text to appear when hovering over the button.

If a tooltip is not specified, a default tooltip will be applied.

pub fn no_tooltip(self) -> Self

If a tooltip is not specified, a default tooltip will be applied. Use no_tooltip when you do not want even the default tooltip to appear.

pub fn disabled_tooltip(self, tooltip: impl Into<Text>) -> Self

Set a tooltip Text to appear when hovering over the button, when the button is disabled.

This tooltip is only displayed when disabled(true) is also called.

pub fn vertical(self) -> Self

The button’s items will be rendered in a vertical column

If the button doesn’t have both an image and label, this has no effect.

pub fn horizontal(self) -> Self

The button’s items will be rendered in a horizontal row

If the button doesn’t have both an image and label, this has no effect.

pub fn disabled(self, is_disabled: bool) -> Self

The button cannot be clicked and will be styled as ControlState::Disabled

pub fn label_first(self) -> Self

Display the button’s label before the button’s image.

If the button doesn’t have both an image and label, this has no effect.

pub fn image_first(self) -> Self

Display the button’s image before the button’s label.

If the button doesn’t have both an image and label, this has no effect.

pub fn stack_spacing(self, value: f64) -> Self

Spacing between the image and text of a button. Has no effect if the button is text-only or image-only.

pub fn corner_rounding<R: Into<CornerRounding>>(self, value: R) -> Self

Set independent rounding for each of the button’s corners

pub fn build(&self, ctx: &EventCtx<'_>, action: &str) -> Button

Build a button.

action: The event that will be fired when clicked

fn build_some_buttons(ctx: &EventCtx) {
    let one_off_builder = ButtonBuilder::new().label_text("foo").build(ctx, "foo");

    // If you'd like to build a series of similar buttons, `clone` the builder first.
    let red_builder = ButtonBuilder::new()
        .bg_color(Color::RED, ControlState::Default)
        .bg_color(Color::RED.alpha(0.3), ControlState::Disabled)
        .outline((2.0, Color::WHITE), ControlState::Default);

    let red_button_1 = red_builder.clone().label_text("First red button").build(ctx, "first");
    let red_button_2 = red_builder.clone().label_text("Second red button").build(ctx, "second");
    let red_button_3 = red_builder.label_text("Last red button").build(ctx, "third");
}

pub fn build_widget<I: AsRef<str>>(
    &self,
    ctx: &EventCtx<'_>,
    action: I
) -> Widget

Shorthand method to build a Button wrapped in a Widget

action: The event that will be fired when clicked

pub fn build_def(&self, ctx: &EventCtx<'_>) -> Widget

Shorthand method to build a default widget whose action is derived from the label’s text.

fn style_mut(
    &'b mut self,
    state: ControlState
) -> &'b mut ButtonStateStyle<'a, 'c>

fn style(&'b self, state: ControlState) -> &'b ButtonStateStyle<'a, 'c>

fn batch(&self, ctx: &EventCtx<'_>, for_state: ControlState) -> GeomBatch

Trait Implementations

impl<'a, 'c> Clone for ButtonBuilder<'a, 'c>

fn clone(&self) -> ButtonBuilder<'a, 'c>

Returns a copy of the value.

pub fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a, 'c> Debug for ButtonBuilder<'a, 'c>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a, 'c> Default for ButtonBuilder<'a, 'c>

fn default() -> ButtonBuilder<'a, 'c>

Returns the “default value” for a type.