Commit ccaf8429 authored by Javier Jardón's avatar Javier Jardón

docs: Move documentation to inline comments: GtkTooltip

parent 38469882
......@@ -42,6 +42,7 @@ gtktexttagtable.sgml
gtktoggleaction.sgml
gtktoolbar.sgml
gtktoolitem.sgml
gtktooltip.sgml
gtktreednd.sgml
gtktypeutils.sgml
gtkwindow.sgml
<!-- ##### 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 ##### -->
<!-- ##### SECTION Image ##### -->
<!-- ##### 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_icon_from_icon_name ##### -->
<para>
</para>
@tooltip:
@icon_name:
@size:
<!-- ##### FUNCTION gtk_tooltip_set_icon_from_gicon ##### -->
<para>
</para>
@tooltip:
@gicon:
@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:
......@@ -36,6 +36,72 @@
#include "gtksizerequest.h"
/**
* SECTION:gtktooltip
* @Short_description: Add tips to your widgets
* @Title: GtkTooltip
*
* Basic tooltips can be realized simply by using gtk_widget_set_tooltip_text()
* or gtk_widget_set_tooltip_markup() without any explicit tooltip object.
*
* 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>
*
* 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 #GtkWidget::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>
*/
#undef DEBUG_TOOLTIP
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment