Crate whiskers_widgets

Overview

This crate implements the UI widget machinery used by the whiskers crate to display the sketch parameter UI. The main entry point is the Widget trait and the associated macros defined in [whiskers-derive].

This crate is separate from the main crate to allow other crates (including the vsvg crate) to implement the Widget trait for their own types.

Implementing the Widget trait

For each supported sketch parameter type T, there must exist a widget type that implements Widget<T> and is registered with register_widget_ui! macro. This module include the traits and macros needed to support this mechanism, as well as widgets for basic types.

For example, let’s consider the bool type:

#[derive(Default)]
pub struct BoolWidget;

impl whiskers_widgets::Widget<bool> for BoolWidget {
    fn ui(&self, ui: &mut egui::Ui, label: &str, value: &mut bool) -> egui::Response {
        ui.horizontal(|_| {});
        ui.checkbox(value, label)
    }
}

whiskers_widgets::register_widget_ui!(bool, BoolWidget);

The BoolWidget type implements the Widget<bool> trait, which requires the Widget::ui method, and is registered with the crate::register_widget_ui! macro. Note that the Widget::ui method is called in the context of an 2-column egui::Grid, so it must contain exactly two top level UI calls, where the first one typically is the label, and the second the actual interactive widget. In the case of a checkbox, the label is already embedded in the UI widget, we leave the first column empty.

The BoolWidget type is already provided by the crate crate, but custom widgets can be implemented for custom types using the same pattern.

Configuring widgets

Many widgets support additional configuration options, which can be set using the #[param(...)] attribute of the whiskers_derive::Sketch macro. This is done by using the builder pattern on the widget type. For example, here is an extract of NumericWidget, which supports numerical types such as f64 and i32:

#[derive(Default)]
pub struct NumericWidget<T: Numeric> {
    step: Option<T>,
    slider: bool,
    /* ... */
}

impl<T: Numeric> NumericWidget<T> {
    pub fn step(mut self, step: T) -> Self {
        self.step = Some(step);
        self
    }

    pub fn slider(mut self, slider: bool) -> Self {
        self.slider = slider;
        self
    }
}

impl<T: Numeric> whiskers_widgets::Widget<T> for NumericWidget<T> {
    /* ... */
}

whiskers_widgets::register_widget_ui!(f64, NumericWidget<f64>);
/* ... */

Now let’s consider a hypothetical sketch:

#[sketch_app]
#[derive(Default)]
struct MySketch {
    #[param(slider, step = 0.1)]
    irregularity: f64,
}

Based on the #[param(...)] attributes, the whiskers_derive::Sketch derive macro will automatically generate the corresponding builder pattern calls:

whiskers_widgets::NumericWidget::<f64>::default().slider(true).step(0.1);

Note that when no value is provided for a key (such as slider here), a boolean value of true is assumed.

Modules

• exports
  Exported dependencies, for use by whiskers_derive

Macros

• register_widget_ui
  Registers a given Widget type for given sketch parameter type.

Structs

• BoolWidget
  Widget to display bool sketch parameters.
• NumericWidget
  A widget for built-in numeric values.
• StringWidget
  Widget for the String type.
• VecWidget

Traits

• Widget
  This is the base trait for widgets used to display sketch parameters in the UI.
• WidgetApp
• WidgetMapper
  This utility trait serves to associate a Widget type with a given sketch parameter type T.

Functions

• collapsing_header
  Display a properly-styled collapsing header with some content. If the header is collapsed, the summary is displayed inline instead of the content.
• enum_collapsing_header
  Display a collapsing header for enum, where the header allows selecting the variant.

Attribute Macros

• sketch_app
  Attribute macro to automatically derive some of the required traits for a sketch app.
• sketch_widget
  Attribute macro to automatically derive some of the required traits for a sketch widget.

Derive Macros

• Sketch
• Widget