## GtkTipsQuery

GtkTipsQuery — Displays help about widgets in the user interface

## Synopsis

    #include <gtk/gtk.h>

                        GtkTipsQuery;
    GtkWidget*          gtk_tips_query_new                  (void);
    void                gtk_tips_query_start_query          (GtkTipsQuery *tips_query);
    void                gtk_tips_query_stop_query           (GtkTipsQuery *tips_query);
    void                gtk_tips_query_set_caller           (GtkTipsQuery *tips_query,
                                                             GtkWidget *caller);
    void                gtk_tips_query_set_labels           (GtkTipsQuery *tips_query,
                                                             const gchar *label_inactive,
                                                             const gchar *label_no_tip);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkObject
                   +----GtkWidget
                         +----GtkMisc
                               +----GtkLabel
                                     +----GtkTipsQuery

## Implemented Interfaces

GtkTipsQuery implements AtkImplementorIface and GtkBuildable.

## Properties

      "caller"                   GtkWidget             : Read / Write
      "emit-always"              gboolean              : Read / Write
      "label-inactive"           gchararray            : Read / Write
      "label-no-tip"             gchararray            : Read / Write

## Signals

      "start-query"                                    : Run First
      "stop-query"                                     : Run First
      "widget-entered"                                 : Run Last
      "widget-selected"                                : Run Last

## Description

The GtkTipsQuery widget is a subclass of GtkLabel which is used to display help about widgets in a user interface.

A query is started with a call to `gtk_tips_query_start_query()`, usually when some kind of 'Help' button is pressed. The GtkTipsQuery then grabs all events, stopping the user interface from functioning normally. Then as the user moves the mouse over the widgets, the GtkTipsQuery displays each widget's tooltip text.

By connecting to the "widget-entered" or "widget-selected" signals, it is possible to customize the GtkTipsQuery to perform other actions when widgets are entered or selected. For example, a help browser could be opened with documentation on the widget selected.

At some point a call to `gtk_tips_query_stop_query()` must be made in order to stop the query and return the interface to its normal state. The `gtk_tips_query_set_caller()` function can be used to specify a widget which the user can select to stop the query (often the same button used to start the query).

## Details

### GtkTipsQuery

    typedef struct _GtkTipsQuery GtkTipsQuery;

### Warning

`GtkTipsQuery` is deprecated and should not be used in newly-written code.

The GtkTipsQuery struct contains private data only, and should be accessed using the functions below.

### gtk_tips_query_new ()

    GtkWidget*          gtk_tips_query_new                  (void);

### Warning

`gtk_tips_query_new` is deprecated and should not be used in newly-written code.

Creates a new GtkTipsQuery.

Returns : | a new GtkTipsQuery.

### gtk_tips_query_start_query ()

    void                gtk_tips_query_start_query          (GtkTipsQuery *tips_query);

### Warning

`gtk_tips_query_start_query` is deprecated and should not be used in newly-written code.

Starts a query. The GtkTipsQuery widget will take control of the mouse and as the mouse moves it will display the tooltip of the widget beneath the mouse.

`tips_query` : | a GtkTipsQuery.

### gtk_tips_query_stop_query ()

    void                gtk_tips_query_stop_query           (GtkTipsQuery *tips_query);

### Warning

`gtk_tips_query_stop_query` is deprecated and should not be used in newly-written code.

Stops a query.

`tips_query` : | a GtkTipsQuery.

### gtk_tips_query_set_caller ()

    void                gtk_tips_query_set_caller           (GtkTipsQuery *tips_query,
                                                             GtkWidget *caller);

### Warning

`gtk_tips_query_set_caller` is deprecated and should not be used in newly-written code.

Sets the widget which initiates the query, usually a button. If the `caller` is selected while the query is running, the query is automatically stopped.

`tips_query` : | a GtkTipsQuery.
`caller` : | the widget which initiates the query.

### gtk_tips_query_set_labels ()

    void                gtk_tips_query_set_labels           (GtkTipsQuery *tips_query,
                                                             const gchar *label_inactive,
                                                             const gchar *label_no_tip);

### Warning

`gtk_tips_query_set_labels` is deprecated and should not be used in newly-written code.

Sets the text to display when the query is not in effect, and the text to display when the query is in effect but the widget beneath the pointer has no tooltip.

`tips_query` : | a GtkTipsQuery.
`label_inactive` : | the text to display when the query is not running.
`label_no_tip` : | the text to display when the query is running but the widget beneath the pointer has no tooltip.

## Property Details

### The "`caller`" property

      "caller"                   GtkWidget             : Read / Write

The widget that starts the tips query, usually a button. If it is selected while the query is in effect the query is automatically stopped.

### The "`emit-always`" property

      "emit-always"              gboolean              : Read / Write

`TRUE` if the widget-entered and widget-selected signals are emitted even when the widget has no tooltip set.

Default value: FALSE

### The "`label-inactive`" property

      "label-inactive"           gchararray            : Read / Write

The text to display in the GtkTipsQuery widget when the query is not in effect.

Default value: NULL

### The "`label-no-tip`" property

      "label-no-tip"             gchararray            : Read / Write

The text to display in the GtkTipsQuery widget when the query is running and the widget that the pointer is over has no tooltip.

Default value: NULL

## Signal Details

### The "start-query" signal

    void                user_function                      (GtkTipsQuery *tipsquery,
                                                            gpointer      user_data)      : Run First

Emitted when the query is started.

`tipsquery` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The "stop-query" signal

    void                user_function                      (GtkTipsQuery *tipsquery,
                                                            gpointer      user_data)      : Run First

Emitted when the query is stopped.

`tipsquery` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The "widget-entered" signal

    void                user_function                      (GtkTipsQuery *tipsquery,
                                                            GtkWidget    *widget,
                                                            gchar        *tip_text,
                                                            gchar        *tip_private,
                                                            gpointer      user_data)        : Run Last

Emitted when a widget is entered by the pointer while the query is in effect.

`tipsquery` : | the object which received the signal.
`widget` : | the widget that was entered by the pointer.
`tip_text` : | the widget's tooltip.
`tip_private` : | the widget's private tooltip (see `gtk_tooltips_set_tip()`).
`user_data` : | user data set when the signal handler was connected.

### The "widget-selected" signal

    gboolean            user_function                      (GtkTipsQuery   *tipsquery,
                                                            GtkWidget      *widget,
                                                            gchar          *tip_text,
                                                            gchar          *tip_private,
                                                            GdkEventButton *event,
                                                            gpointer        user_data)        : Run Last

Emitted when a widget is selected during a query.

`tipsquery` : | the object which received the signal.
`widget` : | the widget that was selected.
`tip_text` : | the widget's tooltip.
`tip_private` : | the widget's private tooltip (see `gtk_tooltips_set_tip()`).
`event` : | the button press or button release event.
`user_data` : | user data set when the signal handler was connected.
Returns : | `TRUE` if the query should be stopped.

## See Also

GtkTooltips | the object which handles tooltips.