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

   1 <!-- ##### SECTION Title ##### -->
   2 GtkTipsQuery
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Displays help about widgets in the user interface
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 The #GtkTipsQuery widget is a subclass of #GtkLabel which is used to display
  10 help about widgets in a user interface.
  11 </para>
  12 <para>
  13 A query is started with a call to gtk_tips_query_start_query(), usually
  14 when some kind of 'Help' button is pressed. The #GtkTipsQuery then grabs all
  15 events, stopping the user interface from functioning normally.
  16 Then as the user moves the mouse over the widgets, the #GtkTipsQuery displays
  17 each widget's tooltip text.
  18 </para>
  19 <para>
  20 By connecting to the "widget-entered" or "widget-selected" signals, it is
  21 possible to customize the #GtkTipsQuery to perform other actions when widgets
  22 are entered or selected. For example, a help browser could be opened with
  23 documentation on the widget selected.
  24 </para>
  25 <para>
  26 At some point a call to gtk_tips_query_stop_query() must be made in order to
  27 stop the query and return the interface to its normal state.
  28 The gtk_tips_query_set_caller() function can be used to specify a widget
  29 which the user can select to stop the query (often the same button used to
  30 start the query).
  31 </para>
  32
  33 <!-- ##### SECTION See_Also ##### -->
  34 <para>
  35 <variablelist>
  36 <varlistentry>
  37 <term>#GtkTooltips</term>
  38 <listitem><para>the object which handles tooltips.</para></listitem>
  39 </varlistentry>
  40 </variablelist>
  41 </para>
  42
  43 <!-- ##### SECTION Stability_Level ##### -->
  44
  45
  46 <!-- ##### STRUCT GtkTipsQuery ##### -->
  47 <para>
  48 The #GtkTipsQuery-struct struct contains private data only, and
  49 should be accessed using the functions below.
  50 </para>
  51
  52
  53 <!-- ##### SIGNAL GtkTipsQuery::start-query ##### -->
  54 <para>
  55 Emitted when the query is started.
  56 </para>
  57
  58 @tipsquery: the object which received the signal.
  59
  60 <!-- ##### SIGNAL GtkTipsQuery::stop-query ##### -->
  61 <para>
  62 Emitted when the query is stopped.
  63 </para>
  64
  65 @tipsquery: the object which received the signal.
  66
  67 <!-- ##### SIGNAL GtkTipsQuery::widget-entered ##### -->
  68 <para>
  69 Emitted when a widget is entered by the pointer while the query is in effect.
  70 </para>
  71
  72 @tipsquery: the object which received the signal.
  73 @widget: the widget that was entered by the pointer.
  74 @tip_text: the widget's tooltip.
  75 @tip_private: the widget's private tooltip (see gtk_tooltips_set_tip()).
  76
  77 <!-- ##### SIGNAL GtkTipsQuery::widget-selected ##### -->
  78 <para>
  79 Emitted when a widget is selected during a query.
  80 </para>
  81
  82 @tipsquery: the object which received the signal.
  83 @widget: the widget that was selected.
  84 @tip_text: the widget's tooltip.
  85 @tip_private: the widget's private tooltip (see gtk_tooltips_set_tip()).
  86 @event: the button press or button release event.
  87 @Returns: %TRUE if the query should be stopped.
  88
  89 <!-- ##### ARG GtkTipsQuery:caller ##### -->
  90 <para>
  91 The widget that starts the tips query, usually a button.
  92 If it is selected while the query is in effect the query is automatically
  93 stopped.
  94 </para>
  95
  96 <!-- ##### ARG GtkTipsQuery:emit-always ##### -->
  97 <para>
  98 %TRUE if the widget-entered and widget-selected signals are emitted even when
  99 the widget has no tooltip set.
 100 </para>
 101
 102 <!-- ##### ARG GtkTipsQuery:label-inactive ##### -->
 103 <para>
 104 The text to display in the #GtkTipsQuery widget when the query is not in
 105 effect.
 106 </para>
 107
 108 <!-- ##### ARG GtkTipsQuery:label-no-tip ##### -->
 109 <para>
 110 The text to display in the #GtkTipsQuery widget when the query is running
 111 and the widget that the pointer is over has no tooltip.
 112 </para>
 113
 114 <!-- ##### FUNCTION gtk_tips_query_new ##### -->
 115 <para>
 116 Creates a new #GtkTipsQuery.
 117 </para>
 118
 119 @Returns: a new #GtkTipsQuery.
 120
 121
 122 <!-- ##### FUNCTION gtk_tips_query_start_query ##### -->
 123 <para>
 124 Starts a query.
 125 The #GtkTipsQuery widget will take control of the mouse and as the mouse
 126 moves it will display the tooltip of the widget beneath the mouse.
 127 </para>
 128
 129 @tips_query: a #GtkTipsQuery.
 130
 131
 132 <!-- ##### FUNCTION gtk_tips_query_stop_query ##### -->
 133 <para>
 134 Stops a query.
 135 </para>
 136
 137 @tips_query: a #GtkTipsQuery.
 138
 139
 140 <!-- ##### FUNCTION gtk_tips_query_set_caller ##### -->
 141 <para>
 142 Sets the widget which initiates the query, usually a button.
 143 If the @caller is selected while the query is running, the query is
 144 automatically stopped.
 145 </para>
 146
 147 @tips_query: a #GtkTipsQuery.
 148 @caller: the widget which initiates the query.
 149
 150
 151 <!-- ##### FUNCTION gtk_tips_query_set_labels ##### -->
 152 <para>
 153 Sets the text to display when the query is not in effect,
 154 and the text to display when the query is in effect but the widget beneath
 155 the pointer has no tooltip.
 156 </para>
 157
 158 @tips_query: a #GtkTipsQuery.
 159 @label_inactive: the text to display when the query is not running.
 160 @label_no_tip: the text to display when the query is running but the widget
 161 beneath the pointer has no tooltip.
 162
 163