dear_imgui_rs/widget/
tooltip.rs

1//! Tooltips
2//!
3//! Tooltip helpers with automatic lifetime management via tokens and
4//! convenient `with_tooltip` patterns.
5//!
6#![allow(
7    clippy::cast_possible_truncation,
8    clippy::cast_sign_loss,
9    clippy::as_conversions
10)]
11use crate::input::MouseButton;
12use crate::sys;
13use crate::ui::Ui;
14
15/// # Tooltip Widgets
16impl Ui {
17    /// Construct a tooltip window that can have any kind of content.
18    ///
19    /// Typically used with `Ui::is_item_hovered()` or some other conditional check.
20    ///
21    /// # Examples
22    ///
23    /// ```no_run
24    /// # use dear_imgui_rs::*;
25    /// # let mut ctx = Context::create();
26    /// # let ui = ctx.frame();
27    /// ui.text("Hover over me");
28    /// if ui.is_item_hovered() {
29    ///     ui.tooltip(|| {
30    ///         ui.text_colored([1.0, 0.0, 0.0, 1.0], "I'm red!");
31    ///     });
32    /// }
33    /// ```
34    #[doc(alias = "BeginTooltip", alias = "EndTooltip")]
35    pub fn tooltip<F: FnOnce()>(&self, f: F) {
36        if let Some(_token) = self.begin_tooltip() {
37            f();
38        }
39    }
40
41    /// Construct a tooltip window that can have any kind of content.
42    ///
43    /// Returns a `TooltipToken` that must be ended by calling `.end()` or by dropping.
44    #[doc(alias = "BeginTooltip")]
45    pub fn begin_tooltip(&self) -> Option<TooltipToken<'_>> {
46        if self.run_with_bound_context(|| unsafe { sys::igBeginTooltip() }) {
47            Some(TooltipToken::new(self))
48        } else {
49            None
50        }
51    }
52
53    /// Shortcut to call [`Self::tooltip`] with simple text content.
54    ///
55    /// # Examples
56    ///
57    /// ```no_run
58    /// # use dear_imgui_rs::*;
59    /// # let mut ctx = Context::create();
60    /// # let ui = ctx.frame();
61    /// ui.text("Hover over me");
62    /// if ui.is_item_hovered() {
63    ///     ui.tooltip_text("I'm a tooltip!");
64    /// }
65    /// ```
66    #[doc(alias = "BeginTooltip", alias = "EndTooltip", alias = "SetTooltip")]
67    pub fn tooltip_text(&self, text: impl AsRef<str>) {
68        self.tooltip(|| self.text(text));
69    }
70
71    /// Sets a tooltip with simple text content.
72    ///
73    /// This renders unformatted text (no `%`-style formatting) and avoids calling C variadic APIs.
74    #[doc(alias = "SetTooltip")]
75    pub fn set_tooltip(&self, text: impl AsRef<str>) {
76        let s = text.as_ref();
77        self.run_with_bound_context(|| unsafe {
78            // Avoid calling C variadic APIs: build a tooltip window and render unformatted text.
79            if sys::igBeginTooltip() {
80                let begin = s.as_ptr() as *const std::os::raw::c_char;
81                let end = begin.add(s.len());
82                sys::igTextUnformatted(begin, end);
83                sys::igEndTooltip();
84            }
85        });
86    }
87
88    /// Sets a tooltip with formatted text content.
89    #[doc(alias = "SetTooltip")]
90    pub fn set_tooltip_formatted(&self, text: impl AsRef<str>) {
91        self.set_tooltip(text);
92    }
93
94    /// Sets a tooltip for the last item with simple text content.
95    ///
96    /// Uses the non-variadic `BeginItemTooltip` path and renders unformatted text.
97    #[doc(alias = "SetItemTooltip")]
98    pub fn set_item_tooltip(&self, text: impl AsRef<str>) {
99        let s = text.as_ref();
100        self.run_with_bound_context(|| unsafe {
101            // Prefer the non-variadic ImGui 1.9x+ API when available.
102            if sys::igBeginItemTooltip() {
103                let begin = s.as_ptr() as *const std::os::raw::c_char;
104                let end = begin.add(s.len());
105                sys::igTextUnformatted(begin, end);
106                sys::igEndTooltip();
107            }
108        });
109    }
110}
111
112/// # Item/Widget Utilities and Query Functions
113impl Ui {
114    /// Returns true if the last item is being hovered by mouse (and usable).
115    /// This is typically used to show tooltips.
116    #[doc(alias = "IsItemHovered")]
117    pub fn is_item_hovered(&self) -> bool {
118        self.run_with_bound_context(|| unsafe {
119            sys::igIsItemHovered(crate::ItemHoveredFlags::NONE.bits())
120        })
121    }
122
123    /// Returns true if the last item is being hovered by mouse with specific flags.
124    #[doc(alias = "IsItemHovered")]
125    pub fn is_item_hovered_with_flags(&self, flags: crate::ItemHoveredFlags) -> bool {
126        crate::utils::validate_item_hovered_flags("Ui::is_item_hovered_with_flags()", flags);
127        self.run_with_bound_context(|| unsafe { sys::igIsItemHovered(flags.bits()) })
128    }
129
130    /// Returns true if the last item is active (e.g. button being held, text field being edited).
131    #[doc(alias = "IsItemActive")]
132    pub fn is_item_active(&self) -> bool {
133        self.run_with_bound_context(|| unsafe { sys::igIsItemActive() })
134    }
135
136    /// Returns true if the last item is focused (e.g. text input field).
137    #[doc(alias = "IsItemFocused")]
138    pub fn is_item_focused(&self) -> bool {
139        self.run_with_bound_context(|| unsafe { sys::igIsItemFocused() })
140    }
141
142    /// Returns true if the last item was just clicked.
143    #[doc(alias = "IsItemClicked")]
144    pub fn is_item_clicked(&self) -> bool {
145        self.run_with_bound_context(|| unsafe {
146            sys::igIsItemClicked(crate::input::MouseButton::Left as i32)
147        })
148    }
149
150    /// Returns true if the last item was clicked with specific mouse button.
151    #[doc(alias = "IsItemClicked")]
152    pub fn is_item_clicked_with_button(&self, mouse_button: MouseButton) -> bool {
153        self.run_with_bound_context(|| unsafe { sys::igIsItemClicked(mouse_button as i32) })
154    }
155
156    /// Returns true if the last item is visible (not clipped).
157    #[doc(alias = "IsItemVisible")]
158    pub fn is_item_visible(&self) -> bool {
159        self.run_with_bound_context(|| unsafe { sys::igIsItemVisible() })
160    }
161
162    /// Returns true if the last item was just made active (e.g. button was pressed).
163    #[doc(alias = "IsItemActivated")]
164    pub fn is_item_activated(&self) -> bool {
165        self.run_with_bound_context(|| unsafe { sys::igIsItemActivated() })
166    }
167
168    /// Returns true if the last item was just made inactive (e.g. button was released).
169    #[doc(alias = "IsItemDeactivated")]
170    pub fn is_item_deactivated(&self) -> bool {
171        self.run_with_bound_context(|| unsafe { sys::igIsItemDeactivated() })
172    }
173
174    /// Returns true if the last item was just made inactive and was edited.
175    #[doc(alias = "IsItemDeactivatedAfterEdit")]
176    pub fn is_item_deactivated_after_edit(&self) -> bool {
177        self.run_with_bound_context(|| unsafe { sys::igIsItemDeactivatedAfterEdit() })
178    }
179
180    /// Returns true if the last item was edited.
181    ///
182    /// This is typically used to detect value changes for widgets.
183    #[doc(alias = "IsItemEdited")]
184    pub fn is_item_edited(&self) -> bool {
185        self.run_with_bound_context(|| unsafe { sys::igIsItemEdited() })
186    }
187
188    /// Returns true if any item is active.
189    #[doc(alias = "IsAnyItemActive")]
190    pub fn is_any_item_active(&self) -> bool {
191        self.run_with_bound_context(|| unsafe { sys::igIsAnyItemActive() })
192    }
193
194    /// Returns true if any item is focused.
195    #[doc(alias = "IsAnyItemFocused")]
196    pub fn is_any_item_focused(&self) -> bool {
197        self.run_with_bound_context(|| unsafe { sys::igIsAnyItemFocused() })
198    }
199
200    /// Returns true if any item is hovered.
201    #[doc(alias = "IsAnyItemHovered")]
202    pub fn is_any_item_hovered(&self) -> bool {
203        self.run_with_bound_context(|| unsafe { sys::igIsAnyItemHovered() })
204    }
205
206    /// Gets the bounding rectangle of the last item in screen space.
207    #[doc(alias = "GetItemRectMin", alias = "GetItemRectMax")]
208    pub fn item_rect(&self) -> ([f32; 2], [f32; 2]) {
209        let (min, max) = self.run_with_bound_context(|| unsafe {
210            (sys::igGetItemRectMin(), sys::igGetItemRectMax())
211        });
212        ([min.x, min.y], [max.x, max.y])
213    }
214
215    /// Gets the size of the last item.
216    #[doc(alias = "GetItemRectSize")]
217    pub fn item_rect_size(&self) -> [f32; 2] {
218        let size = self.run_with_bound_context(|| unsafe { sys::igGetItemRectSize() });
219        [size.x, size.y]
220    }
221
222    /// Returns the ImGui ID of the last item.
223    #[doc(alias = "GetItemID")]
224    pub fn item_id(&self) -> crate::Id {
225        self.run_with_bound_context(|| unsafe { crate::Id::from(sys::igGetItemID()) })
226    }
227}
228
229/// Tracks a tooltip that can be ended by calling `.end()` or by dropping
230#[must_use]
231pub struct TooltipToken<'ui> {
232    _ui: &'ui Ui,
233}
234
235impl<'ui> TooltipToken<'ui> {
236    /// Creates a new tooltip token
237    fn new(ui: &'ui Ui) -> Self {
238        TooltipToken { _ui: ui }
239    }
240
241    /// Ends the tooltip
242    pub fn end(self) {
243        // The drop implementation will handle the actual ending
244    }
245}
246
247impl<'ui> Drop for TooltipToken<'ui> {
248    fn drop(&mut self) {
249        self._ui
250            .run_with_bound_context(|| unsafe { sys::igEndTooltip() });
251    }
252}
dear_imgui_rs/widget/tooltip.rs

dear_imgui_rs/widget/
tooltip.rs
