Height-for-width Geometry Management

GTK+ uses a height-for-width (and width-for-height) geometry management system. Height-for-width means that a widget can change how much vertical space it needs, depending on the amount of horizontal space that it is given (and similar for width-for-height). The most common example is a label that reflows to fill up the available width, wraps to fewer lines, and therefore needs less height.

Height-for-width geometry management is implemented in GTK+ by way of five virtual methods:

There are some important things to keep in mind when implementing height-for-width and when using it in container implementations.

The geometry management system will query a widget hierarchy in only one orientation at a time. When widgets are initially queried for their minimum sizes it is generally done in two initial passes in the GtkSizeRequestMode chosen by the toplevel.

For example, when queried in the normal GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH mode: First, the default minimum and natural width for each widget in the interface will be computed using gtk_widget_get_preferred_width(). Because the preferred widths for each container depend on the preferred widths of their children, this information propagates up the hierarchy, and finally a minimum and natural width is determined for the entire toplevel. Next, the toplevel will use the minimum width to query for the minimum height contextual to that width using gtk_widget_get_preferred_height_for_width(), which will also be a highly recursive operation. The minimum height for the minimum width is normally used to set the minimum size constraint on the toplevel (unless gtk_window_set_geometry_hints() is explicitly used instead).

After the toplevel window has initially requested its size in both dimensions it can go on to allocate itself a reasonable size (or a size previously specified with gtk_window_set_default_size()). During the recursive allocation process it's important to note that request cycles will be recursively executed while container widgets allocate their children. Each container widget, once allocated a size, will go on to first share the space in one orientation among its children and then request each child's height for its target allocated width or its width for allocated height, depending. In this way a GtkWidget will typically be requested its size a number of times before actually being allocated a size. The size a widget is finally allocated can of course differ from the size it has requested. For this reason, GtkWidget caches a small number of results to avoid re-querying for the same sizes in one allocation cycle.

See GtkContainer's geometry management section to learn more about how height-for-width allocations are performed by container widgets.

If a widget does move content around to intelligently use up the allocated size then it must support the request in both GtkSizeRequestModes even if the widget in question only trades sizes in a single orientation.

For instance, a GtkLabel that does height-for-width word wrapping will not expect to have GtkWidgetClass.get_preferred_height() called because that call is specific to a width-for-height request. In this case the label must return the height required for its own minimum possible width. By following this rule any widget that handles height-for-width or width-for-height requests will always be allocated at least enough space to fit its own content.

Here are some examples of how a GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH widget generally deals with width-for-height requests, for GtkWidgetClass.get_preferred_height() it will do:

static void
foo_widget_get_preferred_height (GtkWidget *widget, gint *min_height, gint *nat_height)
{
   if (i_am_in_height_for_width_mode)
     {
       gint min_width;

       GTK_WIDGET_GET_CLASS (widget)->get_preferred_width (widget, &min_width, NULL);
       GTK_WIDGET_GET_CLASS (widget)->get_preferred_height_for_width (widget, min_width,
                                                                     min_height, nat_height);
     }
   else
     {
        ... some widgets do both. For instance, if a GtkLabel is rotated to 90 degrees
        it will return the minimum and natural height for the rotated label here.
     }
}

And in GtkWidgetClass.get_preferred_width_for_height() it will simply return the minimum and natural width:

static void
foo_widget_get_preferred_width_for_height (GtkWidget *widget, gint for_height,
                                           gint *min_width, gint *nat_width)
{
   if (i_am_in_height_for_width_mode)
     {
       GTK_WIDGET_GET_CLASS (widget)->get_preferred_width (widget, min_width, nat_width);
     }
   else
     {
        ... again if a widget is sometimes operating in width-for-height mode
        (like a rotated GtkLabel) it can go ahead and do its real width for
        height calculation here.
     }
}

Often a widget needs to get its own request during size request or allocation. For example, when computing height it may need to also compute width. Or when deciding how to use an allocation, the widget may need to know its natural size. In these cases, the widget should be careful to call its virtual methods directly, like this:

1
2

GTK_WIDGET_GET_CLASS(widget)->get_preferred_width (widget),
                                 &min, &natural);

It will not work to use the wrapper functions, such as gtk_widget_get_preferred_width() inside your own size request implementation. These return a request adjusted by GtkSizeGroup and by the GtkWidgetClass.adjust_size_request() virtual method. If a widget used the wrappers inside its virtual method implementations, then the adjustments (such as widget margins) would be applied twice. GTK+ therefore does not allow this and will warn if you try to do it.

Of course if you are getting the size request for another widget, such as a child of a container, you must use the wrapper APIs. Otherwise, you would not properly consider widget margins, GtkSizeGroup, and so forth.

Style Properties

GtkWidget introduces style properties - these are basically object properties that are stored not on the object, but in the style object associated to the widget. Style properties are set in resource files. This mechanism is used for configuring such things as the location of the scrollbar arrows through the theme, giving theme authors more control over the look of applications without the need to write a theme engine in C.

Use gtk_widget_class_install_style_property() to install style properties for a widget class, gtk_widget_class_find_style_property() or gtk_widget_class_list_style_properties() to get information about existing style properties and gtk_widget_style_get_property(), gtk_widget_style_get() or gtk_widget_style_get_valist() to obtain the value of a style property.

GtkWidget as GtkBuildable

The GtkWidget implementation of the GtkBuildable interface supports a custom <accelerator> element, which has attributes named key, modifiers and signal and allows to specify accelerators.

1
2
3

<object class="GtkButton">
  <accelerator key="q" modifiers="GDK_CONTROL_MASK" signal="clicked"/>
</object>

In addition to accelerators, GtkWidget also support a custom <accessible> element, which supports actions and relations. Properties on the accessible implementation of an object can be set by accessing the internal child "accessible" of a GtkWidget.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

<object class="GtkButton" id="label1"/>
  <property name="label">I am a Label for a Button</property>
</object>
<object class="GtkButton" id="button1">
  <accessibility>
    <action action_name="click" translatable="yes">Click the button.</action>
    <relation target="label1" type="labelled-by"/>
  </accessibility>
  <child internal-child="accessible">
    <object class="AtkObject" id="a11y-button1">
      <property name="AtkObject::name">Clickable Button</property>
    </object>
  </child>
</object>

Finally, GtkWidget allows style information such as style classes to be associated with widgets, using the custom <style> element:

1
2
3
4
5
6

<object class="GtkButton" id="button1">
  <style>
    <class name="my-special-button-class"/>
    <class name="dark-button"/>
  </style>
</object>

GtkWidget

typedef struct _GtkWidget GtkWidget;

struct GtkWidgetClass

struct GtkWidgetClass {
  GInitiallyUnownedClass parent_class;


  guint activate_signal;

  /* seldomly overidden */
  void (*dispatch_child_properties_changed) (GtkWidget   *widget,
					     guint        n_pspecs,
					     GParamSpec **pspecs);

  /* basics */
  void (* destroy)             (GtkWidget        *widget);
  void (* show)		       (GtkWidget        *widget);
  void (* show_all)            (GtkWidget        *widget);
  void (* hide)		       (GtkWidget        *widget);
  void (* map)		       (GtkWidget        *widget);
  void (* unmap)	       (GtkWidget        *widget);
  void (* realize)	       (GtkWidget        *widget);
  void (* unrealize)	       (GtkWidget        *widget);
  void (* size_allocate)       (GtkWidget        *widget,
				GtkAllocation    *allocation);
  void (* state_changed)       (GtkWidget        *widget,
				GtkStateType   	  previous_state);
  void (* state_flags_changed) (GtkWidget        *widget,
				GtkStateFlags  	  previous_state_flags);
  void (* parent_set)	       (GtkWidget        *widget,
				GtkWidget        *previous_parent);
  void (* hierarchy_changed)   (GtkWidget        *widget,
				GtkWidget        *previous_toplevel);
  void (* style_set)	       (GtkWidget        *widget,
				GtkStyle         *previous_style);
  void (* direction_changed)   (GtkWidget        *widget,
				GtkTextDirection  previous_direction);
  void (* grab_notify)         (GtkWidget        *widget,
				gboolean          was_grabbed);
  void (* child_notify)        (GtkWidget	 *widget,
				GParamSpec       *pspec);
  gboolean (* draw)	       (GtkWidget	 *widget,
                                cairo_t          *cr);

  /* size requests */
  GtkSizeRequestMode (* get_request_mode)               (GtkWidget      *widget);

  void               (* get_preferred_height)           (GtkWidget       *widget,
                                                         gint            *minimum_height,
                                                         gint            *natural_height);
  void               (* get_preferred_width_for_height) (GtkWidget       *widget,
                                                         gint             height,
                                                         gint            *minimum_width,
                                                         gint            *natural_width);
  void               (* get_preferred_width)            (GtkWidget       *widget,
                                                         gint            *minimum_width,
                                                         gint            *natural_width);
  void               (* get_preferred_height_for_width) (GtkWidget       *widget,
                                                         gint             width,
                                                         gint            *minimum_height,
                                                         gint            *natural_height);

  /* Mnemonics */
  gboolean (* mnemonic_activate)        (GtkWidget           *widget,
                                         gboolean             group_cycling);

  /* explicit focus */
  void     (* grab_focus)               (GtkWidget           *widget);
  gboolean (* focus)                    (GtkWidget           *widget,
                                         GtkDirectionType     direction);

  /* keyboard navigation */
  void     (* move_focus)               (GtkWidget           *widget,
                                         GtkDirectionType     direction);
  gboolean (* keynav_failed)            (GtkWidget           *widget,
                                         GtkDirectionType     direction);

  /* events */
  gboolean (* event)			(GtkWidget	     *widget,
					 GdkEvent	     *event);
  gboolean (* button_press_event) (GtkWidget	     *widget,
					 GdkEventButton      *event);
  gboolean (* button_release_event) (GtkWidget	     *widget,
					 GdkEventButton      *event);
  gboolean (* scroll_event)		(GtkWidget           *widget,
					 GdkEventScroll      *event);
  gboolean (* motion_notify_event) (GtkWidget	     *widget,
					 GdkEventMotion      *event);
  gboolean (* delete_event)		(GtkWidget	     *widget,
					 GdkEventAny	     *event);
  gboolean (* destroy_event)		(GtkWidget	     *widget,
					 GdkEventAny	     *event);
  gboolean (* key_press_event)		(GtkWidget	     *widget,
					 GdkEventKey	     *event);
  gboolean (* key_release_event) (GtkWidget	     *widget,
					 GdkEventKey	     *event);
  gboolean (* enter_notify_event) (GtkWidget	     *widget,
					 GdkEventCrossing    *event);
  gboolean (* leave_notify_event) (GtkWidget	     *widget,
					 GdkEventCrossing    *event);
  gboolean (* configure_event)		(GtkWidget	     *widget,
					 GdkEventConfigure   *event);
  gboolean (* focus_in_event)		(GtkWidget	     *widget,
					 GdkEventFocus       *event);
  gboolean (* focus_out_event)		(GtkWidget	     *widget,
					 GdkEventFocus       *event);
  gboolean (* map_event)		(GtkWidget	     *widget,
					 GdkEventAny	     *event);
  gboolean (* unmap_event)		(GtkWidget	     *widget,
					 GdkEventAny	     *event);
  gboolean (* property_notify_event) (GtkWidget	     *widget,
					 GdkEventProperty    *event);
  gboolean (* selection_clear_event) (GtkWidget	     *widget,
					 GdkEventSelection   *event);
  gboolean (* selection_request_event) (GtkWidget	     *widget,
					 GdkEventSelection   *event);
  gboolean (* selection_notify_event) (GtkWidget	     *widget,
					 GdkEventSelection   *event);
  gboolean (* proximity_in_event) (GtkWidget	     *widget,
					 GdkEventProximity   *event);
  gboolean (* proximity_out_event) (GtkWidget	     *widget,
					 GdkEventProximity   *event);
  gboolean (* visibility_notify_event) (GtkWidget	     *widget,
					 GdkEventVisibility  *event);
  gboolean (* window_state_event) (GtkWidget	     *widget,
					 GdkEventWindowState *event);
  gboolean (* damage_event)             (GtkWidget           *widget,
                                         GdkEventExpose      *event);
  gboolean (* grab_broken_event)        (GtkWidget           *widget,
                                         GdkEventGrabBroken  *event);

  /* selection */
  void     (* selection_get)       (GtkWidget          *widget,
				    GtkSelectionData   *selection_data,
				    guint               info,
				    guint               time_);
  void     (* selection_received)  (GtkWidget          *widget,
				    GtkSelectionData   *selection_data,
				    guint               time_);

  /* Source side drag signals */
  void     (* drag_begin)          (GtkWidget         *widget,
				    GdkDragContext     *context);
  void     (* drag_end)	           (GtkWidget	       *widget,
				    GdkDragContext     *context);
  void     (* drag_data_get)       (GtkWidget          *widget,
				    GdkDragContext     *context,
				    GtkSelectionData   *selection_data,
				    guint               info,
				    guint               time_);
  void     (* drag_data_delete)    (GtkWidget          *widget,
				    GdkDragContext     *context);

  /* Target side drag signals */
  void     (* drag_leave)          (GtkWidget          *widget,
				    GdkDragContext     *context,
				    guint               time_);
  gboolean (* drag_motion)         (GtkWidget	       *widget,
				    GdkDragContext     *context,
				    gint                x,
				    gint                y,
				    guint               time_);
  gboolean (* drag_drop)           (GtkWidget	       *widget,
				    GdkDragContext     *context,
				    gint                x,
				    gint                y,
				    guint               time_);
  void     (* drag_data_received)  (GtkWidget          *widget,
				    GdkDragContext     *context,
				    gint                x,
				    gint                y,
				    GtkSelectionData   *selection_data,
				    guint               info,
				    guint               time_);
  gboolean (* drag_failed)         (GtkWidget          *widget,
                                    GdkDragContext     *context,
                                    GtkDragResult       result);

  /* Signals used only for keybindings */
  gboolean (* popup_menu)          (GtkWidget          *widget);

  /* If a widget has multiple tooltips/whatsthis, it should show the
   * one for the current focus location, or if that doesn't make
   * sense, should cycle through them showing each tip alongside
   * whatever piece of the widget it applies to.
   */
  gboolean (* show_help)           (GtkWidget          *widget,
                                    GtkWidgetHelpType   help_type);

  /* accessibility support
   */
  AtkObject *  (* get_accessible)     (GtkWidget *widget);

  void         (* screen_changed)     (GtkWidget *widget,
                                       GdkScreen *previous_screen);
  gboolean     (* can_activate_accel) (GtkWidget *widget,
                                       guint      signal_id);


  void         (* composited_changed) (GtkWidget *widget);

  gboolean     (* query_tooltip)      (GtkWidget  *widget,
				       gint        x,
				       gint        y,
				       gboolean    keyboard_tooltip,
				       GtkTooltip *tooltip);

  void         (* compute_expand)     (GtkWidget  *widget,
                                       gboolean   *hexpand_p,
                                       gboolean   *vexpand_p);

  void         (* adjust_size_request)    (GtkWidget         *widget,
                                           GtkOrientation     orientation,
                                           gint              *minimum_size,
                                           gint              *natural_size);
  void         (* adjust_size_allocation) (GtkWidget         *widget,
                                           GtkOrientation     orientation,
                                           gint              *minimum_size,
                                           gint              *natural_size,
                                           gint              *allocated_pos,
                                           gint              *allocated_size);

  void         (* style_updated)          (GtkWidget *widget);
};

GtkCallback ()

void                (*GtkCallback)                      (GtkWidget *widget,
                                                         gpointer data);

The type of the callback functions used for e.g. iterating over the children of a container, see gtk_container_foreach().

struct GtkRequisition

struct GtkRequisition;

A GtkRequisition represents the desired size of a widget. See the section called “Height-for-width Geometry Management” for more information.

GtkAllocation

typedef 	GdkRectangle	   GtkAllocation;

A GtkAllocation of a widget represents region which has been allocated to the widget by its parent. It is a subregion of its parents allocation. See the section called “Height-for-width Geometry Management” for more information.

GtkSelectionData

typedef struct _GtkSelectionData GtkSelectionData;

struct GtkWidgetAuxInfo

struct GtkWidgetAuxInfo {
  gint width;
  gint height;

  guint   halign : 4;
  guint   valign : 4;

  GtkBorder margin;
};

enum GtkWidgetHelpType

typedef enum
{
  GTK_WIDGET_HELP_TOOLTIP,
  GTK_WIDGET_HELP_WHATS_THIS
} GtkWidgetHelpType;

gtk_widget_new ()

GtkWidget *         gtk_widget_new                      (GType type,
                                                         const gchar *first_property_name,
                                                         ...);

This is a convenience function for creating a widget and setting its properties in one go. For example you might write: gtk_widget_new (GTK_TYPE_LABEL, "label", "Hello World", "xalign", 0.0, NULL) to create a left-aligned label. Equivalent to g_object_new(), but returns a widget so you don't have to cast the object yourself.

gtk_widget_destroy ()

void                gtk_widget_destroy                  (GtkWidget *widget);

Destroys a widget.

When a widget is destroyed, it will break any references it holds to other objects. If the widget is inside a container, the widget will be removed from the container. If the widget is a toplevel (derived from GtkWindow), it will be removed from the list of toplevels, and the reference GTK+ holds to it will be removed. Removing a widget from its container or the list of toplevels results in the widget being finalized, unless you've added additional references to the widget with g_object_ref().

In most cases, only toplevel widgets (windows) require explicit destruction, because when you destroy a toplevel its children will be destroyed as well.

gtk_widget_in_destruction ()

gboolean            gtk_widget_in_destruction           (GtkWidget *widget);

Returns whether the widget is currently being destroyed. This information can sometimes be used to avoid doing unnecessary work.

gtk_widget_destroyed ()

void                gtk_widget_destroyed                (GtkWidget *widget,
                                                         GtkWidget **widget_pointer);

This function sets *widget_pointer to NULL if widget_pointer != NULL. It's intended to be used as a callback connected to the "destroy" signal of a widget. You connect gtk_widget_destroyed() as a signal handler, and pass the address of your widget variable as user data. Then when the widget is destroyed, the variable will be set to NULL. Useful for example to avoid multiple copies of the same dialog.

gtk_widget_unparent ()

void                gtk_widget_unparent                 (GtkWidget *widget);

This function is only for use in widget implementations. Should be called by implementations of the remove method on GtkContainer, to dissociate a child from the container.

gtk_widget_show ()

void                gtk_widget_show                     (GtkWidget *widget);

Flags a widget to be displayed. Any widget that isn't shown will not appear on the screen. If you want to show all the widgets in a container, it's easier to call gtk_widget_show_all() on the container, instead of individually showing the widgets.

Remember that you have to show the containers containing a widget, in addition to the widget itself, before it will appear onscreen.

When a toplevel container is shown, it is immediately realized and mapped; other shown widgets are realized and mapped when their toplevel container is realized and mapped.

gtk_widget_show_now ()

void                gtk_widget_show_now                 (GtkWidget *widget);

Shows a widget. If the widget is an unmapped toplevel widget (i.e. a GtkWindow that has not yet been shown), enter the main loop and wait for the window to actually be mapped. Be careful; because the main loop is running, anything can happen during this function.

gtk_widget_hide ()

void                gtk_widget_hide                     (GtkWidget *widget);

Reverses the effects of gtk_widget_show(), causing the widget to be hidden (invisible to the user).

gtk_widget_show_all ()

void                gtk_widget_show_all                 (GtkWidget *widget);

Recursively shows a widget, and any child widgets (if the widget is a container).

gtk_widget_map ()

void                gtk_widget_map                      (GtkWidget *widget);

This function is only for use in widget implementations. Causes a widget to be mapped if it isn't already.

gtk_widget_unmap ()

void                gtk_widget_unmap                    (GtkWidget *widget);

This function is only for use in widget implementations. Causes a widget to be unmapped if it's currently mapped.

gtk_widget_realize ()

void                gtk_widget_realize                  (GtkWidget *widget);

Creates the GDK (windowing system) resources associated with a widget. For example, widget->window will be created when a widget is realized. Normally realization happens implicitly; if you show a widget and all its parent containers, then the widget will be realized and mapped automatically.

Realizing a widget requires all the widget's parent widgets to be realized; calling gtk_widget_realize() realizes the widget's parents in addition to widget itself. If a widget is not yet inside a toplevel window when you realize it, bad things will happen.

This function is primarily used in widget implementations, and isn't very useful otherwise. Many times when you think you might need it, a better approach is to connect to a signal that will be called after the widget is realized automatically, such as "draw". Or simply g_signal_connect() to the "realize" signal.

gtk_widget_unrealize ()

void                gtk_widget_unrealize                (GtkWidget *widget);

This function is only useful in widget implementations. Causes a widget to be unrealized (frees all GDK resources associated with the widget, such as widget->window).

gtk_widget_draw ()

void                gtk_widget_draw                     (GtkWidget *widget,
                                                         cairo_t *cr);

Draws widget to cr. The top left corner of the widget will be drawn to the currently set origin point of cr.

You should pass a cairo context as cr argument that is in an original state. Otherwise the resulting drawing is undefined. For example changing the operator using cairo_set_operator() or the line width using cairo_set_line_width() might have unwanted side effects. You may however change the context's transform matrix - like with cairo_scale(), cairo_translate() or cairo_set_matrix() and clip region with cairo_clip() prior to calling this function. Also, it is fine to modify the context with cairo_save() and cairo_push_group() prior to calling this function.

Since 3.0

gtk_widget_queue_draw ()

void                gtk_widget_queue_draw               (GtkWidget *widget);

Equivalent to calling gtk_widget_queue_draw_area() for the entire area of a widget.

gtk_widget_queue_resize ()

void                gtk_widget_queue_resize             (GtkWidget *widget);

This function is only for use in widget implementations. Flags a widget to have its size renegotiated; should be called when a widget for some reason has a new size request. For example, when you change the text in a GtkLabel, GtkLabel queues a resize to ensure there's enough space for the new text.

gtk_widget_queue_resize_no_redraw ()

void                gtk_widget_queue_resize_no_redraw   (GtkWidget *widget);

This function works like gtk_widget_queue_resize(), except that the widget is not invalidated.

Since 2.4

gtk_widget_size_request ()

void                gtk_widget_size_request             (GtkWidget *widget,
                                                         GtkRequisition *requisition);

This function is typically used when implementing a GtkContainer subclass. Obtains the preferred size of a widget. The container uses this information to arrange its child widgets and decide what size allocations to give them with gtk_widget_size_allocate().

You can also call this function from an application, with some caveats. Most notably, getting a size request requires the widget to be associated with a screen, because font information may be needed. Multihead-aware applications should keep this in mind.

Also remember that the size request is not necessarily the size a widget will actually be allocated.

gtk_widget_get_child_requisition ()

void                gtk_widget_get_child_requisition    (GtkWidget *widget,
                                                         GtkRequisition *requisition);

This function is only for use in widget implementations. Obtains widget->requisition, unless someone has forced a particular geometry on the widget (e.g. with gtk_widget_set_size_request()), in which case it returns that geometry instead of the widget's requisition.

This function differs from gtk_widget_size_request() in that it retrieves the last size request value from widget->requisition, while gtk_widget_size_request() actually calls the "size_request" method on widget to compute the size request and fill in widget->requisition, and only then returns widget->requisition.

Because this function does not call the "size_request" method, it can only be used when you know that widget->requisition is up-to-date, that is, gtk_widget_size_request() has been called since the last time a resize was queued. In general, only container implementations have this information; applications should use gtk_widget_size_request().

gtk_widget_size_allocate ()

void                gtk_widget_size_allocate            (GtkWidget *widget,
                                                         GtkAllocation *allocation);

This function is only used by GtkContainer subclasses, to assign a size and position to their child widgets.

In this function, the allocation may be adjusted. It will be forced to a 1x1 minimum size, and the adjust_size_allocation virtual method on the child will be used to adjust the allocation. Standard adjustments include removing the widget's margins, and applying the widget's "halign" and "valign" properties.

gtk_widget_add_accelerator ()

void                gtk_widget_add_accelerator          (GtkWidget *widget,
                                                         const gchar *accel_signal,
                                                         GtkAccelGroup *accel_group,
                                                         guint accel_key,
                                                         GdkModifierType accel_mods,
                                                         GtkAccelFlags accel_flags);

Installs an accelerator for this widget in accel_group that causes accel_signal to be emitted if the accelerator is activated. The accel_group needs to be added to the widget's toplevel via gtk_window_add_accel_group(), and the signal must be of type G_RUN_ACTION. Accelerators added through this function are not user changeable during runtime. If you want to support accelerators that can be changed by the user, use gtk_accel_map_add_entry() and gtk_widget_set_accel_path() or gtk_menu_item_set_accel_path() instead.

gtk_widget_remove_accelerator ()

gboolean            gtk_widget_remove_accelerator       (GtkWidget *widget,
                                                         GtkAccelGroup *accel_group,
                                                         guint accel_key,
                                                         GdkModifierType accel_mods);

Removes an accelerator from widget, previously installed with gtk_widget_add_accelerator().

gtk_widget_set_accel_path ()

void                gtk_widget_set_accel_path           (GtkWidget *widget,
                                                         const gchar *accel_path,
                                                         GtkAccelGroup *accel_group);

Given an accelerator group, accel_group, and an accelerator path, accel_path, sets up an accelerator in accel_group so whenever the key binding that is defined for accel_path is pressed, widget will be activated. This removes any accelerators (for any accelerator group) installed by previous calls to gtk_widget_set_accel_path(). Associating accelerators with paths allows them to be modified by the user and the modifications to be saved for future use. (See gtk_accel_map_save().)

This function is a low level function that would most likely be used by a menu creation system like GtkUIManager. If you use GtkUIManager, setting up accelerator paths will be done automatically.

Even when you you aren't using GtkUIManager, if you only want to set up accelerators on menu items gtk_menu_item_set_accel_path() provides a somewhat more convenient interface.

Note that accel_path string will be stored in a GQuark. Therefore, if you pass a static string, you can save some memory by interning it first with g_intern_static_string().

gtk_widget_list_accel_closures ()

GList *             gtk_widget_list_accel_closures      (GtkWidget *widget);

Lists the closures used by widget for accelerator group connections with gtk_accel_group_connect_by_path() or gtk_accel_group_connect(). The closures can be used to monitor accelerator changes on widget, by connecting to the GtkAccelGroup::accel-changed signal of the GtkAccelGroup of a closure which can be found out with gtk_accel_group_from_accel_closure().

gtk_widget_can_activate_accel ()

gboolean            gtk_widget_can_activate_accel       (GtkWidget *widget,
                                                         guint signal_id);

Determines whether an accelerator that activates the signal identified by signal_id can currently be activated. This is done by emitting the "can-activate-accel" signal on widget; if the signal isn't overridden by a handler or in a derived widget, then the default check is that the widget must be sensitive, and the widget and all its ancestors mapped.

Since 2.4

gtk_widget_event ()

gboolean            gtk_widget_event                    (GtkWidget *widget,
                                                         GdkEvent *event);

Rarely-used function. This function is used to emit the event signals on a widget (those signals should never be emitted without using this function to do so). If you want to synthesize an event though, don't use this function; instead, use gtk_main_do_event() so the event will behave as if it were in the event queue. Don't synthesize expose events; instead, use gdk_window_invalidate_rect() to invalidate a region of the window.

gtk_widget_activate ()

gboolean            gtk_widget_activate                 (GtkWidget *widget);

For widgets that can be "activated" (buttons, menu items, etc.) this function activates them. Activation is what happens when you press Enter on a widget during key navigation. If widget isn't activatable, the function returns FALSE.

gtk_widget_reparent ()

void                gtk_widget_reparent                 (GtkWidget *widget,
                                                         GtkWidget *new_parent);

Moves a widget from one GtkContainer to another, handling reference count issues to avoid destroying the widget.

gtk_widget_intersect ()

gboolean            gtk_widget_intersect                (GtkWidget *widget,
                                                         const GdkRectangle *area,
                                                         GdkRectangle *intersection);

Computes the intersection of a widget's area and area, storing the intersection in intersection, and returns TRUE if there was an intersection. intersection may be NULL if you're only interested in whether there was an intersection.

gtk_widget_is_focus ()

gboolean            gtk_widget_is_focus                 (GtkWidget *widget);

Determines if the widget is the focus widget within its toplevel. (This does not mean that the HAS_FOCUS flag is necessarily set; HAS_FOCUS will only be set if the toplevel widget additionally has the global input focus.)

gtk_widget_grab_focus ()

void                gtk_widget_grab_focus               (GtkWidget *widget);

Causes widget to have the keyboard focus for the GtkWindow it's inside. widget must be a focusable widget, such as a GtkEntry; something like GtkFrame won't work.

More precisely, it must have the GTK_CAN_FOCUS flag set. Use gtk_widget_set_can_focus() to modify that flag.

The widget also needs to be realized and mapped. This is indicated by the related signals. Grabbing the focus immediately after creating the widget will likely fail and cause critical warnings.

gtk_widget_grab_default ()

void                gtk_widget_grab_default             (GtkWidget *widget);

Causes widget to become the default widget. widget must have the GTK_CAN_DEFAULT flag set; typically you have to set this flag yourself by calling gtk_widget_set_can_default (widget, TRUE). The default widget is activated when the user presses Enter in a window. Default widgets must be activatable, that is, gtk_widget_activate() should affect them. Note that GtkEntry widgets require the "activates-default" property set to TRUE before they activate the default widget when Enter is pressed and the GtkEntry is focused.

gtk_widget_set_name ()

void                gtk_widget_set_name                 (GtkWidget *widget,
                                                         const gchar *name);

Widgets can be named, which allows you to refer to them from a CSS file. You can apply a style to widgets with a particular name in the CSS file. See the documentation for the CSS syntax (on the same page as the docs for GtkStyleContext).

Note that the CSS syntax has certain special characters to delimit and represent elements in a selector (period, #, >, *...), so using these will make your widget impossible to match by name. Any combination of alphanumeric symbols, dashes and underscores will suffice.

gtk_widget_get_name ()

const gchar *       gtk_widget_get_name                 (GtkWidget *widget);

Retrieves the name of a widget. See gtk_widget_set_name() for the significance of widget names.

gtk_widget_set_state ()

void                gtk_widget_set_state                (GtkWidget *widget,
                                                         GtkStateType state);

This function is for use in widget implementations. Sets the state of a widget (insensitive, prelighted, etc.) Usually you should set the state using wrapper functions such as gtk_widget_set_sensitive().

gtk_widget_set_sensitive ()

void                gtk_widget_set_sensitive            (GtkWidget *widget,
                                                         gboolean sensitive);

Sets the sensitivity of a widget. A widget is sensitive if the user can interact with it. Insensitive widgets are "grayed out" and the user can't interact with them. Insensitive widgets are known as "inactive", "disabled", or "ghosted" in some other toolkits.

gtk_widget_set_parent ()

void                gtk_widget_set_parent               (GtkWidget *widget,
                                                         GtkWidget *parent);

This function is useful only when implementing subclasses of GtkContainer. Sets the container as the parent of widget, and takes care of some details such as updating the state and style of the child to reflect its new location. The opposite function is gtk_widget_unparent().

gtk_widget_set_parent_window ()

void                gtk_widget_set_parent_window        (GtkWidget *widget,
                                                         GdkWindow *parent_window);

Sets a non default parent window for widget.

For GtkWindow classes, setting a parent_window effects whether the window is a toplevel window or can be embedded into other widgets.

gtk_widget_get_parent_window ()

GdkWindow *         gtk_widget_get_parent_window        (GtkWidget *widget);

Gets widget's parent window.

gtk_widget_set_events ()

void                gtk_widget_set_events               (GtkWidget *widget,
                                                         gint events);

Sets the event mask (see GdkEventMask) for a widget. The event mask determines which events a widget will receive. Keep in mind that different widgets have different default event masks, and by changing the event mask you may disrupt a widget's functionality, so be careful. This function must be called while a widget is unrealized. Consider gtk_widget_add_events() for widgets that are already realized, or if you want to preserve the existing event mask. This function can't be used with GTK_NO_WINDOW widgets; to get events on those widgets, place them inside a GtkEventBox and receive events on the event box.

gtk_widget_get_events ()

gint                gtk_widget_get_events               (GtkWidget *widget);

Returns the event mask for the widget (a bitfield containing flags from the GdkEventMask enumeration). These are the events that the widget will receive.

gtk_widget_add_events ()

void                gtk_widget_add_events               (GtkWidget *widget,
                                                         gint events);

Adds the events in the bitfield events to the event mask for widget. See gtk_widget_set_events() for details.

gtk_widget_set_device_events ()

void                gtk_widget_set_device_events        (GtkWidget *widget,
                                                         GdkDevice *device,
                                                         GdkEventMask events);

Sets the device event mask (see GdkEventMask) for a widget. The event mask determines which events a widget will receive from device. Keep in mind that different widgets have different default event masks, and by changing the event mask you may disrupt a widget's functionality, so be careful. This function must be called while a widget is unrealized. Consider gtk_widget_add_device_events() for widgets that are already realized, or if you want to preserve the existing event mask. This function can't be used with GTK_NO_WINDOW widgets; to get events on those widgets, place them inside a GtkEventBox and receive events on the event box.

Since 3.0

gtk_widget_get_device_events ()

GdkEventMask        gtk_widget_get_device_events        (GtkWidget *widget,
                                                         GdkDevice *device);

Returns the events mask for the widget corresponding to an specific device. These are the events that the widget will receive when device operates on it.

Since 3.0

gtk_widget_add_device_events ()

void                gtk_widget_add_device_events        (GtkWidget *widget,
                                                         GdkDevice *device,
                                                         GdkEventMask events);

Adds the device events in the bitfield events to the event mask for widget. See gtk_widget_set_device_events() for details.

Since 3.0

gtk_widget_set_device_enabled ()

void                gtk_widget_set_device_enabled       (GtkWidget *widget,
                                                         GdkDevice *device,
                                                         gboolean enabled);

Enables or disables a GdkDevice to interact with widget and all its children.

It does so by descending through the GdkWindow hierarchy and enabling the same mask that is has for core events (i.e. the one that gdk_window_get_events() returns).

Since 3.0

gtk_widget_get_device_enabled ()

gboolean            gtk_widget_get_device_enabled       (GtkWidget *widget,
                                                         GdkDevice *device);

Returns whether device can interact with widget and its children. See gtk_widget_set_device_enabled().

Since 3.0

gtk_widget_get_toplevel ()

GtkWidget *         gtk_widget_get_toplevel             (GtkWidget *widget);

This function returns the topmost widget in the container hierarchy widget is a part of. If widget has no parent widgets, it will be returned as the topmost widget. No reference will be added to the returned widget; it should not be unreferenced.

Note the difference in behavior vs. gtk_widget_get_ancestor(); gtk_widget_get_ancestor (widget, GTK_TYPE_WINDOW) would return NULL if widget wasn't inside a toplevel window, and if the window was inside a GtkWindow-derived widget which was in turn inside the toplevel GtkWindow. While the second case may seem unlikely, it actually happens when a GtkPlug is embedded inside a GtkSocket within the same application.

To reliably find the toplevel GtkWindow, use gtk_widget_get_toplevel() and check if the TOPLEVEL flags is set on the result.

1
2
3
4
5

GtkWidget *toplevel = gtk_widget_get_toplevel (widget);
if (gtk_widget_is_toplevel (toplevel))
  {
    /* Perform action on toplevel. */
  }

gtk_widget_get_ancestor ()

GtkWidget *         gtk_widget_get_ancestor             (GtkWidget *widget,
                                                         GType widget_type);

Gets the first ancestor of widget with type widget_type. For example, gtk_widget_get_ancestor (widget, GTK_TYPE_BOX) gets the first GtkBox that's an ancestor of widget. No reference will be added to the returned widget; it should not be unreferenced. See note about checking for a toplevel GtkWindow in the docs for gtk_widget_get_toplevel().

Note that unlike gtk_widget_is_ancestor(), gtk_widget_get_ancestor() considers widget to be an ancestor of itself.

gtk_widget_get_visual ()

GdkVisual *         gtk_widget_get_visual               (GtkWidget *widget);

Gets the visual that will be used to render widget.

gtk_widget_set_visual ()

void                gtk_widget_set_visual               (GtkWidget *widget,
                                                         GdkVisual *visual);

Sets the visual that should be used for by widget and its children for creating GdkWindows. The visual must be on the same GdkScreen as returned by gdk_widget_get_screen(), so handling the "screen-changed" signal is necessary.

Setting a new visual will not cause widget to recreate its windows, so you should call this function before widget is realized.

gtk_widget_get_pointer ()

void                gtk_widget_get_pointer              (GtkWidget *widget,
                                                         gint *x,
                                                         gint *y);

Obtains the location of the mouse pointer in widget coordinates. Widget coordinates are a bit odd; for historical reasons, they are defined as widget->window coordinates for widgets that are not GTK_NO_WINDOW widgets, and are relative to widget->allocation.x, widget->allocation.y for widgets that are GTK_NO_WINDOW widgets.

gtk_widget_is_ancestor ()

gboolean            gtk_widget_is_ancestor              (GtkWidget *widget,
                                                         GtkWidget *ancestor);

Determines whether widget is somewhere inside ancestor, possibly with intermediate containers.

gtk_widget_translate_coordinates ()

gboolean            gtk_widget_translate_coordinates    (GtkWidget *src_widget,
                                                         GtkWidget *dest_widget,
                                                         gint src_x,
                                                         gint src_y,
                                                         gint *dest_x,
                                                         gint *dest_y);

Translate coordinates relative to src_widget's allocation to coordinates relative to dest_widget's allocations. In order to perform this operation, both widgets must be realized, and must share a common toplevel.

gtk_widget_hide_on_delete ()

gboolean            gtk_widget_hide_on_delete           (GtkWidget *widget);

Utility function; intended to be connected to the "delete-event" signal on a GtkWindow. The function calls gtk_widget_hide() on its argument, then returns TRUE. If connected to ::delete-event, the result is that clicking the close button for a window (on the window frame, top right corner usually) will hide but not destroy the window. By default, GTK+ destroys windows when ::delete-event is received.

gtk_widget_set_style ()

void                gtk_widget_set_style                (GtkWidget *widget,
                                                         GtkStyle *style);

Sets the GtkStyle for a widget (widget->style).

You probably don't want to use this function; it interacts badly with themes, because themes work by replacing the GtkStyle. Instead, use gtk_widget_modify_style().

gtk_widget_ensure_style ()

void                gtk_widget_ensure_style             (GtkWidget *widget);

Ensures that widget has a style (widget->style).

Not a very useful function; most of the time, if you want the style, the widget is realized, and realized widgets are guaranteed to have a style already.

gtk_widget_get_style ()

GtkStyle *          gtk_widget_get_style                (GtkWidget *widget);

Simply an accessor function that returns widget->style.

gtk_widget_reset_rc_styles ()

void                gtk_widget_reset_rc_styles          (GtkWidget *widget);

Reset the styles of widget and all descendents, so when they are looked up again, they get the correct values for the currently loaded RC file settings.

This function is not useful for applications.

gtk_widget_get_default_style ()

GtkStyle *          gtk_widget_get_default_style        (void);

Returns the default style used by all widgets initially.

gtk_widget_set_direction ()

void                gtk_widget_set_direction            (GtkWidget *widget,
                                                         GtkTextDirection dir);

Sets the reading direction on a particular widget. This direction controls the primary direction for widgets containing text, and also the direction in which the children of a container are packed. The ability to set the direction is present in order so that correct localization into languages with right-to-left reading directions can be done. Generally, applications will let the default reading direction present, except for containers where the containers are arranged in an order that is explicitely visual rather than logical (such as buttons for text justification).

If the direction is set to GTK_TEXT_DIR_NONE, then the value set by gtk_widget_set_default_direction() will be used.

enum GtkTextDirection

typedef enum
{
  GTK_TEXT_DIR_NONE,
  GTK_TEXT_DIR_LTR,
  GTK_TEXT_DIR_RTL
} GtkTextDirection;

gtk_widget_get_direction ()

GtkTextDirection    gtk_widget_get_direction            (GtkWidget *widget);

Gets the reading direction for a particular widget. See gtk_widget_set_direction().

gtk_widget_set_default_direction ()

void                gtk_widget_set_default_direction    (GtkTextDirection dir);

Sets the default reading direction for widgets where the direction has not been explicitly set by gtk_widget_set_direction().

gtk_widget_get_default_direction ()

GtkTextDirection    gtk_widget_get_default_direction    (void);

Obtains the current default reading direction. See gtk_widget_set_default_direction().

gtk_widget_shape_combine_region ()

void                gtk_widget_shape_combine_region     (GtkWidget *widget,
                                                         cairo_region_t *region);

Sets a shape for this widget's GDK window. This allows for transparent windows etc., see gdk_window_shape_combine_region() for more information.

Since 3.0

gtk_widget_input_shape_combine_region ()

void                gtk_widget_input_shape_combine_region
                                                        (GtkWidget *widget,
                                                         cairo_region_t *region);

Sets an input shape for this widget's GDK window. This allows for windows which react to mouse click in a nonrectangular region, see gdk_window_input_shape_combine_region() for more information.

Since 3.0

gtk_widget_path ()

void                gtk_widget_path                     (GtkWidget *widget,
                                                         guint *path_length,
                                                         gchar **path,
                                                         gchar **path_reversed);

Obtains the full path to widget. The path is simply the name of a widget and all its parents in the container hierarchy, separated by periods. The name of a widget comes from gtk_widget_get_name(). Paths are used to apply styles to a widget in gtkrc configuration files. Widget names are the type of the widget by default (e.g. "GtkButton") or can be set to an application-specific value with gtk_widget_set_name(). By setting the name of a widget, you allow users or theme authors to apply styles to that specific widget in their gtkrc file. path_reversed_p fills in the path in reverse order, i.e. starting with widget's name instead of starting with the name of widget's outermost ancestor.

gtk_widget_class_path ()

void                gtk_widget_class_path               (GtkWidget *widget,
                                                         guint *path_length,
                                                         gchar **path,
                                                         gchar **path_reversed);

Same as gtk_widget_path(), but always uses the name of a widget's type, never uses a custom name set with gtk_widget_set_name().

gtk_widget_get_composite_name ()

gchar *             gtk_widget_get_composite_name       (GtkWidget *widget);

Obtains the composite name of a widget.

gtk_widget_override_background_color ()

void                gtk_widget_override_background_color
                                                        (GtkWidget *widget,
                                                         GtkStateFlags state,
                                                         const GdkRGBA *color);

Sets the background color to use for a widget.

All other style values are left untouched. See gtk_widget_override_color().

Since 3.0

gtk_widget_override_color ()

void                gtk_widget_override_color           (GtkWidget *widget,
                                                         GtkStateFlags state,
                                                         const GdkRGBA *color);

Sets the color to use for a widget.

All other style values are left untouched.

Since 3.0

gtk_widget_override_font ()

void                gtk_widget_override_font            (GtkWidget *widget,
                                                         const PangoFontDescription *font_desc);

Sets the font to use for a widget. All other style values are left untouched. See gtk_widget_override_color().

Since 3.0

gtk_widget_override_symbolic_color ()

void                gtk_widget_override_symbolic_color  (GtkWidget *widget,
                                                         const gchar *name,
                                                         const GdkRGBA *color);

Sets a symbolic color for a widget.

All other style values are left untouched. See gtk_widget_override_color() for overriding the foreground or background color.

Since 3.0

gtk_widget_override_cursor ()

void                gtk_widget_override_cursor          (GtkWidget *widget,
                                                         const GdkRGBA *cursor,
                                                         const GdkRGBA *secondary_cursor);

Sets the cursor color to use in a widget, overriding the "cursor-color" and "secondary-cursor-color" style properties. All other style values are left untouched. See also gtk_widget_modify_style().

Note that the underlying properties have the GdkColor type, so the alpha value in primary and secondary will be ignored.

Since 3.0

gtk_widget_modify_style ()

void                gtk_widget_modify_style             (GtkWidget *widget,
                                                         GtkRcStyle *style);

Modifies style values on the widget.

Modifications made using this technique take precedence over style values set via an RC file, however, they will be overridden if a style is explicitely set on the widget using gtk_widget_set_style(). The GtkRcStyle structure is designed so each field can either be set or unset, so it is possible, using this function, to modify some style values and leave the others unchanged.

Note that modifications made with this function are not cumulative with previous calls to gtk_widget_modify_style() or with such functions as gtk_widget_modify_fg(). If you wish to retain previous values, you must first call gtk_widget_get_modifier_style(), make your modifications to the returned style, then call gtk_widget_modify_style() with that style. On the other hand, if you first call gtk_widget_modify_style(), subsequent calls to such functions gtk_widget_modify_fg() will have a cumulative effect with the initial modifications.

gtk_widget_get_modifier_style ()

GtkRcStyle *        gtk_widget_get_modifier_style       (GtkWidget *widget);

Returns the current modifier style for the widget. (As set by gtk_widget_modify_style().) If no style has previously set, a new GtkRcStyle will be created with all values unset, and set as the modifier style for the widget. If you make changes to this rc style, you must call gtk_widget_modify_style(), passing in the returned rc style, to make sure that your changes take effect.

Caution: passing the style back to gtk_widget_modify_style() will normally end up destroying it, because gtk_widget_modify_style() copies the passed-in style and sets the copy as the new modifier style, thus dropping any reference to the old modifier style. Add a reference to the modifier style if you want to keep it alive.

gtk_widget_modify_fg ()

void                gtk_widget_modify_fg                (GtkWidget *widget,
                                                         GtkStateType state,
                                                         const GdkColor *color);

Sets the foreground color for a widget in a particular state.

All other style values are left untouched. See also gtk_widget_modify_style().

gtk_widget_modify_bg ()

void                gtk_widget_modify_bg                (GtkWidget *widget,
                                                         GtkStateType state,
                                                         const GdkColor *color);

Sets the background color for a widget in a particular state.

All other style values are left untouched. See also gtk_widget_modify_style().

gtk_widget_modify_text ()

void                gtk_widget_modify_text              (GtkWidget *widget,
                                                         GtkStateType state,
                                                         const GdkColor *color);

Sets the text color for a widget in a particular state.

All other style values are left untouched. The text color is the foreground color used along with the base color (see gtk_widget_modify_base()) for widgets such as GtkEntry and GtkTextView. See also gtk_widget_modify_style().

gtk_widget_modify_base ()

void                gtk_widget_modify_base              (GtkWidget *widget,
                                                         GtkStateType state,
                                                         const GdkColor *color);

Sets the base color for a widget in a particular state. All other style values are left untouched. The base color is the background color used along with the text color (see gtk_widget_modify_text()) for widgets such as GtkEntry and GtkTextView. See also gtk_widget_modify_style().

gtk_widget_modify_font ()

void                gtk_widget_modify_font              (GtkWidget *widget,
                                                         PangoFontDescription *font_desc);

Sets the font to use for a widget.

All other style values are left untouched. See also gtk_widget_modify_style().

gtk_widget_modify_cursor ()

void                gtk_widget_modify_cursor            (GtkWidget *widget,
                                                         const GdkColor *primary,
                                                         const GdkColor *secondary);

Sets the cursor color to use in a widget, overriding the "cursor-color" and "secondary-cursor-color" style properties.

All other style values are left untouched. See also gtk_widget_modify_style().

Since 2.12

gtk_widget_create_pango_context ()

PangoContext *      gtk_widget_create_pango_context     (GtkWidget *widget);

Creates a new PangoContext with the appropriate font map, font description, and base direction for drawing text for this widget. See also gtk_widget_get_pango_context().

gtk_widget_get_pango_context ()

PangoContext *      gtk_widget_get_pango_context        (GtkWidget *widget);

Gets a PangoContext with the appropriate font map, font description, and base direction for this widget. Unlike the context returned by gtk_widget_create_pango_context(), this context is owned by the widget (it can be used until the screen for the widget changes or the widget is removed from its toplevel), and will be updated to match any changes to the widget's attributes.

If you create and keep a PangoLayout using this context, you must deal with changes to the context by calling pango_layout_context_changed() on the layout in response to the "style-updated" and "direction-changed" signals for the widget.

gtk_widget_create_pango_layout ()

PangoLayout *       gtk_widget_create_pango_layout      (GtkWidget *widget,
                                                         const gchar *text);

Creates a new PangoLayout with the appropriate font map, font description, and base direction for drawing text for this widget.

If you keep a PangoLayout created in this way around, in order to notify the layout of changes to the base direction or font of this widget, you must call pango_layout_context_changed() in response to the "style-updated" and "direction-changed" signals for the widget.

gtk_widget_render_icon ()

GdkPixbuf *         gtk_widget_render_icon              (GtkWidget *widget,
                                                         const gchar *stock_id,
                                                         GtkIconSize size,
                                                         const gchar *detail);