AuroraMiddleware/gtk2
1
0
Fork 0
forked from AuroraMiddleware/gtk
Code Issues Pull Requests Projects Releases Wiki Activity

More tooltips docs

Browse Source 
svn path=/trunk/; revision=18443
This commit is contained in:
Matthias Clasen 2007-07-11 04:46:03 +00:00
parent 2a9ae2f16f
commit 6cd8ec5f78
5 changed files with 140 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
docs/reference/ChangeLog
View File

@ -1,3 +1,16 @@
2007-07-11 Matthias Clasen <mclasen@redhat.com>
* gtk/migrating-GtkTooltip.sgml: Migration chapter
for tooltips.
* gtk/gtk-docs.sgml: Include it, and move GtkTooltips
chapter to "Deprecated".
* gtk/Makefile.am: Glue
* gtk/tmpl/gtktooltip.sgml: Add more content from
Kris' "tooltips in 5 minutes" mail.
2007-07-10 Matthias Clasen <mclasen@redhat.com>
* gdk/tmpl/colors.sgml: Remov references to deprecated

2
docs/reference/gtk/Makefile.am
View File

@ -136,6 +136,7 @@ content_files = \
migrating-GtkRecentChooser.sgml \
migrating-GtkLinkButton.sgml \
migrating-GtkBuilder.sgml \
migrating-GtkTooltip.sgml \
objects_grouped.sgml \
osx.sgml \
question_index.sgml \
@ -162,6 +163,7 @@ expand_content_files = \
migrating-GtkRecentChooser.sgml \
migrating-GtkLinkButton.sgml \
migrating-GtkBuilder.sgml \
migrating-GtkTooltip.sgml \
tree_widget.sgml \
text_widget.sgml \
question_index.sgml

5
docs/reference/gtk/gtk-docs.sgml
View File

@ -226,6 +226,7 @@
<!ENTITY gtk-migrating-GtkRecentChooser SYSTEM "xml/migrating-GtkRecentChooser.sgml">
<!ENTITY gtk-migrating-GtkLinkButton SYSTEM "xml/migrating-GtkLinkButton.sgml">
<!ENTITY gtk-migrating-GtkBuilder SYSTEM "xml/migrating-GtkBuilder.sgml">
<!ENTITY gtk-migrating-GtkTooltip SYSTEM "xml/migrating-GtkTooltip.sgml">
<!ENTITY version SYSTEM "version.xml">
<!ENTITY gtk-query-immodules SYSTEM "gtk-query-immodules-2.0.xml">
<!ENTITY gtk-update-icon-cache SYSTEM "gtk-update-icon-cache.xml">
@ -545,7 +546,6 @@ that is, GUI components such as #GtkButton or #GtkTextView.
&GtkIMMulticontext;
&GtkSizeGroup;
&GtkTooltip;
&GtkTooltips;
&GtkViewport;
&GtkAccessible;
</chapter>
@ -614,6 +614,7 @@ that is, GUI components such as #GtkButton or #GtkTextView.
&GtkPreview;
&GtkProgress;
&GtkText;
&GtkTooltips;
&GtkTipsQuery;
&GtkTree;
&GtkTreeItem;
@ -646,6 +647,7 @@ that is, GUI components such as #GtkButton or #GtkTextView.
&gtk-migrating-GtkRecentChooser;
&gtk-migrating-GtkLinkButton;
&gtk-migrating-GtkBuilder;
&gtk-migrating-GtkTooltip;
</part>
<part>
@ -682,4 +684,5 @@ that is, GUI components such as #GtkButton or #GtkTextView.
<index role="2.12">
<title>Index of new symbols in 2.12</title>
</index>
</book>

62
docs/reference/gtk/migrating-GtkTooltip.sgml Normal file
View File

@ -0,0 +1,62 @@
<chapter id="gtk-migrating-tooltips">
<title>Migrating from GtkTooltips to GtkTooltip</title>
<para>
GTK+ 2.12 brings a completely new tooltip implementation which
allows many things that were not possible with the old
#GtkTooltips interface. The new possibilities are explained
in more detail in the section about #GtkTooltip.
</para>
<para>
A number of complications of the old API have been removed:
<itemizedlist>
<listitem><para>
Tooltips can not be grouped anymore. The old tooltips
API allowed this by using multiple #GtkTooltips objects.
We believe that the timeout behaviour of the new tooltips
implementation is better and makes it unnecessary to use
grouping as a way to overcome shortcomings of the
fast-tooltips mode.
</para></listitem>
<listitem><para>
Timeouts can not be set individually anymore. Instead
there are settings #GtkSettings:gtk-tooltip-timeout,
#GtkSettings:gtk-tooltip-browse-timeout and
#GtkSettings:gtk-tooltip-browse-mode-timeout to influence
the behaviour of tooltips globally.
</para></listitem>
</itemizedlist>
</para>
<para>
Here is an example of setting a tooltip on a widget with the old API:
<informalexample><programlisting>
GtkTooltips *tooltips = gtk_tooltips_new ();
gtk_tooltips_set_tip (tooltips, widget, "Some tips", NULL);
</programlisting></informalexample>
</para>
<para>
Using the new tooltips API, it is no longer necessary to create
an object:
<informalexample><programlisting>
gtk_widget_set_tooltip_text (widget, "Some tips");
</programlisting></informalexample>
</para>
<para>
Similarly, setting a tooltip on a #GtkToolItem gets
simplified from
<informalexample><programlisting>
gtk_tool_item_set_tooltip (toolitem, toolbar->tooltips, "tool tip", NULL);
</programlisting></informalexample>
to
<informalexample><programlisting>
gtk_tool_item_set_tooltip_text (toolitem, text);
</programlisting></informalexample>
</para>
</chapter>

65
docs/reference/gtk/tmpl/gtktooltip.sgml
View File

@ -11,14 +11,67 @@ 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. For fancy tooltips, you will likely
connect to the #GtkWidget::query-tooltip signal, which is passed
a #GtkTooltip object as the last parameter. You can use functions
like gtk_tooltip_set_icon() to modify the tooltip.
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>