Struct thyme::WidgetBuilder

pub struct WidgetBuilder<'a> { /* fields omitted */ }

A WidgetBuilder is used to customize widgets within your UI tree, following a builder pattern.

Although there are several convenience methods on Frame for simple buttons, labels, etc, widgets with more complex behavior will usually be created via Frame.start and then customized using the methods here. Note also that many methods here have an equivalent in the widget's theme definition.

Each method here takes the WidgetBuilder by value, modifies it, and then returns it, allowing you to use a builder pattern. The window method will transform this into a WindowBuilder, while the finish and children methods will complete the widget and add it to the frame's widget tree.

Implementations

impl<'a> WidgetBuilder<'a>

#[must_use]pub fn new_render_group(self) -> WidgetBuilder<'a>

Specifies that this widget and its children should be part of a new Render Group. Render groups are used to handle cases where widgets may overlap, and determine input routing and draw order in those cases. If your UI doesn't have moveable elements such as windows, you should generally be ok to draw your entire UI in one render group, with the exception of modal popups. Windows make use of render groups.

#[must_use]pub fn wants_mouse(self, wants_mouse: bool) -> WidgetBuilder<'a>

Sets whether this widget will interact with the mouse. By default, widgets will not interact with the mouse, so this is set to true for buttons and similar. This may also be specified in the widget's theme.

#[must_use]pub fn wants_scroll(self, wants_scroll: bool) -> WidgetBuilder<'a>

Sets whether this widget will receive mouse scrollwheel events. By default, widgets will not receive scroll wheel events, so this is set to true for scrollpanes. This may also be specified in the widget's theme.

#[must_use]pub fn id<T: Into<String>>(self, id: T) -> WidgetBuilder<'a>

Sets an id for this widget. This id is used internally to associate the widget with its PersistentState. You will need to specify an id if you want to make changes to the PersistentState. Otherwise, Thyme can usually generate a unique internal ID for most elements.

#[must_use]pub fn initially_open(self, open: bool) -> WidgetBuilder<'a>

Specify whether this widget is initially open, or visible. By default, widgets are initially open. If set to false, the widget will not be shown until it is set to open using one of the methods on Frame to modify its PersistentState.

#[must_use]pub fn text_color(self, color: Color) -> WidgetBuilder<'a>

Specify a Color for the text of this widget to display. The default color is white. This may also be specified in the widget's theme.

#[must_use]pub fn text_align(self, align: Align) -> WidgetBuilder<'a>

Specify the alignment of the widget's text within the widget's inner area, as defined by its overall size and border. This may also be specified in the widget's theme.

#[must_use]pub fn text<T: Into<String>>(self, text: T) -> WidgetBuilder<'a>

Specify text to display for this widget. The widget must have a font specified to render text. This may also be specified in the widget's theme.

#[must_use]pub fn font(self, font: &str) -> WidgetBuilder<'a>

Specify a font for any text rendered by this widget. A widget must have a font specified to render text. The font must be registered in the theme's font definitions. This may also be specified in the widget's theme.

#[must_use]pub fn foreground(self, fg: &str) -> WidgetBuilder<'a>

Specify a foreground image for this widget. The image ID, fg must be registered in the theme's image definitions. The ID consists of "{image_set_id}/{image_id}". Foreground images are drawn below text but above the background. This may also be specified in the widget's theme.

#[must_use]pub fn background(self, bg: &str) -> WidgetBuilder<'a>

Specify a background image for this widget. The image ID, bg must be registered in the theme's image definitions. The ID consists of "{image_set_id}/{image_id}". Background images are drawn below text and any children. This may also be specified in the widget's theme.

#[must_use]pub fn child_align(self, align: Align) -> WidgetBuilder<'a>

Specifies the default alignment of children added to this widget. See Align. This may be overridden by the child, either in the theme or by calling align. This may also be specified in the widget's theme.

#[must_use]pub fn layout_spacing(self, spacing: Point) -> WidgetBuilder<'a>

Specifies the spacing, in logical pixels, to use between children that are laid out in this widget. This may also be specified in the widget's theme.

#[must_use]pub fn layout_horizontal(self) -> WidgetBuilder<'a>

Specifies that the children of this widget should be laid out vertically. See Layout. This may also be specified in the widget's theme.

#[must_use]pub fn layout_vertical(self) -> WidgetBuilder<'a>

Specifies that the children of this widget should be laid out vertically. See Layout. This may also be specified in the widget's theme.

#[must_use]pub fn layout(self, layout: Layout) -> WidgetBuilder<'a>

Specifies the layout for children of this widget. See Layout. This may also be specified in the widget's theme.

#[must_use]pub fn screen_pos(self, x: f32, y: f32) -> WidgetBuilder<'a>

Manually specify a position for this widget, basedon the specified x and y logical pixel positions. This position ignores alignment or any other considerations.

#[must_use]pub fn pos(self, x: f32, y: f32) -> WidgetBuilder<'a>

Specify the position of the widget, with respect to its alignment within the parent. The x and `` values are in logical pixels. See align. This may also be specified in the widget's theme.

#[must_use]pub fn align(self, align: Align) -> WidgetBuilder<'a>

Specify the alignment of this widget with respect to its parent. See Align. This may also be specified in the widget's theme.

#[must_use]pub fn border(self, border: Border) -> WidgetBuilder<'a>

Specify the widget's border size, which determines the inner size of the widget relative to its size. See Border. This may also be specified in the widget's theme.

#[must_use]pub fn size(self, x: f32, y: f32) -> WidgetBuilder<'a>

Specify the widget's size in logical pixels. This may or may not be an absolute size, depending on WidthRelative and HeightRelative This may also be specified in the widget's theme.

#[must_use]pub fn width_from(self, from: WidthRelative) -> WidgetBuilder<'a>

Specify how to compute the widget's width from its size. See WidthRelative. This may also be specified in the widget's theme. You may also specify this using size_from.

#[must_use]pub fn height_from(self, from: HeightRelative) -> WidgetBuilder<'a>

Specify how to compute the widget's height from its size. See HeightRelative This may also be specified in the widget's theme. You may also specify this using size_from.

#[must_use]pub fn size_from(
    self,
    width_from: WidthRelative,
    height_from: HeightRelative
) -> WidgetBuilder<'a>

Specify how to compute the widget's height and width from its size. See WidthRelative and HeightRelative. This may also be specified in the widget's theme. You may also specify this using width_from and height_from

#[must_use]pub fn clip(self, clip: Rect) -> WidgetBuilder<'a>

Sets the widget's clip Rectangle. By default, a widget will have a clip rectangle set from its size and position, calculated based on the theme and the various methods such as size, pos, width_from, height_from, etc. You can override that behavior with this method. This is useful to display part of an image, such as in a progress bar, or to limit the size of child content, such as in a scrollpane. Widgets always inherit their clip as the minimum extent of their parent's clip and their own clip. See Rect.min.

#[must_use]pub fn unclip(self) -> WidgetBuilder<'a>

Removes all constraints from the widget's clip Rectangle. This will allow the widget to render outside of its parent's area. See clip

#[must_use]pub fn unparent(self) -> WidgetBuilder<'a>

If called, the current parent widget will not treat this widget as a child for the purposes of computing its child bounds. This is useful for popups and similar which are not neccesarily children of the widgets that create them. You usually will also want unclip and new_render_group.

#[must_use]pub fn active(self, active: bool) -> WidgetBuilder<'a>

Sets whether the widget's AnimState will include the active AnimStateKey.

#[must_use]pub fn visible(self, visible: bool) -> WidgetBuilder<'a>

Sets whether this widget will be visible. If the widget is not visible, it will not be shown and any child closures (such as passed in children) will not be run.

#[must_use]pub fn enabled(self, enabled: bool) -> WidgetBuilder<'a>

Sets whether this widget will be enabled. If the widget is not enabled, it will not interact with any user input.

#[must_use]pub fn trigger_layout(self, rect: &mut Rect) -> WidgetBuilder<'a>

Force the widget to layout its size and position immediately. Assuming these attributes are not changed after this method is called, these attributes will have their final values after this method returns. The size and position are written to the passed in Rect.

#[must_use]pub fn trigger_layout_inner(self, rect: &mut Rect) -> WidgetBuilder<'a>

Force the widget to layout its size and position immediately. Assuming these attributes are not changed after this is method is called, they will have their final values after this method returns. The inner size and position (size and position adjusted by the Border are written to the passed in Rect

#[must_use]pub fn trigger_text_layout(self, cursor: &mut Point) -> WidgetBuilder<'a>

Causes this widget to layout its current text. The final position of the text cursor is written into pos. If this widget does not have a font or has no text, nothing is written into pos.

#[must_use]pub fn window(self, id: &str) -> WindowBuilder<'a>

Turns this builder into a WindowBuilder. You should use all WidgetBuilder methods before calling this method. The window must still be completed with one of the WindowBuilder methods. You must pass a unique id for each window created by your application.

#[must_use]pub fn scrollpane(self, content_id: &str) -> ScrollpaneBuilder<'a>

Turns this builder into a ScrollpaneBuilder. You should use all WidgetBuilder methods before calling this method. The scrollpane must still be completed with one of the methods on ScrollpaneBuilder. You must pass a unique content_id for the scrollpane's content.

pub fn finish(self) -> WidgetState

Consumes the builder and adds a widget to the current frame. The returned data includes information about the animation state and mouse interactions of the created element. If you wish this widget to have one or more child widgets, you should call children instead.

pub fn children<F: FnOnce(&mut Frame)>(self, f: F) -> WidgetState

Consumes the builder and adds a widget to the current frame. The returned data includes information about the animation state and mouse interactions of the created element. The provided closure is called to enable adding children to this widget. If you don't want to add children, you can just call finish instead.