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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

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, nat_width;

       GTK_WIDGET_GET_CLASS (widget)->get_preferred_width (widget,
                                                           &min_width,
                                                           &nat_width);
       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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

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
3

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.

Since 3.10 GTK+ also supports baseline vertical alignment of widgets. This means that widgets are positioned such that the typographical baseline of widgets in the same row are aligned. This happens if a widget supports baselines, has a vertical alignment of GTK_ALIGN_BASELINE, and is inside a container that supports baselines and has a natural “row” that it aligns to the baseline, or a baseline assigned to it by the grandparent.

Baseline alignment support for a widget is done by the GtkWidgetClass.get_preferred_height_and_baseline_for_width() virtual function. It allows you to report a baseline in combination with the minimum and natural height. If there is no baseline you can return -1 to indicate this. The default implementation of this virtual function calls into the GtkWidgetClass.get_preferred_height() and GtkWidgetClass.get_preferred_height_for_width(), so if baselines are not supported it doesn’t need to be implemented.

If a widget ends up baseline aligned it will be allocated all the space in the parent as if it was GTK_ALIGN_FILL, but the selected baseline can be found via gtk_widget_get_allocated_baseline(). If this has a value other than -1 you need to align the widget such that the baseline appears at the position.

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.

An example of a UI definition fragment specifying an accelerator:

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.

An example of a UI definition fragment specifying an accessible:

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="accessible-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>

Building composite widgets from template XML

GtkWidget exposes some facilities to automate the procedure of creating composite widgets using GtkBuilder interface description language.

To create composite widgets with GtkBuilder XML, one must associate the interface description with the widget class at class initialization time using gtk_widget_class_set_template().

The interface description semantics expected in composite template descriptions is slightly different from regular GtkBuilder XML.

Unlike regular interface descriptions, gtk_widget_class_set_template() will expect a <template> tag as a direct child of the toplevel <interface> tag. The <template> tag must specify the “class” attribute which must be the type name of the widget. Optionally, the “parent” attribute may be specified to specify the direct parent type of the widget type, this is ignored by the GtkBuilder but required for Glade to introspect what kind of properties and internal children exist for a given type when the actual type does not exist.

The XML which is contained inside the <template> tag behaves as if it were added to the <object> tag defining widget itself. You may set properties on widget by inserting <property> tags into the <template> tag, and also add <child> tags to add children and extend widget in the normal way you would with <object> tags.

Additionally, <object> tags can also be added before and after the initial <template> tag in the normal way, allowing one to define auxiliary objects which might be referenced by other widgets declared as children of the <template> tag.

An example of a GtkBuilder Template Definition:

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

<interface>
  <template class="FooWidget" parent="GtkBox">
    <property name="orientation">GTK_ORIENTATION_HORIZONTAL</property>
    <property name="spacing">4</property>
    <child>
      <object class="GtkButton" id="hello_button">
        <property name="label">Hello World</property>
        <signal name="clicked" handler="hello_button_clicked" object="FooWidget" swapped="yes"/>
      </object>
    </child>
    <child>
      <object class="GtkButton" id="goodbye_button">
        <property name="label">Goodbye World</property>
      </object>
    </child>
  </template>
</interface>

Typically, you'll place the template fragment into a file that is bundled with your project, using GResource. In order to load the template, you need to call gtk_widget_class_set_template_from_resource() from the class initialization of your GtkWidget type:

1
2
3
4
5
6
7
8

static void
foo_widget_class_init (FooWidgetClass *klass)
{
  // ...

  gtk_widget_class_set_template_from_resource (GTK_WIDGET_CLASS (klass),
                                               "/com/example/ui/foowidget.ui");
}

You will also need to call gtk_widget_init_template() from the instance initialization function:

1
2
3
4
5
6

static void
foo_widget_init (FooWidget *self)
{
  // ...
  gtk_widget_init_template (GTK_WIDGET (self));
}

You can access widgets defined in the template using the gtk_widget_get_template_child() function, but you will typically declare a pointer in the instance private data structure of your type using the same name as the widget in the template definition, and call gtk_widget_class_bind_template_child_private() with that name, e.g.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

typedef struct {
  GtkWidget *hello_button;
  GtkWidget *goodbye_button;
} FooWidgetPrivate;

G_DEFINE_TYPE_WITH_PRIVATE (FooWidget, foo_widget, GTK_TYPE_BOX)

static void
foo_widget_class_init (FooWidgetClass *klass)
{
  // ...
  gtk_widget_class_set_template_from_resource (GTK_WIDGET_CLASS (klass),
                                               "/com/example/ui/foowidget.ui");
  gtk_widget_class_bind_template_child_private (GTK_WIDGET_CLASS (klass),
                                                FooWidget, hello_button);
  gtk_widget_class_bind_template_child_private (GTK_WIDGET_CLASS (klass),
                                                FooWidget, goodbye_button);
}

You can also use gtk_widget_class_bind_template_callback() to connect a signal callback defined in the template with a function visible in the scope of the class, e.g.

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

// the signal handler has the instance and user data swapped
// because of the swapped="yes" attribute in the template XML
static void
hello_button_clicked (FooWidget *self,
                      GtkButton *button)
{
  g_print ("Hello, world!\n");
}

static void
foo_widget_class_init (FooWidgetClass *klass)
{
  // ...
  gtk_widget_class_set_template_from_resource (GTK_WIDGET_CLASS (klass),
                                               "/com/example/ui/foowidget.ui");
  gtk_widget_class_bind_template_callback (GTK_WIDGET_CLASS (klass), hello_button_clicked);
}

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().

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.

Note that special-purpose widgets may contain special code for rendering to the screen and might appear differently on screen and when rendered using gtk_widget_draw().

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.

Note that you cannot call gtk_widget_queue_resize() on a widget from inside its implementation of the GtkWidgetClass::size_allocate virtual method. Calls to gtk_widget_queue_resize() from inside GtkWidgetClass::size_allocate will be silently ignored.

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_queue_allocate ()

void
gtk_widget_queue_allocate (GtkWidget *widget);

This function is only for use in widget implementations.

Flags the widget for a rerun of the GtkWidgetClass::size_allocate function. Use this function instead of gtk_widget_queue_resize() when the widget 's size request didn't change but it wants to reposition its contents.

An example user of this function is gtk_widget_set_halign().

gtk_widget_get_frame_clock ()

GdkFrameClock *
gtk_widget_get_frame_clock (GtkWidget *widget);

Obtains the frame clock for a widget. The frame clock is a global “ticker” that can be used to drive animations and repaints. The most common reason to get the frame clock is to call gdk_frame_clock_get_frame_time(), in order to get a time to use for animating. For example you might record the start of the animation with an initial value from gdk_frame_clock_get_frame_time(), and then update the animation by calling gdk_frame_clock_get_frame_time() again during each repaint.

gdk_frame_clock_request_phase() will result in a new frame on the clock, but won’t necessarily repaint any widgets. To repaint a widget, you have to use gtk_widget_queue_draw() which invalidates the widget (thus scheduling it to receive a draw on the next frame). gtk_widget_queue_draw() will also end up requesting a frame on the appropriate frame clock.

A widget’s frame clock will not change while the widget is mapped. Reparenting a widget (which implies a temporary unmap) can change the widget’s frame clock.

Unrealized widgets do not have a frame clock.

Since: 3.8

gtk_widget_get_scale_factor ()

gint
gtk_widget_get_scale_factor (GtkWidget *widget);

Retrieves the internal scale factor that maps from window coordinates to the actual device pixels. On traditional systems this is 1, on high density outputs, it can be a higher value (typically 2).

See gdk_window_get_scale_factor().

Since: 3.10

GtkTickCallback ()

gboolean
(*GtkTickCallback) (GtkWidget *widget,
                    GdkFrameClock *frame_clock,
                    gpointer user_data);

Callback type for adding a function to update animations. See gtk_widget_add_tick_callback().

Since: 3.8

gtk_widget_add_tick_callback ()

guint
gtk_widget_add_tick_callback (GtkWidget *widget,
                              GtkTickCallback callback,
                              gpointer user_data,
                              GDestroyNotify notify);

Queues an animation frame update and adds a callback to be called before each frame. Until the tick callback is removed, it will be called frequently (usually at the frame rate of the output device or as quickly as the application can be repainted, whichever is slower). For this reason, is most suitable for handling graphics that change every frame or every few frames. The tick callback does not automatically imply a relayout or repaint. If you want a repaint or relayout, and aren’t changing widget properties that would trigger that (for example, changing the text of a GtkLabel), then you will have to call gtk_widget_queue_resize() or gtk_widget_queue_draw_area() yourself.

gdk_frame_clock_get_frame_time() should generally be used for timing continuous animations and gdk_frame_timings_get_predicted_presentation_time() if you are trying to display isolated frames at particular times.

This is a more convenient alternative to connecting directly to the “update” signal of GdkFrameClock, since you don't have to worry about when a GdkFrameClock is assigned to a widget.

Since: 3.8

gtk_widget_remove_tick_callback ()

void
gtk_widget_remove_tick_callback (GtkWidget *widget,
                                 guint id);

Removes a tick callback previously registered with gtk_widget_add_tick_callback().

Since: 3.8

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.

For baseline support in containers you need to use gtk_widget_size_allocate_with_baseline() instead.

gtk_widget_size_allocate_with_baseline ()

void
gtk_widget_size_allocate_with_baseline
                               (GtkWidget *widget,
                                GtkAllocation *allocation,
                                gint baseline);

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

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

If the child widget does not have a valign of GTK_ALIGN_BASELINE the baseline argument is ignored and -1 is used instead.

Since: 3.10

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_SIGNAL_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” property 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 be able to be a default widget; typically you would ensure this yourself by calling gtk_widget_set_can_default() with a TRUE value. 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.

For GtkWindow classes, this needs to be called before the window is realized.

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 widgets that have no window. (See gtk_widget_get_has_window()). 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 (see GdkEventMask) for the widget. These are the events that the widget will receive.

Note: Internally, the widget event mask will be the logical OR of the event mask set through gtk_widget_set_events() or gtk_widget_add_events(), and the event mask necessary to cater for every GtkEventController created for the widget.

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() and the input handling overview 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 windowless widgets (which return FALSE from gtk_widget_get_has_window()); 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 call gtk_widget_is_toplevel() 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 gtk_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 return TRUE for gtk_widget_get_has_window(); and are relative to widget->allocation.x , widget->allocation.y otherwise.

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);

Used to set the GtkStyle for a widget (widget->style ). Since GTK 3, this function does nothing, the passed in style is ignored.

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 explicitly 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.

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.

This function does not act recursively. Setting the color of a container does not affect its children. Note that some widgets that you may not think of as containers, for instance GtkButtons, are actually containers.

This API is mostly meant as a quick way for applications to change a widget appearance. If you are developing a widgets library and intend this change to be themeable, it is better done by setting meaningful CSS classes in your widget/container implementation through gtk_style_context_add_class().

This way, your widget library can install a GtkCssProvider with the GTK_STYLE_PROVIDER_PRIORITY_FALLBACK priority in order to provide a default styling for those widgets that need so, and this theming may fully overridden by the user’s theme.

Note that for complex widgets this may bring in undesired results (such as uniform background color everywhere), in these cases it is better to fully style such widgets through a GtkCssProvider with the GTK_STYLE_PROVIDER_PRIORITY_APPLICATION priority.

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().