gtktooltip.sgml

This GTK+ version 2.12.3. GTK+ is a multi-platform toolkit for creating graphical user interfaces.

<!-- ##### SECTION Title ##### -->
GtkTooltip

<!-- ##### SECTION Short_Description ##### -->
Add tips to your widgets

<!-- ##### SECTION Long_Description ##### -->
<para>
#GtkTooltip belongs to the new tooltips API that was
introduced in GTK+ 2.12 and which deprecates the old
#GtkTooltips API. 
</para>
<para>
Basic tooltips can be realized simply by using gtk_widget_set_tooltip_text()
or gtk_widget_set_tooltip_markup() without any explicit tooltip object. 
</para>

<para>
When you need a tooltip with a little more fancy contents, like
adding an image, or you want the tooltip to have different contents
per GtkTreeView row or cell, you will have to do a little more work:
<itemizedlist>

<listitem><para>
Set the #GtkWidget:has-tooltip property to %TRUE, this will
make GTK+ monitor the widget for motion and related events
which are needed to determine when and where to show a tooltip.
</para></listitem>

<listitem><para>
Connect to the #GtkWidget::query-tooltip signal.  This signal
will be emitted when a tooltip is supposed to be shown. One
of the arguments passed to the signal handler is a #GtkTooltip
object. This is the object that we are about to display as a 
tooltip, and can be manipulated in your callback using functions
like gtk_tooltip_set_icon(). There are functions for setting
the tooltip's markup, setting an image from a stock icon, or
even putting in a custom widget.
</para></listitem>

<listitem><para>
Return %TRUE from your query-tooltip handler. This causes
the tooltip to be show. If you return %FALSE, it will not be shown. 
</para></listitem>
</itemizedlist>
</para>

<para>
In the probably rare case where you want to have even more control
over the tooltip that is about to be shown, you can set your own
#GtkWindow which will be used as tooltip window.  This works as
follows:
<itemizedlist>

<listitem><para>
Set #GtkWidget:has-tooltip and connect to #GtkWidget::query-tooltip as 
before.
</para></listitem>

<listitem><para>
Use gtk_widget_set_tooltip_window() to set a #GtkWindow created
by you as tooltip window.
</para></listitem>

<listitem><para>
In the ::query-tooltip callback you can access your window
using gtk_widget_get_tooltip_window() and manipulate as you
wish. The semantics of the return value are exactly as before,
return %TRUE to show the window, %FALSE to not show it.
</para></listitem>
</itemizedlist>
</para>

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### STRUCT GtkTooltip ##### -->
<para>

</para>


<!-- ##### FUNCTION gtk_tooltip_set_markup ##### -->
<para>

</para>

@tooltip: 
@markup: 


<!-- ##### FUNCTION gtk_tooltip_set_text ##### -->
<para>

</para>

@tooltip: 
@text: 


<!-- ##### FUNCTION gtk_tooltip_set_icon ##### -->
<para>

</para>

@tooltip: 
@pixbuf: 


<!-- ##### FUNCTION gtk_tooltip_set_icon_from_stock ##### -->
<para>

</para>

@tooltip: 
@stock_id: 
@size: 


<!-- ##### FUNCTION gtk_tooltip_set_custom ##### -->
<para>

</para>

@tooltip: 
@custom_widget: 


<!-- ##### FUNCTION gtk_tooltip_trigger_tooltip_query ##### -->
<para>

</para>

@display: 


<!-- ##### FUNCTION gtk_tooltip_set_tip_area ##### -->
<para>

</para>

@tooltip: 
@rect: