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