pub trait Tile: Layout {
Show 14 methods
// Provided methods
fn as_tile(&self) -> &dyn Tile { ... }
fn id_ref(&self) -> &Id { ... }
fn id(&self) -> Id { ... }
fn identify(&self) -> IdentifyWidget<'_> { ... }
fn navigable(&self) -> bool { ... }
fn tooltip(&self) -> Option<&str> { ... }
fn role(&self, cx: &mut dyn RoleCx) -> Role<'_> { ... }
fn role_child_properties(&self, cx: &mut dyn RoleCx, index: usize) { ... }
fn child_indices(&self) -> ChildIndices { ... }
fn get_child(&self, index: usize) -> Option<&dyn Tile> { ... }
fn find_child_index(&self, id: &Id) -> Option<usize> { ... }
fn nav_next(&self, reverse: bool, from: Option<usize>) -> Option<usize> { ... }
fn translation(&self, index: usize) -> Offset { ... }
fn probe(&self, coord: Coord) -> Id
where Self: Sized { ... }
}Expand description
A sizable, drawable, identifiable, introspectible 2D tree object
Tile is a super-trait of Widget which:
- Is a sub-trait of
Layout: is sizable and drawable - Has no
Dataparameter or event-handling methods - Has an identifier and
Self::role - Supports read-only tree reflection:
Self::child_indices,Self::get_child
Tile may not be implemented directly; it will be implemented by the
#widget macro.
§Tree reflection
Tile offers a reflection API over the widget tree via
Tile::get_child. This is limited to read-only functions, and thus
cannot directly violate the widget lifecycle, however note that the
id_ref could be invalid or could be valid but refer to a
node which has not yet been sized and positioned (and thus which it is not
valid to send events to).
Provided Methods§
Sourcefn as_tile(&self) -> &dyn Tile
fn as_tile(&self) -> &dyn Tile
Get as a dyn Tile
This method is implemented by the #[widget] macro.
Sourcefn id_ref(&self) -> &Id
fn id_ref(&self) -> &Id
Get a reference to the widget’s identifier
The widget identifier is assigned when the widget is configured (see
Events::configure and Events::configure_recurse). In case the
Id is accessed before this, it will be invalid.
The identifier may change when widgets which are descendants of some
dynamic layout are reconfigured.
This method is implemented by the #[widget] macro.
Sourcefn id(&self) -> Id
fn id(&self) -> Id
Get the widget’s identifier
This method returns a Clone of Self::id_ref. Since cloning an
Id is very cheap, this can mostly be ignored.
The widget identifier is assigned when the widget is configured (see
Events::configure and Events::configure_recurse). In case the
Id is accessed before this, it will be invalid.
The identifier may change when widgets which are descendants of some
dynamic layout are reconfigured.
Sourcefn identify(&self) -> IdentifyWidget<'_>
fn identify(&self) -> IdentifyWidget<'_>
Return a Display-able widget identifier
This method is implemented by the #[widget] macro.
Whether this widget supports navigation focus
By default this is false.
Sourcefn tooltip(&self) -> Option<&str>
fn tooltip(&self) -> Option<&str>
Tooltip
This is shown on mouse hover and may or may not use the same text as the label defined by the role.
By default this is None.
Sourcefn role(&self, cx: &mut dyn RoleCx) -> Role<'_>
fn role(&self, cx: &mut dyn RoleCx) -> Role<'_>
Describe the widget’s role
This descriptor supports accessibility tooling and UI introspection.
§Default implementation
If the widget has children with macro-defined layout, the #[widget]
macro will implement this method to return Role::None; otherwise,
the default implementation simply returns Role::Unknown.
Sourcefn role_child_properties(&self, cx: &mut dyn RoleCx, index: usize)
fn role_child_properties(&self, cx: &mut dyn RoleCx, index: usize)
Specify additional role properties for child index
Role properties (for example RoleCxExt::set_label) may be specified
by a widget for itself in Self::role or by a parent in this method.
The default implementation does nothing.
Sourcefn child_indices(&self) -> ChildIndices
fn child_indices(&self) -> ChildIndices
Get child indices available to recursion
This method returns a range of child indices for “visible” children.
These children are expected to be accessible through Self::get_child
and to be configured and sized (assuming that self is). They may
or may not be visible on the screen.
Hidden children might be excluded from this list, for example a collapsed element, closed menu or inactive stack page. (Such children might also not be configured or sized.)
This method is generated by default unless Self::get_child has an
explicit implementation. A non-default implementation may be needed when
a child should be hidden. In this case it might be necessary to write
an explicit implementation of Events::configure_recurse.
Sourcefn get_child(&self, index: usize) -> Option<&dyn Tile>
fn get_child(&self, index: usize) -> Option<&dyn Tile>
Access a child as a dyn Tile, if available
Valid index values may be discovered by calling
Tile::child_indices, Tile::find_child_index or
Tile::nav_next. The index-to-child mapping is not
required to remain fixed; use an Id to track a widget over time.
This method is usually implemented automatically by the #[widget]
macro, but must be implemented explicitly in some cases (e.g. if
children are not marked with #[widget] or #[collection]).
Sourcefn find_child_index(&self, id: &Id) -> Option<usize>
fn find_child_index(&self, id: &Id) -> Option<usize>
Find the child which is an ancestor of this id, if any
As with Self::child_indices, this method should only return
Some(index) when Self::get_child succeeds on the given index,
returning access to a child which is configured and sized (assuming that
self is). find_child_index should return None if the above
conditions would not be met, even if id identifies a known child.
The default implementation simply uses Id::next_key_after.
Widgets may choose to assign children custom keys by overriding this
method and Events::make_child_id.
Navigation in spatial order
Controls Tab navigation order of children. This method should:
- Return
Noneif there is no (next) navigable child - In the case there are navigable children and
from == None, return the index of the first (or last ifreverse) navigable child - In the case there are navigable children and
from == Some(index), it may be expected thatfromis the output of a previous call to this method; the method should return the next (or previous ifreverse) navigable child (if any)
The return value is expected to be None or Some(index) where
Self::get_child returns access to a child at the given index and
that child is configured and sized (assuming that self is).
Default (macro generated) implementation:
- Generated from
#[widget]’s layout property, if used (not always possible!) - Otherwise, iterate through children in order of definition
Sourcefn translation(&self, index: usize) -> Offset
fn translation(&self, index: usize) -> Offset
Get translation of child index relative to this widget
Usually this is zero; only widgets with scrollable or offset content
and child widgets need to implement this.
Such widgets must also implement Tile::probe and (if they scroll)
Events::handle_scroll.
Affects event handling via Tile::probe and affects the positioning
of pop-up menus. Layout::draw must be implemented directly using
DrawCx::with_clip_region to offset contents.
Default implementation: return Offset::ZERO
Sourcefn probe(&self, coord: Coord) -> Idwhere
Self: Sized,
fn probe(&self, coord: Coord) -> Idwhere
Self: Sized,
Probe a coordinate for a widget’s Id
Returns the Id of the widget expected to handle clicks and touch
events at the given coord. Typically this is the lowest descendant in
the widget tree at the given coord, but it is not required to be; e.g.
a Button may use an inner widget as a label but return its own Id
to indicate that the button (not the inner label) handles clicks.
§Calling
Prefer to call Layout::try_probe instead.
§Call order
It is expected that Layout::set_rect is called before this method,
but failure to do so should not cause a fatal error.
§Implementation
The callee may usually assume that it occupies coord and may thus
return its own Id when no child occupies the input coord.
If the Self::translation is non-zero for any child, then the
coordinate passed to that child must be translated:
coord + translation.
§Default implementation
The #[widget] macro may implement this method as:
MacroDefinedLayout::try_probe(self, coord).unwrap_or_else(|| self.id())