<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
<!ENTITY pi "&#960;">
<!ENTITY solidus "&#8260;">
]>
<refentry id="GtkTooltip">
<refmeta>
<refentrytitle role="top_of_page" id="GtkTooltip.top_of_page">GtkTooltip</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GTK4 Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>GtkTooltip</refname>
<refpurpose>Add tips to your widgets</refpurpose>
</refnamediv>

<refsect1 id="GtkTooltip.functions" role="functions_proto">
<title role="functions_proto.title">Functions</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="functions_proto_type" colwidth="150px"/>
<colspec colname="functions_proto_name"/>
<tbody>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-tooltip-set-markup">gtk_tooltip_set_markup</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-tooltip-set-text">gtk_tooltip_set_text</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-tooltip-set-icon">gtk_tooltip_set_icon</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-tooltip-set-icon-from-icon-name">gtk_tooltip_set_icon_from_icon_name</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-tooltip-set-icon-from-gicon">gtk_tooltip_set_icon_from_gicon</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-tooltip-set-custom">gtk_tooltip_set_custom</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-tooltip-set-tip-area">gtk_tooltip_set_tip_area</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkTooltip.other" role="other_proto">
<title role="other_proto.title">Types and Values</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="other_proto_type" colwidth="150px"/>
<colspec colname="other_proto_name"/>
<tbody>
<row><entry role="datatype_keyword"></entry><entry role="function_name"><link linkend="GtkTooltip-struct">GtkTooltip</link></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkTooltip.object-hierarchy" role="object_hierarchy">
<title role="object_hierarchy.title">Object Hierarchy</title>
<screen>    <link linkend="GObject">GObject</link>
    <phrase role="lineart">&#9584;&#9472;&#9472;</phrase> GtkTooltip
</screen>
</refsect1>

<refsect1 id="GtkTooltip.includes"><title>Includes</title><synopsis>#include &lt;gtk/gtk.h&gt;
</synopsis></refsect1>

<refsect1 id="GtkTooltip.description" role="desc">
<title role="desc.title">Description</title>
<para>Basic tooltips can be realized simply by using <link linkend="gtk-widget-set-tooltip-text"><function>gtk_widget_set_tooltip_text()</function></link>
or <link linkend="gtk-widget-set-tooltip-markup"><function>gtk_widget_set_tooltip_markup()</function></link> 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 <link linkend="GtkTreeView"><type>GtkTreeView</type></link>
row or cell, you will have to do a little more work:</para>
<itemizedlist>
<listitem>
<para>Set the <link linkend="GtkWidget--has-tooltip"><type>“has-tooltip”</type></link> property to <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>, 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 <link linkend="GtkWidget-query-tooltip"><type>“query-tooltip”</type></link> 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 <link linkend="gtk-tooltip-set-icon"><function>gtk_tooltip_set_icon()</function></link>. There are functions for setting
the tooltip’s markup, setting an image from a named icon, or even putting in
a custom widget.</para>
<para>Return <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> from your query-tooltip handler. This causes the tooltip to be
show. If you return <link linkend="FALSE:CAPS"><literal>FALSE</literal></link>, it will not be shown.</para>
</listitem>
</itemizedlist>
<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 <link linkend="GtkWindow"><type>GtkWindow</type></link> which
will be used as tooltip window.  This works as follows:</para>
<itemizedlist>
<listitem>
<para>Set <link linkend="GtkWidget--has-tooltip"><type>“has-tooltip”</type></link> and connect to <link linkend="GtkWidget-query-tooltip"><type>“query-tooltip”</type></link> as before.
Use <link linkend="gtk-widget-set-tooltip-window"><function>gtk_widget_set_tooltip_window()</function></link> to set a <link linkend="GtkWindow"><type>GtkWindow</type></link> created by you as
tooltip window.</para>
</listitem>
<listitem><para>In the <link linkend="GtkWidget-query-tooltip"><type>“query-tooltip”</type></link> callback you can access your window using
<link linkend="gtk-widget-get-tooltip-window"><function>gtk_widget_get_tooltip_window()</function></link> and manipulate as you wish. The semantics of
the return value are exactly as before, return <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> to show the window,
<link linkend="FALSE:CAPS"><literal>FALSE</literal></link> to not show it.</para></listitem>
</itemizedlist>

</refsect1>
<refsect1 id="GtkTooltip.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="gtk-tooltip-set-markup" role="function">
<title>gtk_tooltip_set_markup&#160;()</title>
<indexterm zone="gtk-tooltip-set-markup"><primary>gtk_tooltip_set_markup</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_tooltip_set_markup (<parameter><link linkend="GtkTooltip"><type>GtkTooltip</type></link> *tooltip</parameter>,
                        <parameter>const <link linkend="gchar"><type>gchar</type></link> *markup</parameter>);</programlisting>
<para>Sets the text of the tooltip to be <parameter>markup</parameter>
, which is marked up
with the <link linkend="PangoMarkupFormat">Pango text markup language</link>.
If <parameter>markup</parameter>
 is <link linkend="NULL:CAPS"><literal>NULL</literal></link>, the label will be hidden.</para>
<refsect3 id="gtk-tooltip-set-markup.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>tooltip</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkTooltip"><type>GtkTooltip</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>markup</para></entry>
<entry role="parameter_description"><para>a markup string (see <link linkend="PangoMarkupFormat">Pango markup format</link>) or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-tooltip-set-text" role="function">
<title>gtk_tooltip_set_text&#160;()</title>
<indexterm zone="gtk-tooltip-set-text"><primary>gtk_tooltip_set_text</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_tooltip_set_text (<parameter><link linkend="GtkTooltip"><type>GtkTooltip</type></link> *tooltip</parameter>,
                      <parameter>const <link linkend="gchar"><type>gchar</type></link> *text</parameter>);</programlisting>
<para>Sets the text of the tooltip to be <parameter>text</parameter>
. If <parameter>text</parameter>
 is <link linkend="NULL:CAPS"><literal>NULL</literal></link>, the label
will be hidden. See also <link linkend="gtk-tooltip-set-markup"><function>gtk_tooltip_set_markup()</function></link>.</para>
<refsect3 id="gtk-tooltip-set-text.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>tooltip</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkTooltip"><type>GtkTooltip</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>text</para></entry>
<entry role="parameter_description"><para>a text string or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-tooltip-set-icon" role="function">
<title>gtk_tooltip_set_icon&#160;()</title>
<indexterm zone="gtk-tooltip-set-icon"><primary>gtk_tooltip_set_icon</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_tooltip_set_icon (<parameter><link linkend="GtkTooltip"><type>GtkTooltip</type></link> *tooltip</parameter>,
                      <parameter><link linkend="GdkPaintable"><type>GdkPaintable</type></link> *paintable</parameter>);</programlisting>
<para>Sets the icon of the tooltip (which is in front of the text) to be
<parameter>paintable</parameter>
.  If <parameter>paintable</parameter>
 is <link linkend="NULL:CAPS"><literal>NULL</literal></link>, the image will be hidden.</para>
<refsect3 id="gtk-tooltip-set-icon.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>tooltip</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkTooltip"><type>GtkTooltip</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>paintable</para></entry>
<entry role="parameter_description"><para>a <link linkend="GdkPaintable"><type>GdkPaintable</type></link>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-tooltip-set-icon-from-icon-name" role="function">
<title>gtk_tooltip_set_icon_from_icon_name&#160;()</title>
<indexterm zone="gtk-tooltip-set-icon-from-icon-name"><primary>gtk_tooltip_set_icon_from_icon_name</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_tooltip_set_icon_from_icon_name (<parameter><link linkend="GtkTooltip"><type>GtkTooltip</type></link> *tooltip</parameter>,
                                     <parameter>const <link linkend="gchar"><type>gchar</type></link> *icon_name</parameter>);</programlisting>
<para>Sets the icon of the tooltip (which is in front of the text) to be
the icon indicated by <parameter>icon_name</parameter>
 with the size indicated
by <parameter>size</parameter>
.  If <parameter>icon_name</parameter>
 is <link linkend="NULL:CAPS"><literal>NULL</literal></link>, the image will be hidden.</para>
<refsect3 id="gtk-tooltip-set-icon-from-icon-name.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>tooltip</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkTooltip"><type>GtkTooltip</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>icon_name</para></entry>
<entry role="parameter_description"><para>an icon name, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-tooltip-set-icon-from-gicon" role="function">
<title>gtk_tooltip_set_icon_from_gicon&#160;()</title>
<indexterm zone="gtk-tooltip-set-icon-from-gicon"><primary>gtk_tooltip_set_icon_from_gicon</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_tooltip_set_icon_from_gicon (<parameter><link linkend="GtkTooltip"><type>GtkTooltip</type></link> *tooltip</parameter>,
                                 <parameter><link linkend="GIcon"><type>GIcon</type></link> *gicon</parameter>);</programlisting>
<para>Sets the icon of the tooltip (which is in front of the text)
to be the icon indicated by <parameter>gicon</parameter>
 with the size indicated
by <parameter>size</parameter>
. If <parameter>gicon</parameter>
 is <link linkend="NULL:CAPS"><literal>NULL</literal></link>, the image will be hidden.</para>
<refsect3 id="gtk-tooltip-set-icon-from-gicon.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>tooltip</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkTooltip"><type>GtkTooltip</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>gicon</para></entry>
<entry role="parameter_description"><para>a <link linkend="GIcon"><type>GIcon</type></link> representing the icon, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-tooltip-set-custom" role="function">
<title>gtk_tooltip_set_custom&#160;()</title>
<indexterm zone="gtk-tooltip-set-custom"><primary>gtk_tooltip_set_custom</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_tooltip_set_custom (<parameter><link linkend="GtkTooltip"><type>GtkTooltip</type></link> *tooltip</parameter>,
                        <parameter><link linkend="GtkWidget"><type>GtkWidget</type></link> *custom_widget</parameter>);</programlisting>
<para>Replaces the widget packed into the tooltip with
<parameter>custom_widget</parameter>
. <parameter>custom_widget</parameter>
 does not get destroyed when the tooltip goes
away.
By default a box with a <link linkend="GtkImage"><type>GtkImage</type></link> and <link linkend="GtkLabel"><type>GtkLabel</type></link> is embedded in 
the tooltip, which can be configured using <link linkend="gtk-tooltip-set-markup"><function>gtk_tooltip_set_markup()</function></link> 
and <link linkend="gtk-tooltip-set-icon"><function>gtk_tooltip_set_icon()</function></link>.</para>
<refsect3 id="gtk-tooltip-set-custom.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>tooltip</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkTooltip"><type>GtkTooltip</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>custom_widget</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkWidget"><type>GtkWidget</type></link>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> to unset the old custom widget. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-tooltip-set-tip-area" role="function">
<title>gtk_tooltip_set_tip_area&#160;()</title>
<indexterm zone="gtk-tooltip-set-tip-area"><primary>gtk_tooltip_set_tip_area</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_tooltip_set_tip_area (<parameter><link linkend="GtkTooltip"><type>GtkTooltip</type></link> *tooltip</parameter>,
                          <parameter>const <link linkend="GdkRectangle"><type>GdkRectangle</type></link> *rect</parameter>);</programlisting>
<para>Sets the area of the widget, where the contents of this tooltip apply,
to be <parameter>rect</parameter>
 (in widget coordinates).  This is especially useful for
properly setting tooltips on <link linkend="GtkTreeView"><type>GtkTreeView</type></link> rows and cells, <link linkend="GtkIconViews"><type>GtkIconViews</type></link>,
etc.</para>
<para>For setting tooltips on <link linkend="GtkTreeView"><type>GtkTreeView</type></link>, please refer to the convenience
functions for this: <link linkend="gtk-tree-view-set-tooltip-row"><function>gtk_tree_view_set_tooltip_row()</function></link> and
<link linkend="gtk-tree-view-set-tooltip-cell"><function>gtk_tree_view_set_tooltip_cell()</function></link>.</para>
<refsect3 id="gtk-tooltip-set-tip-area.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>tooltip</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkTooltip"><type>GtkTooltip</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>rect</para></entry>
<entry role="parameter_description"><para>a <link linkend="GdkRectangle"><type>GdkRectangle</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>

</refsect1>
<refsect1 id="GtkTooltip.other_details" role="details">
<title role="details.title">Types and Values</title>
<refsect2 id="GtkTooltip-struct" role="struct">
<title>GtkTooltip</title>
<indexterm zone="GtkTooltip-struct"><primary>GtkTooltip</primary></indexterm>
<programlisting language="C">typedef struct _GtkTooltip GtkTooltip;</programlisting>
</refsect2>

</refsect1>

</refentry>
