Trait nannou::ui::Widget[−][src]

pub trait Widget: Common {
    type State: Any + Send;
    type Style: Style + Send;
    type Event;

Show methods    pub fn init_state(&self, Generator<'_>) -> Self::State;

    pub fn style(&self) -> Self::Style;

    pub fn update(self, args: UpdateArgs<'_, '_, '_, '_, Self>) -> Self::Event;

    pub fn default_x_position(&self, ui: &Ui) -> Position { ... }

    pub fn default_y_position(&self, ui: &Ui) -> Position { ... }

    pub fn default_x_dimension(&self, ui: &Ui) -> Dimension { ... }

    pub fn default_y_dimension(&self, ui: &Ui) -> Dimension { ... }

    pub fn drag_area(
        &self, 
        _dim: [f64; 2], 
        _style: &Self::Style, 
        _theme: &Theme
    ) -> Option<Rect> { ... }

    pub fn kid_area(&self, args: KidAreaArgs<'_, Self>) -> KidArea { ... }

    pub fn is_over(&self) -> fn(&Container, [f64; 2], &Theme) -> IsOver { ... }

    pub fn parent(self, parent_id: NodeIndex<u32>) -> Self { ... }

    pub fn no_parent(self) -> Self { ... }

    pub fn place_on_kid_area(self, b: bool) -> Self { ... }

    pub fn graphics_for(self, id: NodeIndex<u32>) -> Self { ... }

    pub fn floating(self, is_floating: bool) -> Self { ... }

    pub fn crop_kids(self) -> Self { ... }

    pub fn scroll_kids(self) -> Self { ... }

    pub fn scroll_kids_vertically(self) -> Self { ... }

    pub fn scroll_kids_horizontally(self) -> Self { ... }

    pub fn and<F>(self, build: F) -> Self
    where
        F: FnOnce(Self) -> Self,
    { ... }

    pub fn and_mut<F>(self, mutate: F) -> Self
    where
        F: FnOnce(&mut Self),
    { ... }

    pub fn and_if<F>(self, cond: bool, build: F) -> Self
    where
        F: FnOnce(Self) -> Self,
    { ... }

    pub fn and_then<T, F>(self, maybe: Option<T>, build: F) -> Self
    where
        F: FnOnce(Self, T) -> Self,
    { ... }

    pub fn set(
        self, 
        id: NodeIndex<u32>, 
        ui_cell: &'a mut UiCell<'b>
    ) -> Self::Event { ... }

}

A trait to be implemented by all Widget types.

A type that implements Widget can be thought of as a collection of arguments to the Widget’s Widget::update method. They type itself is not stored between updates, but rather is used to update an instance of the Widget’s Widget::State, which is stored.

Methods that must be overridden:

  • init_state
  • style
  • update

Methods that can be optionally overridden:

  • default_x_position
  • default_y_position
  • default_width
  • default_height
  • drag_area
  • kid_area

Methods that should not be overridden:

  • floating
  • scroll_kids
  • scroll_kids_vertically
  • scroll_kids_horizontally
  • place_widget_on_kid_area
  • parent
  • no_parent
  • set

Associated Types

type State: Any + Send[src]

State to be stored within the Uis widget cache.

Take advantage of this type for any large allocations that you would like to avoid repeating between updates, or any calculations that you’d like to avoid repeating between calls to update.

Conrod will never clone the state, it will only ever be moved.

type Style: Style + Send[src]

Every widget is required to have its own associated Style type. This type is intended to contain high-level styling information for the widget that can be optionally specified by a user of the widget.

All Style structs are typically Copy and contain simple, descriptive fields like color, font_size, line_spacing, border_width, etc. These types are also required to be PartialEq. This is so that the Ui may automatically compare the previous style to the new style each time .set is called, allowing conrod to automatically determine whether or not something has changed and if a re-draw is required.

Each field in a Style struct is typically an Option<T>. This is so that each field may be optionally specified, indicating to fall back to defaults if the fields are None upon style retrieval.

The reason this data is required to be in its own Style type (rather than in the widget type itself) is so that conrod can distinguish between default style data that may be stored within the Theme’s widget_styling field, and other data that is necessary for the widget’s behaviour logic. Having Style be an associated type makes it trivial to retrieve unique, widget-specific styling data for each widget from a single method (see Theme::widget_style).

#[derive(WidgetStyle)]

These Style types are often quite similar and their implementations can involve a lot of boilerplate when written by hand. To get around this, conrod provides #[derive(WidgetStyle)].

This procedural macro generates a “getter”-style method for each struct field that is decorated with a #[conrod(default = "expr")] attribute. The generated methods have the same name as their respective fields and behave as follows:

  1. First, the method will attempt to return the value directly if the field is Some.
  2. If the field is None, the method will fall back to the Widget::Style stored within the Theme’s widget_styling map.
  3. If there are no style defaults for the widget in the Theme, or if there is but the default field is also None, the method will fall back to the expression specified within the field’s #[conrod(default = "expr")] attribute.

The given “expr” can be a string containing any expression that returns the type specified within the field’s Option type parameter. The expression may also utilise the theme and self bindings, where theme is a binding to the borrowed Theme and self is a binding to the borrowed instance of this Style type.

Examples

/// Unique styling for a Button widget.
#[derive(Copy, Clone, Debug, Default, PartialEq, WidgetStyle)]
pub struct Style {
    /// Color of the Button's pressable area.
    #[conrod(default = "theme.shape_color")]
    pub color: Option<Color>,
    /// Width of the border surrounding the button.
    #[conrod(default = "1.0")]
    pub border: Option<Scalar>,
    /// The color of the Button's rectangular border.
    #[conrod(default = "conrod_core::color::BLACK")]
    pub border_color: Option<Color>,
    /// The color of the Button's label.
    #[conrod(default = "theme.label_color")]
    pub label_color: Option<Color>,
    /// The font size for the Button's label.
    #[conrod(default = "12")]
    pub label_font_size: Option<FontSize>,
}

type Event[src]

The type of event yielded by the widget, returned via the Widget::set function.

For a Toggle widget, this might be a bool.

For a non-interactive, purely graphical widget, this might be ().

Loading content...

Required methods

pub fn init_state(&self, Generator<'_>) -> Self::State[src]

Return the initial State of the Widget.

The Ui will only call this once, immediately prior to the first time that Widget::update is first called.

pub fn style(&self) -> Self::Style[src]

Return the styling of the widget.

The Ui will call this once prior to each update. It does this so that it can check for differences in Style in case we need to re-draw the widget.

pub fn update(self, args: UpdateArgs<'_, '_, '_, '_, Self>) -> Self::Event[src]

Update our Widget’s unique Widget::State via the State wrapper type (the state field within the UpdateArgs).

Whenever State::update is called, a has_updated flag is set within the State, indicating that there has been some change to the unique Widget::State and that we require re-drawing the Widget. As a result, widget designers should only call State::update when necessary, checking whether or not the state has changed before invoking the method. See the custom_widget.rs example for a demonstration of this.

Arguments

  • id - The Widget’s unique index (whether Public or Internal).
  • prev - The previous common state of the Widget. If this is the first time update is called, Widget::init_state will be used to produce some initial state instead.
  • state - A wrapper around the Widget::State. See the State docs for more details.
  • rect - The position (centered) and dimensions of the widget.
  • style - The style produced by the Widget::style method.
  • ui - A wrapper around the Ui, offering restricted access to its functionality. See the docs for UiCell for more details.
Loading content...

Provided methods

pub fn default_x_position(&self, ui: &Ui) -> Position[src]

The default Position for the widget along the x axis.

This is used when no Position is explicitly given when instantiating the Widget.

pub fn default_y_position(&self, ui: &Ui) -> Position[src]

The default Position for the widget along the y axis.

This is used when no Position is explicitly given when instantiating the Widget.

pub fn default_x_dimension(&self, ui: &Ui) -> Dimension[src]

The default width for the Widget.

This method is only used if no height is explicitly given.

By default, this simply calls default_dimension with a fallback absolute dimension of 0.0.

pub fn default_y_dimension(&self, ui: &Ui) -> Dimension[src]

The default height of the widget.

By default, this simply calls default_dimension with a fallback absolute dimension of 0.0.

pub fn drag_area(
    &self,
    _dim: [f64; 2],
    _style: &Self::Style,
    _theme: &Theme
) -> Option<Rect>[src]

If the widget is draggable, implement this method and return the position and dimensions of the draggable space. The position should be relative to the center of the widget.

pub fn kid_area(&self, args: KidAreaArgs<'_, Self>) -> KidArea[src]

The area on which child widgets will be placed when using the Place Position methods.

pub fn is_over(&self) -> fn(&Container, [f64; 2], &Theme) -> IsOver[src]

Returns either of the following:

  • A Function that can be used to describe whether or not a given point is over the widget.
  • The Id of another Widget that can be used to determine if the point is over this widget.

By default, this is a function returns true if the given Point is over the bounding Rect and returns false otherwise.

NOTE: It could be worth removing this in favour of adding a widget::State trait, adding an is_over method to it and then refactoring the Container to store a Box<widget::State> and Box<widget::Style> rather than Box<Any>. This would however involve some significant breakage (which could perhaps be mitigated by adding a derive(WidgetState) macro - a fair chunk of work) so this might be the easiest temporary way forward for now.

pub fn parent(self, parent_id: NodeIndex<u32>) -> Self[src]

Set the parent widget for this Widget by passing the WidgetId of the parent.

This will attach this Widget to the parent widget.

pub fn no_parent(self) -> Self[src]

Specify that this widget has no parent widgets.

pub fn place_on_kid_area(self, b: bool) -> Self[src]

Set whether or not the Widget should be placed on the kid_area.

If true, the Widget will be placed on the kid_area of the parent Widget if the Widget is given a Place variant for its Position.

If false, the Widget will be placed on the parent Widget’s total area.

By default, conrod will automatically determine this for you by checking whether or not the Widget that our Widget is being placed upon returns Some from its Widget::kid_area method.

pub fn graphics_for(self, id: NodeIndex<u32>) -> Self[src]

Indicates that the Widget is used as a non-interactive graphical element for some other widget.

This is useful for Widgets that are used to compose some other Widget.

When adding an edge a -> b where b is considered to be a graphical element of a, several things are implied about b:

  • If b is picked within either Graph::pick_widget or Graph::pick_top_scrollable_widget, it will instead return the index for a.
  • When determining the Graph::scroll_offset for b, a’s scrolling (if it is scrollable, that is) will be skipped.
  • b will always be placed upon a’s total area, rather than its kid_area which is the default.
  • Any Graphic child of b will be considered as a Graphic child of a.

pub fn floating(self, is_floating: bool) -> Self[src]

Set whether or not the widget is floating (the default is false). A typical example of a floating widget would be a pop-up or alert window.

A “floating” widget will always be rendered after its parent tree and all widgets connected to its parent tree. If two sibling widgets are both floating, then the one that was last clicked will be rendered last. If neither are clicked, they will be rendered in the order in which they were cached into the Ui.

pub fn crop_kids(self) -> Self[src]

Indicates that all widgets who are children of this widget should be cropped to the kid_area of this widget.

pub fn scroll_kids(self) -> Self[src]

Makes the widget’s KidArea scrollable.

If a widget is scrollable and it has children widgets that fall outside of its KidArea, the KidArea will become scrollable.

This method calls Widget::crop_kids internally.

pub fn scroll_kids_vertically(self) -> Self[src]

Makes the widget’s KidArea scrollable.

If a widget is scrollable and it has children widgets that fall outside of its KidArea, the KidArea will become scrollable.

This method calls Widget::crop_kids internally.

pub fn scroll_kids_horizontally(self) -> Self[src]

Set whether or not the widget’s KidArea is scrollable (the default is false).

If a widget is scrollable and it has children widgets that fall outside of its KidArea, the KidArea will become scrollable.

This method calls Widget::crop_kids internally.

pub fn and<F>(self, build: F) -> Self where
    F: FnOnce(Self) -> Self, [src]

A builder method that “lifts” the Widget through the given build function.

This method is solely for providing slight ergonomic improvement by helping to maintain the symmetry of the builder pattern in some cases.

pub fn and_mut<F>(self, mutate: F) -> Self where
    F: FnOnce(&mut Self), [src]

A builder method that mutates the Widget with the given mutate function.

This method is solely for providing slight ergonomic improvement by helping to maintain the symmetry of the builder pattern in some cases.

pub fn and_if<F>(self, cond: bool, build: F) -> Self where
    F: FnOnce(Self) -> Self, [src]

A method that conditionally builds the Widget with the given build function.

If cond is true, build(self) is evaluated and returned.

If false, self is returned.

pub fn and_then<T, F>(self, maybe: Option<T>, build: F) -> Self where
    F: FnOnce(Self, T) -> Self, [src]

A method that optionally builds the Widget with the given build function.

If maybe is Some(t), build(self, t) is evaluated and returned.

If None, self is returned.

pub fn set(self, id: NodeIndex<u32>, ui_cell: &'a mut UiCell<'b>) -> Self::Event[src]

Note: There should be no need to override this method.

After building the widget, you call this method to set its current state into the given Ui. More precisely, the following will occur when calling this method:

  • The widget’s previous state and style will be retrieved.
  • The widget’s current Style will be retrieved (from the Widget::style method).
  • The widget’s state will be updated (using the Widget::udpate method).
  • If the widget’s state or style has changed, the Ui will be notified that the widget needs to be re-drawn.
  • The new State and Style will be cached within the Ui.
Loading content...

Implementors

impl Widget for BorderedRectangle[src]

type State = State

type Style = Style

type Event = ()

pub fn update(
    self,
    args: UpdateArgs<'_, '_, '_, '_, BorderedRectangle>
) -> <BorderedRectangle as Widget>::Event[src]

Update the state of the Rectangle.

impl Widget for Image[src]

type State = State

type Style = Style

type Event = ()

impl Widget for Line[src]

type State = State

type Style = Style

type Event = ()

pub fn update(
    self,
    args: UpdateArgs<'_, '_, '_, '_, Line>
) -> <Line as Widget>::Event[src]

Update the state of the Line.

impl Widget for Matrix[src]

type State = State

type Style = Style

type Event = Elements

pub fn update(
    self,
    args: UpdateArgs<'_, '_, '_, '_, Matrix>
) -> <Matrix as Widget>::Event[src]

Update the state of the Matrix.

impl Widget for Rectangle[src]

type State = State

type Style = Style

type Event = ()

pub fn update(
    self,
    args: UpdateArgs<'_, '_, '_, '_, Rectangle>
) -> <Rectangle as Widget>::Event[src]

Update the state of the Rectangle.

impl Widget for RoundedRectangle[src]

type State = State

type Style = Style

type Event = ()

pub fn update(
    self,
    args: UpdateArgs<'_, '_, '_, '_, RoundedRectangle>
) -> <RoundedRectangle as Widget>::Event[src]

Update the state of the Rectangle.

impl<'a> Widget for DirectoryView<'a>[src]

type State = State

type Style = Style

type Event = Vec<Event, Global>

impl<'a> Widget for Button<'a, Flat>[src]

type State = FlatIds

type Style = Style

type Event = TimesClicked

pub fn update(
    self,
    args: UpdateArgs<'_, '_, '_, '_, Button<'a, Flat>>
) -> <Button<'a, Flat> as Widget>::Event[src]

Update the state of the Button.

impl<'a> Widget for Button<'a, Image>[src]

type State = ImageIds

type Style = Style

type Event = TimesClicked

pub fn update(
    self,
    args: UpdateArgs<'_, '_, '_, '_, Button<'a, Image>>
) -> <Button<'a, Image> as Widget>::Event[src]

Update the state of the Button.

impl<'a> Widget for Canvas<'a>[src]

type State = State

type Style = Style

type Event = ()

pub fn drag_area(
    &self,
    dim: [f64; 2],
    style: &Style,
    theme: &Theme
) -> Option<Rect>[src]

The title bar area at which the Canvas can be clicked and dragged.

Note: the position of the returned Rect should be relative to the center of the widget.

pub fn kid_area(&self, args: KidAreaArgs<'_, Canvas<'a>>) -> KidArea[src]

The area of the widget below the title bar, upon which child widgets will be placed.

pub fn update(self, args: UpdateArgs<'_, '_, '_, '_, Canvas<'a>>)[src]

Update the state of the Canvas.

impl<'a> Widget for CollapsibleArea<'a>[src]

type State = State

type Style = Style

type Event = (Option<Area>, Option<Event>)

impl<'a> Widget for FileNavigator<'a>[src]

type State = State

type Style = Style

type Event = Vec<Event, Global>

pub fn update(
    self,
    args: UpdateArgs<'_, '_, '_, '_, FileNavigator<'a>>
) -> <FileNavigator<'a> as Widget>::Event[src]

Update the state of the Button.

impl<'a> Widget for Tabs<'a>[src]

type State = State

type Style = Style

type Event = ()

pub fn kid_area(&self, args: KidAreaArgs<'_, Tabs<'a>>) -> KidArea[src]

The area on which child widgets will be placed when using the Place Positionable methods.

pub fn update(self, args: UpdateArgs<'_, '_, '_, '_, Tabs<'a>>)[src]

Update the state of the Tabs.

impl<'a> Widget for Text<'a>[src]

type State = State

type Style = Style

type Event = ()

pub fn default_x_dimension(&self, ui: &Ui) -> Dimension[src]

If no specific width was given, we’ll use the width of the widest line as a default.

The Font used by the Text is retrieved in order to determine the width of each line. If the font used by the Text cannot be found, a dimension of Absolute(0.0) is returned.

pub fn default_y_dimension(&self, ui: &Ui) -> Dimension[src]

If no specific height was given, we’ll use the total height of the text as a default.

The Font used by the Text is retrieved in order to determine the width of each line. If the font used by the Text cannot be found, a dimension of Absolute(0.0) is returned.

pub fn update(
    self,
    args: UpdateArgs<'_, '_, '_, '_, Text<'a>>
) -> <Text<'a> as Widget>::Event[src]

Update the state of the Text.

impl<'a> Widget for TextBox<'a>[src]

type State = State

type Style = Style

type Event = Vec<Event, Global>

pub fn update(
    self,
    args: UpdateArgs<'_, '_, '_, '_, TextBox<'a>>
) -> <TextBox<'a> as Widget>::Event[src]

Update the state of the TextEdit.

impl<'a> Widget for TextEdit<'a>[src]

type State = State

type Style = Style

type Event = Option<String>

pub fn update(
    self,
    args: UpdateArgs<'_, '_, '_, '_, TextEdit<'a>>
) -> <TextEdit<'a> as Widget>::Event[src]

Update the state of the TextEdit.

impl<'a> Widget for TitleBar<'a>[src]

type State = State

type Style = Style

type Event = ()

impl<'a> Widget for Toggle<'a>[src]

type State = State

type Style = Style

type Event = TimesClicked

pub fn update(
    self,
    args: UpdateArgs<'_, '_, '_, '_, Toggle<'a>>
) -> <Toggle<'a> as Widget>::Event[src]

Update the state of the Toggle.

impl<'a, E> Widget for EnvelopeEditor<'a, E> where
    E: EnvelopePoint, [src]

type State = State

type Style = Style

type Event = Vec<Event<E>, Global>

pub fn update(
    self,
    args: UpdateArgs<'_, '_, '_, '_, EnvelopeEditor<'a, E>>
) -> <EnvelopeEditor<'a, E> as Widget>::Event[src]

Update the EnvelopeEditor in accordance to the latest input and call the given react function if necessary.

impl<'a, N, E> Widget for Graph<'a, N, E> where
    E: Iterator<Item = (NodeSocket<<N as Iterator>::Item>, NodeSocket<<N as Iterator>::Item>)>,
    N: Iterator,
    <N as Iterator>::Item: NodeId, [src]

type State = State<<N as Iterator>::Item>

type Style = Style

type Event = SessionEvents<<N as Iterator>::Item>

impl<'a, T> Widget for DropDownList<'a, T> where
    T: AsRef<str>, [src]

type State = State

type Style = Style

type Event = Option<usize>

pub fn update(
    self,
    args: UpdateArgs<'_, '_, '_, '_, DropDownList<'a, T>>
) -> <DropDownList<'a, T> as Widget>::Event[src]

Update the state of the DropDownList.

impl<'a, T> Widget for NumberDialer<'a, T> where
    T: Float + NumCast + ToString, [src]

type State = State

type Style = Style

type Event = Option<T>

pub fn update(
    self,
    args: UpdateArgs<'_, '_, '_, '_, NumberDialer<'a, T>>
) -> <NumberDialer<'a, T> as Widget>::Event[src]

Update the state of the NumberDialer.

impl<'a, T> Widget for RangeSlider<'a, T> where
    T: Float, [src]

type State = State

type Style = Style

type Event = Event<T>

pub fn update(
    self,
    args: UpdateArgs<'_, '_, '_, '_, RangeSlider<'a, T>>
) -> <RangeSlider<'a, T> as Widget>::Event[src]

Update the state of the range slider.

impl<'a, T> Widget for Slider<'a, T> where
    T: Float + NumCast + ToPrimitive, [src]

type State = State

type Style = Style

type Event = Option<T>

pub fn update(
    self,
    args: UpdateArgs<'_, '_, '_, '_, Slider<'a, T>>
) -> <Slider<'a, T> as Widget>::Event[src]

Update the state of the Slider.

impl<'a, X, Y> Widget for XYPad<'a, X, Y> where
    X: Float + ToString + Debug + Any,
    Y: Float + ToString + Debug + Any, [src]

type State = State

type Style = Style

type Event = Option<(X, Y)>

pub fn update(
    self,
    args: UpdateArgs<'_, '_, '_, '_, XYPad<'a, X, Y>>
) -> <XYPad<'a, X, Y> as Widget>::Event[src]

Update the XYPad’s cached state.

impl<A> Widget for Scrollbar<A> where
    A: Axis, [src]

type State = State

type Style = Style

type Event = ()

impl<D, S> Widget for List<D, S> where
    S: ItemSize,
    D: Direction, [src]

type State = State

type Style = Style

type Event = (Items<D, S>, Option<Scrollbar<<D as Direction>::Axis>>)

impl<I> Widget for PointPath<I> where
    I: IntoIterator<Item = [f64; 2]>, [src]

type State = State

type Style = Style

type Event = ()

pub fn update(
    self,
    args: UpdateArgs<'_, '_, '_, '_, PointPath<I>>
) -> <PointPath<I> as Widget>::Event[src]

Update the state of the Line.

impl<I> Widget for Polygon<I> where
    I: IntoIterator<Item = [f64; 2]>, [src]

type State = State

type Style = Style

type Event = ()

pub fn update(
    self,
    args: UpdateArgs<'_, '_, '_, '_, Polygon<I>>
) -> <Polygon<I> as Widget>::Event[src]

Update the state of the Polygon.

impl<M, D, S> Widget for ListSelect<M, D, S> where
    M: Mode,
    S: ItemSize,
    D: Direction, [src]

type State = State

type Style = Style

type Event = (Events<M, D, S>, Option<Scrollbar<<D as Direction>::Axis>>)

pub fn update(
    self,
    args: UpdateArgs<'_, '_, '_, '_, ListSelect<M, D, S>>
) -> <ListSelect<M, D, S> as Widget>::Event[src]

Update the state of the ListSelect.

impl<S> Widget for Oval<S> where
    S: OvalSection, [src]

type State = State<S>

type Style = Style

type Event = ()

impl<S, I> Widget for Triangles<S, I> where
    S: Style,
    I: IntoIterator<Item = Triangle<<S as Style>::Vertex>>, [src]

type State = State<Vec<Triangle<<S as Style>::Vertex>, Global>>

type Style = S

type Event = ()

impl<W> Widget for Node<W> where
    W: Widget, [src]

type State = State

type Style = Style

type Event = Event<<W as Widget>::Event>

impl<X, Y, F> Widget for PlotPath<X, Y, F> where
    F: FnMut(X) -> Y,
    X: NumCast + Clone,
    Y: NumCast + Clone, [src]

type State = State

type Style = Style

type Event = ()

pub fn update(
    self,
    args: UpdateArgs<'_, '_, '_, '_, PlotPath<X, Y, F>>
) -> <PlotPath<X, Y, F> as Widget>::Event[src]

Update the state of the PlotPath.

impl<X, Y, I> Widget for Grid<X, Y, I> where
    I: Iterator<Item = Axis<X, Y>>,
    X: Into<f64>,
    Y: Into<f64>, [src]

type State = State

type Style = Style

type Event = ()

pub fn update(
    self,
    args: UpdateArgs<'_, '_, '_, '_, Grid<X, Y, I>>
) -> <Grid<X, Y, I> as Widget>::Event[src]

Update the state of the PlotPath.

Loading content...