Pileus Git - ~andy/gtk/blob - docs/reference/gtk/tmpl/gtktooltip.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GtkTooltip
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Add tips to your widgets
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 #GtkTooltip belongs to the new tooltips API that was
  10 introduced in GTK+ 2.12 and which deprecates the old
  11 #GtkTooltips API.
  12 </para>
  13 <para>
  14 Basic tooltips can be realized simply by using gtk_widget_set_tooltip_text()
  15 or gtk_widget_set_tooltip_markup() without any explicit tooltip object.
  16 </para>
  17
  18 <para>
  19 When you need a tooltip with a little more fancy contents, like
  20 adding an image, or you want the tooltip to have different contents
  21 per GtkTreeView row or cell, you will have to do a little more work:
  22 <itemizedlist>
  23
  24 <listitem><para>
  25 Set the #GtkWidget:has-tooltip property to %TRUE, this will
  26 make GTK+ monitor the widget for motion and related events
  27 which are needed to determine when and where to show a tooltip.
  28 </para></listitem>
  29
  30 <listitem><para>
  31 Connect to the #GtkWidget::query-tooltip signal.  This signal
  32 will be emitted when a tooltip is supposed to be shown. One
  33 of the arguments passed to the signal handler is a #GtkTooltip
  34 object. This is the object that we are about to display as a
  35 tooltip, and can be manipulated in your callback using functions
  36 like gtk_tooltip_set_icon(). There are functions for setting
  37 the tooltip's markup, setting an image from a stock icon, or
  38 even putting in a custom widget.
  39 </para></listitem>
  40
  41 <listitem><para>
  42 Return %TRUE from your query-tooltip handler. This causes
  43 the tooltip to be show. If you return %FALSE, it will not be shown.
  44 </para></listitem>
  45 </itemizedlist>
  46 </para>
  47
  48 <para>
  49 In the probably rare case where you want to have even more control
  50 over the tooltip that is about to be shown, you can set your own
  51 #GtkWindow which will be used as tooltip window.  This works as
  52 follows:
  53 <itemizedlist>
  54
  55 <listitem><para>
  56 Set #GtkWidget:has-tooltip and connect to #GtkWidget::query-tooltip as
  57 before.
  58 </para></listitem>
  59
  60 <listitem><para>
  61 Use gtk_widget_set_tooltip_window() to set a #GtkWindow created
  62 by you as tooltip window.
  63 </para></listitem>
  64
  65 <listitem><para>
  66 In the ::query-tooltip callback you can access your window
  67 using gtk_widget_get_tooltip_window() and manipulate as you
  68 wish. The semantics of the return value are exactly as before,
  69 return %TRUE to show the window, %FALSE to not show it.
  70 </para></listitem>
  71 </itemizedlist>
  72 </para>
  73
  74 <!-- ##### SECTION See_Also ##### -->
  75 <para>
  76
  77 </para>
  78
  79 <!-- ##### SECTION Stability_Level ##### -->
  80
  81
  82 <!-- ##### STRUCT GtkTooltip ##### -->
  83 <para>
  84
  85 </para>
  86
  87
  88 <!-- ##### FUNCTION gtk_tooltip_set_markup ##### -->
  89 <para>
  90
  91 </para>
  92
  93 @tooltip:
  94 @markup:
  95
  96
  97 <!-- ##### FUNCTION gtk_tooltip_set_text ##### -->
  98 <para>
  99
 100 </para>
 101
 102 @tooltip:
 103 @text:
 104
 105
 106 <!-- ##### FUNCTION gtk_tooltip_set_icon ##### -->
 107 <para>
 108
 109 </para>
 110
 111 @tooltip:
 112 @pixbuf:
 113
 114
 115 <!-- ##### FUNCTION gtk_tooltip_set_icon_from_stock ##### -->
 116 <para>
 117
 118 </para>
 119
 120 @tooltip:
 121 @stock_id:
 122 @size:
 123
 124
 125 <!-- ##### FUNCTION gtk_tooltip_set_icon_from_icon_name ##### -->
 126 <para>
 127
 128 </para>
 129
 130 @tooltip:
 131 @icon_name:
 132 @size:
 133
 134
 135 <!-- ##### FUNCTION gtk_tooltip_set_icon_from_gicon ##### -->
 136 <para>
 137
 138 </para>
 139
 140 @tooltip:
 141 @gicon:
 142 @size:
 143
 144
 145 <!-- ##### FUNCTION gtk_tooltip_set_custom ##### -->
 146 <para>
 147
 148 </para>
 149
 150 @tooltip:
 151 @custom_widget:
 152
 153
 154 <!-- ##### FUNCTION gtk_tooltip_trigger_tooltip_query ##### -->
 155 <para>
 156
 157 </para>
 158
 159 @display:
 160
 161
 162 <!-- ##### FUNCTION gtk_tooltip_set_tip_area ##### -->
 163 <para>
 164
 165 </para>
 166
 167 @tooltip:
 168 @rect:
 169
 170