Trait conrod::Widget [−] [src]

pub trait Widget: Sized {
    type State: Any + PartialEq + Debug;
    type Style: Any + PartialEq + Debug;
    fn common(&self) -> &CommonBuilder;
    fn common_mut(&mut self) -> &mut CommonBuilder;
    fn unique_kind(&self) -> &'static str;
    fn init_state(&self) -> Self::State;
    fn style(&self) -> Self::Style;
    fn update<C: CharacterCache>(self, args: UpdateArgs<Self, C>);
    fn draw<C: CharacterCache>(args: DrawArgs<Self, C>) -> Element;

    fn default_position(&self, _theme: &Theme) -> Position { ... }
    fn default_h_align(&self, theme: &Theme) -> HorizontalAlign { ... }
    fn default_v_align(&self, theme: &Theme) -> VerticalAlign { ... }
    fn default_width<C: CharacterCache>(&self, _theme: &Theme, _: &GlyphCache<C>) -> Scalar { ... }
    fn default_height(&self, _theme: &Theme) -> Scalar { ... }
    fn drag_area(&self, _dim: Dimensions, _style: &Self::Style, _theme: &Theme) -> Option<Rect> { ... }
    fn kid_area<C: CharacterCache>(&self, args: KidAreaArgs<Self, C>) -> KidArea { ... }
    fn parent<I: Into<Index>>(self, maybe_parent_idx: Option<I>) -> Self { ... }
    fn floating(self, is_floating: bool) -> Self { ... }
    fn scrolling(self, scrollable: bool) -> Self { ... }
    fn vertical_scrolling(self, scrollable: bool) -> Self { ... }
    fn horizontal_scrolling(self, scrollable: bool) -> Self { ... }
    fn set<I, U>(self, idx: I, ui: &mut U) where I: Into<Index>, U: UiRefMut { ... }
}

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: - common - common_mut - unique_kind - init_state - style - update - draw

Methods that can be optionally overridden: - default_position - default_width - default_height - default_h_align - default_v_align

Methods that should not be overridden: - parent - set

Associated Types

type State: Any + PartialEq + Debug

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 and draw. Conrod will never clone the state, it will only ever be moved.

type Style: Any + PartialEq + Debug

Styling used by the widget to construct an Element. Styling is useful to have in its own abstraction in order to making Theme serializing easier. Conrod doesn't yet support serializing non-internal widget styling with the Theme type, but we hope to soon.

Required Methods

fn common(&self) -> &CommonBuilder

Return a reference to a CommonBuilder struct owned by the Widget. This method allows us to do a blanket impl of Positionable and Sizeable for T: Widget.

Note: When rust introduces field inheritance, we will move the CommonBuilder accordingly (perhaps under a different name).

fn common_mut(&mut self) -> &mut CommonBuilder

Return a mutable reference to a CommonBuilder struct owned by the Widget. This method allows us to do a blanket impl of Positionable and Sizeable for T: Widget.

Note: When rust introduces field inheritance, we will move the CommonBuilder accordingly (perhaps under a different name).

fn unique_kind(&self) -> &'static str

Return the kind of the widget as a &'static str.

Note that this must be unique from all other widgets' "unique kinds".

This is used by conrod to help avoid WidgetId errors and to provide better messages for those that do occur.

fn init_state(&self) -> Self::State

Return the initial State of the Widget.

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

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

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 a new Element needs to be constructed.

fn update<C: CharacterCache>(self, args: UpdateArgs<Self, C>)

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's Element (i.e. calling Widget::draw. As a result, widget designers should only call State::update when necessary, checking whether or not the state has changed before invoking the the method. See the custom_widget.rs example for a demonstration of this.

Arguments

  • idx - 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 intial 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.

fn draw<C: CharacterCache>(args: DrawArgs<Self, C>) -> Element

Construct a renderable Element from the current styling and new state. This will only be called on the occasion that the widget's Style or State has changed. Keep this in mind when designing your widget's Style and State types.

Arguments

  • state - The current Widget::State which should contain all unique state necessary for rendering the Widget.
  • style - The current Widget::Style of the Widget.
  • theme - The currently active Theme within the Ui.
  • glyph_cache - Used for determining the size of rendered text if necessary.

Provided Methods

fn default_position(&self, _theme: &Theme) -> Position

The default Position for the widget. This is used when no Position is explicitly given when instantiating the Widget.

fn default_h_align(&self, theme: &Theme) -> HorizontalAlign

The default horizontal alignment for the widget. This is used when no HorizontalAlign is explicitly given when instantiating a Widget.

fn default_v_align(&self, theme: &Theme) -> VerticalAlign

The default vertical alignment for the widget. This is used when no VerticalAlign is explicitly given when instantiating a Widget.

fn default_width<C: CharacterCache>(&self, _theme: &Theme, _: &GlyphCache<C>) -> Scalar

The default width of the widget. A reference to the GlyphCache is provided in case the width should adjust to some text len. This method is only used if no width or dimensions are given.

fn default_height(&self, _theme: &Theme) -> Scalar

The default height of the widget. This method is only used if no height or dimensions are given.

fn drag_area(&self, _dim: Dimensions, _style: &Self::Style, _theme: &Theme) -> Option<Rect>

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

fn kid_area<C: CharacterCache>(&self, args: KidAreaArgs<Self, C>) -> KidArea

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

fn parent<I: Into<Index>>(self, maybe_parent_idx: Option<I>) -> Self

Set the parent widget for this Widget by passing the WidgetId of the parent. This will attach this Widget to the parent widget.

fn floating(self, is_floating: bool) -> Self

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.

fn scrolling(self, scrollable: bool) -> Self

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.

fn vertical_scrolling(self, scrollable: bool) -> Self

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.

fn horizontal_scrolling(self, scrollable: bool) -> Self

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.

fn set<I, U>(self, idx: I, ui: &mut U) where I: Into<Index>, U: UiRefMut

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, Widget::draw will be called to create the new Element for rendering. - The new State, Style and Element (if there is one) will be cached within the Ui.

Implementors