pub trait HasFocus {
// Required methods
fn build(&self, builder: &mut FocusBuilder);
fn focus(&self) -> FocusFlag;
fn area(&self) -> Rect;
// Provided methods
fn build_nav(&self, navigable: Navigation, builder: &mut FocusBuilder) { ... }
fn id(&self) -> usize { ... }
fn area_z(&self) -> u16 { ... }
fn navigable(&self) -> Navigation { ... }
fn is_focused(&self) -> bool { ... }
fn lost_focus(&self) -> bool { ... }
fn gained_focus(&self) -> bool { ... }
fn has_mouse_focus(&self) -> bool { ... }
}Expand description
Trait for a widget that takes part of focus handling.
When used for a simple widget implement
- build()
- focus()
- area()
and optionally
- area_z() and navigable()
use rat_focus::ratatui::layout::Rect;
use rat_focus::{FocusBuilder, FocusFlag, HasFocus};
struct MyWidgetState { pub focus: FocusFlag, pub area: Rect }
impl HasFocus for MyWidgetState {
fn build(&self, builder: &mut FocusBuilder) {
builder.leaf_widget(self);
}
fn focus(&self) -> FocusFlag {
self.focus.clone()
}
fn area(&self) -> Rect {
self.area
}
}When used for a container widget implement
- build()
use rat_focus::ratatui::layout::Rect;
use rat_focus::{FocusBuilder, FocusFlag, HasFocus};
struct MyWidgetState { pub focus: FocusFlag, pub area: Rect }
struct SomeWidgetState { pub focus: FocusFlag, pub area: Rect, pub component_a: MyWidgetState, pub component_b: MyWidgetState }
impl HasFocus for SomeWidgetState {
fn build(&self, builder: &mut FocusBuilder) {
let tag = builder.start(self);
builder.widget(&self.component_a);
builder.widget(&self.component_b);
builder.end(tag);
}
fn focus(&self) -> FocusFlag {
self.focus.clone()
}
fn area(&self) -> Rect {
self.area
}
}Creates a container with an identity.
Or
use rat_focus::ratatui::layout::Rect;
use rat_focus::{FocusBuilder, FocusFlag, HasFocus};
struct MyWidgetState { pub focus: FocusFlag, pub area: Rect }
struct SomeWidgetState { pub focus: FocusFlag, pub area: Rect, pub component_a: MyWidgetState, pub component_b: MyWidgetState }
impl HasFocus for SomeWidgetState {
fn build(&self, builder: &mut FocusBuilder) {
builder.widget(&self.component_a);
builder.widget(&self.component_b);
}
fn focus(&self) -> FocusFlag {
unimplemented!("not in use")
}
fn area(&self) -> Rect {
unimplemented!("not in use")
}
}for an anonymous container.
focus(), area() and area_z() are only used for the first case. navigable() is ignored for containers, leave it at the default.
Required Methods§
Sourcefn build(&self, builder: &mut FocusBuilder)
fn build(&self, builder: &mut FocusBuilder)
Build the focus-structure for the container/widget.
Provided Methods§
Build the focus-structure for the container/widget.
This function is called when the default navigation is overridden by calling FocusBuilder::widget_navigate. You only need to implement this function, if you have a container-widget, that wants to react to an alternate navigation.
For regular widgets this will be called too, but the overridden flag will be used by Focus, regardless of what you do. It’s only useful to get a notification of an alternate navigation.
It defaults to calling build. If you don’t have very specific requirements, you need not concern with this; just implement HasFocus::build.
Sourcefn area_z(&self) -> u16
fn area_z(&self) -> u16
Z-value for the area.
When testing for mouse interactions the z-value is taken into account.
Declares how the widget interacts with focus.
Default is Navigation::Regular.
Sourcefn is_focused(&self) -> bool
fn is_focused(&self) -> bool
Does this widget have the focus. Or, if the flag is used for a container, does any of widget inside the container have the focus.
This flag is set by [Focus::handle].
Sourcefn lost_focus(&self) -> bool
fn lost_focus(&self) -> bool
This widget just lost the focus. This flag is set by [Focus::handle] if there is a focus transfer, and will be reset by the next call to [Focus::handle].
See on_lost!
Sourcefn gained_focus(&self) -> bool
fn gained_focus(&self) -> bool
This widget just gained the focus. This flag is set by [Focus::handle] if there is a focus transfer, and will be reset by the next call to [Focus::handle].
See on_gained!
Sourcefn has_mouse_focus(&self) -> bool
fn has_mouse_focus(&self) -> bool
This flag is set by [Focus::handle], if a mouse-event matches one of the areas associated with a widget.
It searches all containers for an area-match. All matching areas will have the flag set. If an area with a higher z is found, all previously found areas are discarded.
The z value for the last container is taken as a baseline. Only widgets with a z greater or equal are considered. If multiple widget areas are matching, the last one will get the flag set.
This rules enable popup-windows with complex ui’s. The popup-container starts with a z=1 and all widgets within also get the same z. With the given rules, all widgets underneath the popup are ignored.
- This flag starts with a default
true. This allows widgets to work, even if Focus is not used. - Mouse drag events are not bound to any area. Instead, they set the mouse-focus to true for all widgets and containers.