Trait conrod::Widget
[−]
[src]
pub trait Widget: Sized { type State: Any + PartialEq + Debug; type Style: Style; fn common(&self) -> &CommonBuilder; fn common_mut(&mut self) -> &mut CommonBuilder; fn unique_kind(&self) -> Kind; fn init_state(&self) -> Self::State; fn style(&self) -> Self::Style; fn update<B: Backend>(self, args: UpdateArgs<Self, B>); fn default_x_position<B: Backend>(&self, ui: &Ui<B>) -> Position { ... } fn default_y_position<B: Backend>(&self, ui: &Ui<B>) -> Position { ... } fn default_x_dimension<B: Backend>(&self, ui: &Ui<B>) -> Dimension { ... } fn default_y_dimension<B: Backend>(&self, ui: &Ui<B>) -> Dimension { ... } 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, parent_idx: I) -> Self { ... } fn no_parent(self) -> Self { ... } fn place_on_kid_area(self, b: bool) -> Self { ... } fn graphics_for<I: Into<Index>>(self, idx: I) -> Self { ... } fn floating(self, is_floating: bool) -> Self { ... } fn crop_kids(self) -> Self { ... } fn scroll_kids(self) -> Self { ... } fn scroll_kids_vertically(self) -> Self { ... } fn scroll_kids_horizontally(self) -> Self { ... } fn and<F>(self, build: F) -> Self where F: FnOnce(Self) -> Self { ... } fn and_mut<F>(self, mutate: F) -> Self where F: FnOnce(&mut Self) { ... } fn and_if<F>(self, cond: bool, build: F) -> Self where F: FnOnce(Self) -> Self { ... } fn and_then<T, F>(self, maybe: Option<T>, build: F) -> Self where F: FnOnce(Self, T) -> Self { ... } fn set<'a, 'b, I, B>(self, idx: I, ui_cell: &'a mut UiCell<'b, B>) where I: Into<Index>, B: Backend { ... } }
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
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 + PartialEq + Debug
State to be stored within the Ui
s 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
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
, frame_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
, 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
).
These types are often quite similar and can involve a lot of boilerplate when written by
hand due to rust's lack of field inheritance. To get around this, conrod provides
widget_style!
- a macro that vastly simplifies the definition and implementation of
widget Style
types.
Conrod doesn't yet support serializing widget styling with the Theme
type, but we hope to
soon.
Examples
/// Unique styling for a Button widget. pub struct Style { /// Color of the Button's pressable area. pub color: Option<Color>, /// Width of the frame surrounding the button. pub frame: Option<Scalar>, /// The color of the Button's rectangular frame. pub frame_color: Option<Color>, /// The color of the Button's label. pub label_color: Option<Color>, /// The font size for the Button's label. pub label_font_size: Option<FontSize>, }
Note: It is recommended that you don't write these types yourself as it can get tedious.
Instead, we suggest using the widget_style!
macro which also provides all necessary
style retrieval method implementations.
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) -> Kind
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 we need to re-draw the widget.
fn update<B: Backend>(self, args: UpdateArgs<Self, B>)
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
- idx - The
Widget
's unique index (whetherPublic
orInternal
). - 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 forUiCell
for more details.
Provided Methods
fn default_x_position<B: Backend>(&self, ui: &Ui<B>) -> Position
The default Position for the widget along the x axis.
This is used when no Position is explicitly given when instantiating the Widget.
fn default_y_position<B: Backend>(&self, ui: &Ui<B>) -> Position
The default Position for the widget along the y axis.
This is used when no Position is explicitly given when instantiating the Widget.
fn default_x_dimension<B: Backend>(&self, ui: &Ui<B>) -> Dimension
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.
fn default_y_dimension<B: Backend>(&self, ui: &Ui<B>) -> Dimension
The default height of the widget.
By default, this simply calls default_dimension with a fallback absolute dimension of 0.0.
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 and 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, parent_idx: 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 no_parent(self) -> Self
Specify that this widget has no parent widgets.
fn place_on_kid_area(self, b: bool) -> Self
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.
fn graphics_for<I: Into<Index>>(self, idx: I) -> Self
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.
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 crop_kids(self) -> Self
Indicates that all widgets who are children of this widget should be cropped to the
kid_area
of this widget.
fn scroll_kids(self) -> Self
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.
fn scroll_kids_vertically(self) -> Self
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.
fn scroll_kids_horizontally(self) -> 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.
This method calls Widget::crop_kids
internally.
fn and<F>(self, build: F) -> Self where F: FnOnce(Self) -> Self
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.
fn and_mut<F>(self, mutate: F) -> Self where F: FnOnce(&mut Self)
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.
fn and_if<F>(self, cond: bool, build: F) -> Self where F: FnOnce(Self) -> Self
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.
fn and_then<T, F>(self, maybe: Option<T>, build: F) -> Self where F: FnOnce(Self, T) -> Self
A method that optionally builds the the Widget with the given build
function.
If maybe
is Some(t)
, build(self, t)
is evaluated and returned.
If None
, self
is returned.
fn set<'a, 'b, I, B>(self, idx: I, ui_cell: &'a mut UiCell<'b, B>) where I: Into<Index>, B: Backend
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
.
Implementors
impl Widget for Line
impl<T> Widget for Image<T> where T: Any + ImageSize
impl<I> Widget for PointPath<I> where I: IntoIterator<Item=Point>
impl Widget for Oval
impl<I> Widget for Polygon<I> where I: IntoIterator<Item=Point>
impl Widget for Rectangle
impl Widget for FramedRectangle
impl<'a> Widget for Text<'a>
impl<'a, F> Widget for Button<'a, F> where F: FnOnce()
impl<'a> Widget for Canvas<'a>
impl<'a, F> Widget for DropDownList<'a, F> where F: FnMut(&mut Option<Idx>, Idx, &str)
impl<'a, E, F> Widget for EnvelopeEditor<'a, E, F> where E: EnvelopePoint, E::X: Any, E::Y: Any, F: FnMut(&mut Vec<E>, usize)
impl<'a, F> Widget for FileNavigator<'a, F> where F: FnMut(Event)
impl<'a, F, W> Widget for Matrix<F> where W: Widget, F: FnMut(WidgetNum, ColNum, RowNum) -> W
impl<'a, T, F> Widget for NumberDialer<'a, T, F> where F: FnOnce(T), T: Any + Debug + Float + NumCast + ToString
impl<X, Y, F> Widget for PlotPath<X, Y, F> where X: NumCast + Clone, Y: NumCast + Clone, F: FnMut(X) -> Y
impl<'a, T, F> Widget for RangeSlider<'a, T, F> where F: FnMut(Edge, T), T: Float + NumCast + ToPrimitive
impl<A> Widget for Scrollbar<A> where A: Axis
impl<'a, T, F> Widget for Slider<'a, T, F> where F: FnOnce(T), T: Float + NumCast + ToPrimitive
impl<'a> Widget for Tabs<'a>
impl<'a, F> Widget for TextBox<'a, F> where F: FnMut(&mut String)
impl<'a, F> Widget for TextEdit<'a, F> where F: FnMut(&mut String)
impl<'a> Widget for TitleBar<'a>
impl<'a, F> Widget for Toggle<'a, F> where F: FnOnce(bool)
impl<'a, X, Y, F> Widget for XYPad<'a, X, Y, F> where X: Float + ToString + Debug + Any, Y: Float + ToString + Debug + Any, F: FnOnce(X, Y)