gtk/auto/tooltip.rs
1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4
5use crate::{IconSize, Widget};
6use glib::{prelude::*, translate::*};
7use std::fmt;
8
9glib::wrapper! {
10 /// Basic tooltips can be realized simply by using [`WidgetExt::set_tooltip_text()`][crate::prelude::WidgetExt::set_tooltip_text()]
11 /// or [`WidgetExt::set_tooltip_markup()`][crate::prelude::WidgetExt::set_tooltip_markup()] without any explicit tooltip object.
12 ///
13 /// When you need a tooltip with a little more fancy contents, like adding an
14 /// image, or you want the tooltip to have different contents per [`TreeView`][crate::TreeView]
15 /// row or cell, you will have to do a little more work:
16 ///
17 /// - Set the [`has-tooltip`][struct@crate::Widget#has-tooltip] property to [`true`], this will make GTK+
18 /// monitor the widget for motion and related events which are needed to
19 /// determine when and where to show a tooltip.
20 ///
21 /// - Connect to the [`query-tooltip`][struct@crate::Widget#query-tooltip] signal. This signal will be
22 /// emitted when a tooltip is supposed to be shown. One of the arguments passed
23 /// to the signal handler is a GtkTooltip object. This is the object that we
24 /// are about to display as a tooltip, and can be manipulated in your callback
25 /// using functions like [`set_icon()`][Self::set_icon()]. There are functions for setting
26 /// the tooltip’s markup, setting an image from a named icon, or even putting in
27 /// a custom widget.
28 ///
29 /// Return [`true`] from your query-tooltip handler. This causes the tooltip to be
30 /// show. If you return [`false`], it will not be shown.
31 ///
32 /// In the probably rare case where you want to have even more control over the
33 /// tooltip that is about to be shown, you can set your own [`Window`][crate::Window] which
34 /// will be used as tooltip window. This works as follows:
35 ///
36 /// - Set [`has-tooltip`][struct@crate::Widget#has-tooltip] and connect to [`query-tooltip`][struct@crate::Widget#query-tooltip] as before.
37 /// Use [`WidgetExt::set_tooltip_window()`][crate::prelude::WidgetExt::set_tooltip_window()] to set a [`Window`][crate::Window] created by you as
38 /// tooltip window.
39 ///
40 /// - In the [`query-tooltip`][struct@crate::Widget#query-tooltip] callback you can access your window using
41 /// [`WidgetExt::tooltip_window()`][crate::prelude::WidgetExt::tooltip_window()] and manipulate as you wish. The semantics of
42 /// the return value are exactly as before, return [`true`] to show the window,
43 /// [`false`] to not show it.
44 ///
45 /// # Implements
46 ///
47 /// [`trait@glib::ObjectExt`]
48 #[doc(alias = "GtkTooltip")]
49 pub struct Tooltip(Object<ffi::GtkTooltip>);
50
51 match fn {
52 type_ => || ffi::gtk_tooltip_get_type(),
53 }
54}
55
56impl Tooltip {
57 /// Replaces the widget packed into the tooltip with
58 /// `custom_widget`. `custom_widget` does not get destroyed when the tooltip goes
59 /// away.
60 /// By default a box with a [`Image`][crate::Image] and [`Label`][crate::Label] is embedded in
61 /// the tooltip, which can be configured using [`set_markup()`][Self::set_markup()]
62 /// and [`set_icon()`][Self::set_icon()].
63 /// ## `custom_widget`
64 /// a [`Widget`][crate::Widget], or [`None`] to unset the old custom widget.
65 #[doc(alias = "gtk_tooltip_set_custom")]
66 pub fn set_custom(&self, custom_widget: Option<&impl IsA<Widget>>) {
67 unsafe {
68 ffi::gtk_tooltip_set_custom(
69 self.to_glib_none().0,
70 custom_widget.map(|p| p.as_ref()).to_glib_none().0,
71 );
72 }
73 }
74
75 /// Sets the icon of the tooltip (which is in front of the text) to be
76 /// `pixbuf`. If `pixbuf` is [`None`], the image will be hidden.
77 /// ## `pixbuf`
78 /// a [`gdk_pixbuf::Pixbuf`][crate::gdk_pixbuf::Pixbuf], or [`None`]
79 #[doc(alias = "gtk_tooltip_set_icon")]
80 pub fn set_icon(&self, pixbuf: Option<&gdk_pixbuf::Pixbuf>) {
81 unsafe {
82 ffi::gtk_tooltip_set_icon(self.to_glib_none().0, pixbuf.to_glib_none().0);
83 }
84 }
85
86 /// Sets the icon of the tooltip (which is in front of the text)
87 /// to be the icon indicated by `gicon` with the size indicated
88 /// by `size`. If `gicon` is [`None`], the image will be hidden.
89 /// ## `gicon`
90 /// a [`gio::Icon`][crate::gio::Icon] representing the icon, or [`None`]
91 /// ## `size`
92 /// a stock icon size ([`IconSize`][crate::IconSize])
93 #[doc(alias = "gtk_tooltip_set_icon_from_gicon")]
94 pub fn set_icon_from_gicon(&self, gicon: Option<&impl IsA<gio::Icon>>, size: IconSize) {
95 unsafe {
96 ffi::gtk_tooltip_set_icon_from_gicon(
97 self.to_glib_none().0,
98 gicon.map(|p| p.as_ref()).to_glib_none().0,
99 size.into_glib(),
100 );
101 }
102 }
103
104 /// Sets the icon of the tooltip (which is in front of the text) to be
105 /// the icon indicated by `icon_name` with the size indicated
106 /// by `size`. If `icon_name` is [`None`], the image will be hidden.
107 /// ## `icon_name`
108 /// an icon name, or [`None`]
109 /// ## `size`
110 /// a stock icon size ([`IconSize`][crate::IconSize])
111 #[doc(alias = "gtk_tooltip_set_icon_from_icon_name")]
112 pub fn set_icon_from_icon_name(&self, icon_name: Option<&str>, size: IconSize) {
113 unsafe {
114 ffi::gtk_tooltip_set_icon_from_icon_name(
115 self.to_glib_none().0,
116 icon_name.to_glib_none().0,
117 size.into_glib(),
118 );
119 }
120 }
121
122 /// Sets the text of the tooltip to be `markup`, which is marked up
123 /// with the [Pango text markup language][PangoMarkupFormat].
124 /// If `markup` is [`None`], the label will be hidden.
125 /// ## `markup`
126 /// a markup string (see [Pango markup format][PangoMarkupFormat]) or [`None`]
127 #[doc(alias = "gtk_tooltip_set_markup")]
128 pub fn set_markup(&self, markup: Option<&str>) {
129 unsafe {
130 ffi::gtk_tooltip_set_markup(self.to_glib_none().0, markup.to_glib_none().0);
131 }
132 }
133
134 /// Sets the text of the tooltip to be `text`. If `text` is [`None`], the label
135 /// will be hidden. See also [`set_markup()`][Self::set_markup()].
136 /// ## `text`
137 /// a text string or [`None`]
138 #[doc(alias = "gtk_tooltip_set_text")]
139 pub fn set_text(&self, text: Option<&str>) {
140 unsafe {
141 ffi::gtk_tooltip_set_text(self.to_glib_none().0, text.to_glib_none().0);
142 }
143 }
144
145 /// Sets the area of the widget, where the contents of this tooltip apply,
146 /// to be `rect` (in widget coordinates). This is especially useful for
147 /// properly setting tooltips on [`TreeView`][crate::TreeView] rows and cells, `GtkIconViews`,
148 /// etc.
149 ///
150 /// For setting tooltips on [`TreeView`][crate::TreeView], please refer to the convenience
151 /// functions for this: [`TreeViewExt::set_tooltip_row()`][crate::prelude::TreeViewExt::set_tooltip_row()] and
152 /// [`TreeViewExt::set_tooltip_cell()`][crate::prelude::TreeViewExt::set_tooltip_cell()].
153 /// ## `rect`
154 /// a [`gdk::Rectangle`][crate::gdk::Rectangle]
155 #[doc(alias = "gtk_tooltip_set_tip_area")]
156 pub fn set_tip_area(&self, rect: &gdk::Rectangle) {
157 unsafe {
158 ffi::gtk_tooltip_set_tip_area(self.to_glib_none().0, rect.to_glib_none().0);
159 }
160 }
161
162 /// Triggers a new tooltip query on `display`, in order to update the current
163 /// visible tooltip, or to show/hide the current tooltip. This function is
164 /// useful to call when, for example, the state of the widget changed by a
165 /// key press.
166 /// ## `display`
167 /// a [`gdk::Display`][crate::gdk::Display]
168 #[doc(alias = "gtk_tooltip_trigger_tooltip_query")]
169 pub fn trigger_tooltip_query(display: &gdk::Display) {
170 assert_initialized_main_thread!();
171 unsafe {
172 ffi::gtk_tooltip_trigger_tooltip_query(display.to_glib_none().0);
173 }
174 }
175}
176
177impl fmt::Display for Tooltip {
178 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
179 f.write_str("Tooltip")
180 }
181}