pub struct Response {
pub ctx: Context,
pub layer_id: LayerId,
pub id: Id,
pub rect: Rect,
pub interact_rect: Rect,
pub sense: Sense,
/* private fields */
}
Expand description
The result of adding a widget to a Ui
.
A Response
lets you know whether or not a widget is being hovered, clicked or dragged.
It also lets you easily show a tooltip on hover.
Whenever something gets added to a Ui
, a Response
object is returned.
[ui.add
] returns a Response
, as does [ui.button
], and all similar shortcuts.
⚠️ The Response
contains a clone of Context
, and many methods lock the Context
.
It can therefor be a deadlock to use Context
from within a context-locking closures,
such as Context::input
.
Fields§
§ctx: Context
Used for optionally showing a tooltip and checking for more interactions.
layer_id: LayerId
Which layer the widget is part of.
id: Id
The Id
of the widget/area this response pertains.
rect: Rect
The area of the screen we are talking about.
interact_rect: Rect
The rectangle sensing interaction.
This is sometimes smaller than Self::rect
because of clipping
(e.g. when inside a scroll area).
sense: Sense
The senses (click and/or drag) that the widget was interested in (if any).
Note: if Self::enabled
is false
, then
the widget effectively doesn’t sense anything,
but can still have the same Sense
.
This is because the sense informs the styling of the widget,
but we don’t want to change the style when a widget is disabled
(that is handled by the Painter
directly).
Implementations§
source§impl Response
impl Response
sourcepub fn clicked(&self) -> bool
pub fn clicked(&self) -> bool
Returns true if this widget was clicked this frame by the primary button.
A click is registered when the mouse or touch is released within a certain amount of time and distance from when and where it was pressed.
This will also return true if the widget was clicked via accessibility integration, or if the widget had keyboard focus and the use pressed Space/Enter.
Note that the widget must be sensing clicks with Sense::click
.
crate::Button
senses clicks; crate::Label
does not (unless you call crate::Label::sense
).
You can use Self::interact
to sense more things after adding a widget.
sourcepub fn clicked_by(&self, button: PointerButton) -> bool
pub fn clicked_by(&self, button: PointerButton) -> bool
Returns true if this widget was clicked this frame by the given mouse button.
This will NOT return true if the widget was “clicked” via
some accessibility integration, or if the widget had keyboard focus and the
user pressed Space/Enter. For that, use Self::clicked
instead.
This will likewise ignore the press-and-hold action on touch screens.
Use Self::secondary_clicked
instead to also detect that.
sourcepub fn secondary_clicked(&self) -> bool
pub fn secondary_clicked(&self) -> bool
Returns true if this widget was clicked this frame by the secondary mouse button (e.g. the right mouse button).
This also returns true if the widget was pressed-and-held on a touch screen.
sourcepub fn long_touched(&self) -> bool
pub fn long_touched(&self) -> bool
Was this long-pressed on a touch screen?
Usually you want to check Self::secondary_clicked
instead.
sourcepub fn middle_clicked(&self) -> bool
pub fn middle_clicked(&self) -> bool
Returns true if this widget was clicked this frame by the middle mouse button.
sourcepub fn double_clicked(&self) -> bool
pub fn double_clicked(&self) -> bool
Returns true if this widget was double-clicked this frame by the primary button.
sourcepub fn triple_clicked(&self) -> bool
pub fn triple_clicked(&self) -> bool
Returns true if this widget was triple-clicked this frame by the primary button.
sourcepub fn double_clicked_by(&self, button: PointerButton) -> bool
pub fn double_clicked_by(&self, button: PointerButton) -> bool
Returns true if this widget was double-clicked this frame by the given button.
sourcepub fn triple_clicked_by(&self, button: PointerButton) -> bool
pub fn triple_clicked_by(&self, button: PointerButton) -> bool
Returns true if this widget was triple-clicked this frame by the given button.
sourcepub fn clicked_elsewhere(&self) -> bool
pub fn clicked_elsewhere(&self) -> bool
true
if there was a click outside the rect of this widget.
Clicks on widgets contained in this one counts as clicks inside this widget, so that clicking a button in an area will not be considered as clicking “elsewhere” from the area.
sourcepub fn enabled(&self) -> bool
pub fn enabled(&self) -> bool
Was the widget enabled? If false, there was no interaction attempted and the widget should be drawn in a gray disabled look.
sourcepub fn hovered(&self) -> bool
pub fn hovered(&self) -> bool
The pointer is hovering above this widget or the widget was clicked/tapped this frame.
In contrast to Self::contains_pointer
, this will be false
whenever some other widget is being dragged.
hovered
is always false
for disabled widgets.
sourcepub fn contains_pointer(&self) -> bool
pub fn contains_pointer(&self) -> bool
Returns true if the pointer is contained by the response rect, and no other widget is covering it.
In contrast to Self::hovered
, this can be true
even if some other widget is being dragged.
This means it is useful for styling things like drag-and-drop targets.
contains_pointer
can also be true
for disabled widgets.
This is slightly different from Ui::rect_contains_pointer
and Context::rect_contains_pointer
, in that
Self::contains_pointer
also checks that no other widget is covering this response rectangle.
sourcepub fn has_focus(&self) -> bool
pub fn has_focus(&self) -> bool
This widget has the keyboard focus (i.e. is receiving key presses).
This function only returns true if the UI as a whole (e.g. window) also has the keyboard focus. That makes this function suitable for style choices, e.g. a thicker border around focused widgets.
sourcepub fn gained_focus(&self) -> bool
pub fn gained_focus(&self) -> bool
True if this widget has keyboard focus this frame, but didn’t last frame.
sourcepub fn lost_focus(&self) -> bool
pub fn lost_focus(&self) -> bool
The widget had keyboard focus and lost it,
either because the user pressed tab or clicked somewhere else,
or (in case of a crate::TextEdit
) because the user pressed enter.
let response = ui.text_edit_singleline(&mut my_text);
if response.lost_focus() && ui.input(|i| i.key_pressed(egui::Key::Enter)) {
do_request(&my_text);
}
sourcepub fn request_focus(&self)
pub fn request_focus(&self)
Request that this widget get keyboard focus.
sourcepub fn surrender_focus(&self)
pub fn surrender_focus(&self)
Surrender keyboard focus for this widget.
sourcepub fn drag_started(&self) -> bool
pub fn drag_started(&self) -> bool
Did a drag on this widgets begin this frame?
This is only true if the widget sense drags. If the widget also senses clicks, this will only become true if the pointer has moved a bit.
This will only be true for a single frame.
sourcepub fn drag_started_by(&self, button: PointerButton) -> bool
pub fn drag_started_by(&self, button: PointerButton) -> bool
Did a drag on this widgets by the button begin this frame?
This is only true if the widget sense drags. If the widget also senses clicks, this will only become true if the pointer has moved a bit.
This will only be true for a single frame.
sourcepub fn dragged(&self) -> bool
pub fn dragged(&self) -> bool
The widget is being dragged.
To find out which button(s), use Self::dragged_by
.
If the widget is only sensitive to drags, this is true
as soon as the pointer presses down on it.
If the widget is also sensitive to drags, this won’t be true until the pointer has moved a bit,
or the user has pressed down for long enough.
See crate::input_state::PointerState::is_decidedly_dragging
for details.
If you want to avoid the delay, use Self::is_pointer_button_down_on
instead.
If the widget is NOT sensitive to drags, this will always be false
.
crate::DragValue
senses drags; crate::Label
does not (unless you call crate::Label::sense
).
You can use Self::interact
to sense more things after adding a widget.
sourcepub fn dragged_by(&self, button: PointerButton) -> bool
pub fn dragged_by(&self, button: PointerButton) -> bool
See Self::dragged
.
sourcepub fn drag_stopped(&self) -> bool
pub fn drag_stopped(&self) -> bool
The widget was being dragged, but now it has been released.
sourcepub fn drag_stopped_by(&self, button: PointerButton) -> bool
pub fn drag_stopped_by(&self, button: PointerButton) -> bool
The widget was being dragged by the button, but now it has been released.
sourcepub fn drag_released(&self) -> bool
👎Deprecated: Renamed ‘drag_stopped’
pub fn drag_released(&self) -> bool
The widget was being dragged, but now it has been released.
sourcepub fn drag_released_by(&self, button: PointerButton) -> bool
👎Deprecated: Renamed ‘drag_stopped_by’
pub fn drag_released_by(&self, button: PointerButton) -> bool
The widget was being dragged by the button, but now it has been released.
sourcepub fn drag_delta(&self) -> Vec2
pub fn drag_delta(&self) -> Vec2
If dragged, how many points were we dragged and in what direction?
sourcepub fn drag_motion(&self) -> Vec2
pub fn drag_motion(&self) -> Vec2
If dragged, how far did the mouse move?
This will use raw mouse movement if provided by the integration, otherwise will fall back to Response::drag_delta
Raw mouse movement is unaccelerated and unclamped by screen boundaries, and does not relate to any position on the screen.
This may be useful in certain situations such as draggable values and 3D cameras, where screen position does not matter.
sourcepub fn dnd_set_drag_payload<Payload: Any + Send + Sync>(&self, payload: Payload)
pub fn dnd_set_drag_payload<Payload: Any + Send + Sync>(&self, payload: Payload)
If the user started dragging this widget this frame, store the payload for drag-and-drop.
sourcepub fn dnd_hover_payload<Payload: Any + Send + Sync>(
&self,
) -> Option<Arc<Payload>>
pub fn dnd_hover_payload<Payload: Any + Send + Sync>( &self, ) -> Option<Arc<Payload>>
Drag-and-Drop: Return what is being held over this widget, if any.
Only returns something if Self::contains_pointer
is true,
and the user is drag-dropping something of this type.
sourcepub fn dnd_release_payload<Payload: Any + Send + Sync>(
&self,
) -> Option<Arc<Payload>>
pub fn dnd_release_payload<Payload: Any + Send + Sync>( &self, ) -> Option<Arc<Payload>>
Drag-and-Drop: Return what is being dropped onto this widget, if any.
Only returns something if Self::contains_pointer
is true,
the user is drag-dropping something of this type,
and they released it this frame
sourcepub fn interact_pointer_pos(&self) -> Option<Pos2>
pub fn interact_pointer_pos(&self) -> Option<Pos2>
Where the pointer (mouse/touch) were when when this widget was clicked or dragged.
None
if the widget is not being interacted with.
sourcepub fn hover_pos(&self) -> Option<Pos2>
pub fn hover_pos(&self) -> Option<Pos2>
If it is a good idea to show a tooltip, where is pointer?
None if the pointer is outside the response area.
Is the pointer button currently down on this widget?
This is true if the pointer is pressing down or dragging a widget, even when dragging outside the widget.
This could also be thought of as “is this widget being interacted with?”.
sourcepub fn changed(&self) -> bool
pub fn changed(&self) -> bool
Was the underlying data changed?
e.g. the slider was dragged, text was entered in a TextEdit
etc.
Always false
for something like a Button
.
Can sometimes be true
even though the data didn’t changed
(e.g. if the user entered a character and erased it the same frame).
This is not set if the view of the data was changed.
For instance, moving the cursor in a TextEdit
does not set this to true
.
sourcepub fn mark_changed(&mut self)
pub fn mark_changed(&mut self)
Report the data shown by this widget changed.
This must be called by widgets that represent some mutable data, e.g. checkboxes, sliders etc.
This should be called when the content changes, but not when the view does.
So we call this when the text of a crate::TextEdit
, but not when the cursors changes.
sourcepub fn on_hover_ui(self, add_contents: impl FnOnce(&mut Ui)) -> Self
pub fn on_hover_ui(self, add_contents: impl FnOnce(&mut Ui)) -> Self
Show this UI if the widget was hovered (i.e. a tooltip).
The text will not be visible if the widget is not enabled.
For that, use Self::on_disabled_hover_ui
instead.
If you call this multiple times the tooltips will stack underneath the previous ones.
The widget can contain interactive widgets, such as buttons and links.
If so, it will stay open as the user moves their pointer over it.
By default, the text of a tooltip is NOT selectable (i.e. interactive),
but you can change this by setting [style::Interaction::selectable_labels
from within the tooltip:
ui.label("Hover me").on_hover_ui(|ui| {
ui.style_mut().interaction.selectable_labels = true;
ui.label("This text can be selected");
});
sourcepub fn on_disabled_hover_ui(self, add_contents: impl FnOnce(&mut Ui)) -> Self
pub fn on_disabled_hover_ui(self, add_contents: impl FnOnce(&mut Ui)) -> Self
Show this UI when hovering if the widget is disabled.
sourcepub fn on_hover_ui_at_pointer(self, add_contents: impl FnOnce(&mut Ui)) -> Self
pub fn on_hover_ui_at_pointer(self, add_contents: impl FnOnce(&mut Ui)) -> Self
Like on_hover_ui
, but show the ui next to cursor.
sourcepub fn show_tooltip_ui(&self, add_contents: impl FnOnce(&mut Ui))
pub fn show_tooltip_ui(&self, add_contents: impl FnOnce(&mut Ui))
Always show this tooltip, even if disabled and the user isn’t hovering it.
This can be used to give attention to a widget during a tutorial.
sourcepub fn show_tooltip_text(&self, text: impl Into<WidgetText>)
pub fn show_tooltip_text(&self, text: impl Into<WidgetText>)
Always show this tooltip, even if disabled and the user isn’t hovering it.
This can be used to give attention to a widget during a tutorial.
sourcepub fn is_tooltip_open(&self) -> bool
pub fn is_tooltip_open(&self) -> bool
Was the tooltip open last frame?
fn should_show_hover_ui(&self) -> bool
sourcepub fn on_hover_text_at_pointer(self, text: impl Into<WidgetText>) -> Self
pub fn on_hover_text_at_pointer(self, text: impl Into<WidgetText>) -> Self
Like on_hover_text
, but show the text next to cursor.
sourcepub fn on_hover_text(self, text: impl Into<WidgetText>) -> Self
pub fn on_hover_text(self, text: impl Into<WidgetText>) -> Self
Show this text if the widget was hovered (i.e. a tooltip).
The text will not be visible if the widget is not enabled.
For that, use Self::on_disabled_hover_text
instead.
If you call this multiple times the tooltips will stack underneath the previous ones.
sourcepub fn highlight(self) -> Self
pub fn highlight(self) -> Self
Highlight this widget, to make it look like it is hovered, even if it isn’t.
The highlight takes one frame to take effect if you call this after the widget has been fully rendered.
See also Context::highlight_widget
.
sourcepub fn on_disabled_hover_text(self, text: impl Into<WidgetText>) -> Self
pub fn on_disabled_hover_text(self, text: impl Into<WidgetText>) -> Self
Show this text when hovering if the widget is disabled.
sourcepub fn on_hover_cursor(self, cursor: CursorIcon) -> Self
pub fn on_hover_cursor(self, cursor: CursorIcon) -> Self
When hovered, use this icon for the mouse cursor.
sourcepub fn on_hover_and_drag_cursor(self, cursor: CursorIcon) -> Self
pub fn on_hover_and_drag_cursor(self, cursor: CursorIcon) -> Self
When hovered or dragged, use this icon for the mouse cursor.
sourcepub fn interact(&self, sense: Sense) -> Self
pub fn interact(&self, sense: Sense) -> Self
Sense more interactions (e.g. sense clicks on a Response
returned from a label).
The interaction will occur on the same plane as the original widget, i.e. if the response was from a widget behind button, the interaction will also be behind that button. egui gives priority to the last added widget (the one on top gets clicked first).
Note that this call will not add any hover-effects to the widget, so when possible
it is better to give the widget a Sense
instead, e.g. using crate::Label::sense
.
Using this method on a Response
that is the result of calling union
on multiple Response
s
is undefined behavior.
let horiz_response = ui.horizontal(|ui| {
ui.label("hello");
}).response;
assert!(!horiz_response.clicked()); // ui's don't sense clicks by default
let horiz_response = horiz_response.interact(egui::Sense::click());
if horiz_response.clicked() {
// The background behind the label was clicked
}
sourcepub fn scroll_to_me(&self, align: Option<Align>)
pub fn scroll_to_me(&self, align: Option<Align>)
Adjust the scroll position until this UI becomes visible.
If align
is Align::TOP
it means “put the top of the rect at the top of the scroll area”, etc.
If align
is None
, it’ll scroll enough to bring the UI into view.
See also: Ui::scroll_to_cursor
, Ui::scroll_to_rect
. Ui::scroll_with_delta
.
egui::ScrollArea::vertical().show(ui, |ui| {
for i in 0..1000 {
let response = ui.button("Scroll to me");
if response.clicked() {
response.scroll_to_me(Some(egui::Align::Center));
}
}
});
sourcepub fn widget_info(&self, make_info: impl Fn() -> WidgetInfo)
pub fn widget_info(&self, make_info: impl Fn() -> WidgetInfo)
For accessibility.
Call after interacting and potential calls to Self::mark_changed
.
pub fn output_event(&self, event: OutputEvent)
sourcepub fn labelled_by(self, id: Id) -> Self
pub fn labelled_by(self, id: Id) -> Self
Associate a label with a control for accessibility.
§Example
ui.horizontal(|ui| {
let label = ui.label("Your name: ");
ui.text_edit_singleline(&mut text).labelled_by(label.id);
});
Response to secondary clicks (right-clicks) by showing the given menu.
Make sure the widget senses clicks (e.g. crate::Button
does, crate::Label
does not).
let response = ui.add(Label::new("Right-click me!").sense(Sense::click()));
response.context_menu(|ui| {
if ui.button("Close the menu").clicked() {
ui.close_menu();
}
});
See also: Ui::menu_button
and Ui::close_menu
.
Returns whether a context menu is currently open for this widget.
See Self::context_menu
.
sourcepub fn paint_debug_info(&self)
pub fn paint_debug_info(&self)
Draw a debug rectangle over the response displaying the response’s id and whether it is enabled and/or hovered.
This function is intended for debugging purpose and can be useful, for example, in case of widget id instability.
Color code:
- Blue: Enabled but not hovered
- Green: Enabled and hovered
- Red: Disabled
source§impl Response
impl Response
sourcepub fn union(&self, other: Self) -> Self
pub fn union(&self, other: Self) -> Self
A logical “or” operation.
For instance a.union(b).hovered
means “was either a or b hovered?”.
The resulting Self::id
will come from the first (self
) argument.
You may not call Self::interact
on the resulting Response
.
source§impl Response
impl Response
sourcepub fn with_new_rect(self, rect: Rect) -> Self
pub fn with_new_rect(self, rect: Rect) -> Self
Returns a response with a modified Self::rect
.
Trait Implementations§
source§impl BitOr for Response
impl BitOr for Response
See Response::union
.
To summarize the response from many widgets you can use this pattern:
use egui::*;
fn draw_vec2(ui: &mut Ui, v: &mut Vec2) -> Response {
ui.add(DragValue::new(&mut v.x)) | ui.add(DragValue::new(&mut v.y))
}
Now draw_vec2(ui, foo).hovered
is true if either DragValue
were hovered.
source§impl BitOrAssign for Response
impl BitOrAssign for Response
See Response::union
.
To summarize the response from many widgets you can use this pattern:
let mut response = ui.add(widget_a);
response |= ui.add(widget_b);
response |= ui.add(widget_c);
if response.hovered() { ui.label("You hovered at least one of the widgets"); }
source§fn bitor_assign(&mut self, rhs: Self)
fn bitor_assign(&mut self, rhs: Self)
|=
operation. Read more