### Class

# Gtk Widget

#### Description [src]

    abstract class Gtk.Widget : GObject.InitiallyUnowned
      implements Gtk.Accessible, Gtk.Buildable, Gtk.ConstraintTarget {
      /* No available fields */
    }

The base class for all widgets.

`GtkWidget` is the base class all widgets in GTK derive from. It manages the widget lifecycle, layout, states and style.

### 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 two virtual methods:

- `Gtk.WidgetClass.get_request_mode`
- `Gtk.WidgetClass.measure`

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

If you implement a direct `GtkWidget` subclass that supports height-for-width or width-for-height geometry management for itself or its child widgets, the `Gtk.WidgetClass.get_request_mode` virtual function must be implemented as well and return the widget’s preferred request mode. The default implementation of this virtual function returns `GTK_SIZE_REQUEST_CONSTANT_SIZE`, which means that the widget will only ever get -1 passed as the for_size value to its `Gtk.WidgetClass.measure` implementation.

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_measure()` with an orientation of `GTK_ORIENTATION_HORIZONTAL` and a for_size of -1. Because the preferred widths for each widget 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_measure()` with an orientation of `GTK_ORIENTATION_VERTICAL` and a for_size of the just computed width. This 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.

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 widgets allocate their children. Each 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.

If a widget does move content around to intelligently use up the allocated size then it must support the request in both `GtkSizeRequestMode`s 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 `Gtk.WidgetClass.measure` with an orientation of `GTK_ORIENTATION_VERTICAL` 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:

    static void
    foo_widget_measure (GtkWidget      *widget,
                        GtkOrientation  orientation,
                        int             for_size,
                        int            *minimum_size,
                        int            *natural_size,
                        int            *minimum_baseline,
                        int            *natural_baseline)
    {
      if (orientation == GTK_ORIENTATION_HORIZONTAL)
        {
          // Calculate minimum and natural width
        }
      else // VERTICAL
        {
          if (i_am_in_height_for_width_mode)
            {
              int min_width, dummy;

              // First, get the minimum width of our widget
              GTK_WIDGET_GET_CLASS (widget)->measure (widget, GTK_ORIENTATION_HORIZONTAL, -1,
                                                      &min_width, &dummy, &dummy, &dummy);

              // Now use the minimum width to retrieve the minimum and natural height to display
              // that width.
              GTK_WIDGET_GET_CLASS (widget)->measure (widget, GTK_ORIENTATION_VERTICAL, min_width,
                                                      minimum_size, natural_size, &dummy, &dummy);
            }
          else
            {
              // ... some widgets do both.
            }
        }
    }

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 in the code example above.

It will not work to use the wrapper function `gtk_widget_measure()` inside your own `Gtk.WidgetClass.size_allocate` implementation. These return a request adjusted by `GtkSizeGroup`, the widget’s align and expand flags, as well as its CSS style.

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 widget, you must use `gtk_widget_measure()`; otherwise, you would not properly consider widget margins, `GtkSizeGroup`, and so forth.

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 using baselines, and is inside a widget 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 also done by the `Gtk.WidgetClass.measure` virtual function. It allows you to report both a minimum and natural size.

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_baseline()`. If the baseline has a value other than -1 you need to align the widget such that the baseline appears at the position.

### GtkWidget as GtkBuildable

The `GtkWidget` implementation of the `GtkBuildable` interface supports various custom elements to specify additional aspects of widgets that are not directly expressed as properties.

If the widget uses a `GtkLayoutManager`, `GtkWidget` supports a custom `<layout>` element, used to define layout properties:

    <object class="GtkGrid" id="my_grid">
      <child>
        <object class="GtkLabel" id="label1">
          <property name="label">Description</property>
          <layout>
            <property name="column">0</property>
            <property name="row">0</property>
            <property name="row-span">1</property>
            <property name="column-span">1</property>
          </layout>
        </object>
      </child>
      <child>
        <object class="GtkEntry" id="description_entry">
          <layout>
            <property name="column">1</property>
            <property name="row">0</property>
            <property name="row-span">1</property>
            <property name="column-span">1</property>
          </layout>
        </object>
      </child>
    </object>

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

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

`GtkWidget` allows defining accessibility information, such as properties, relations, and states, using the custom `<accessibility>` element:

    <object class="GtkButton" id="button1">
      <accessibility>
        <property name="label">Download</property>
        <relation name="labelled-by">label1</relation>
      </accessibility>
    </object>

### Building composite widgets from template XML

`GtkWidget`exposes some facilities to automate the procedure of creating composite widgets using “templates”.

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 `GtkBuilder` but can be used by UI design tools 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 the widget itself. You may set properties on a widget by inserting `<property>` tags into the `<template>` tag, and also add `<child>` tags to add children and extend a 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.

Since, unlike the `<object>` tag, the `<template>` tag does not contain an “id” attribute, if you need to refer to the instance of the object itself that the template will create, simply refer to the template class name in an applicable element content.

Here is an example of a template definition, which includes an example of this in the `<signal>` tag:

    <interface>
      <template class="FooWidget" parent="GtkBox">
        <property name="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:

    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:

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

      // Initialize the rest of the widget...
    }

as well as calling `gtk_widget_dispose_template()` from the dispose function:

    static void
    foo_widget_dispose (GObject *gobject)
    {
      FooWidget *self = FOO_WIDGET (gobject);

      // Dispose objects for which you have a reference...

      // Clear the template children for this widget type
      gtk_widget_dispose_template (GTK_WIDGET (self), FOO_TYPE_WIDGET);

      G_OBJECT_CLASS (foo_widget_parent_class)->dispose (gobject);
    }

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_full()` (or one of its wrapper macros `gtk_widget_class_bind_template_child()` and `gtk_widget_class_bind_template_child_private()`) with that name, e.g.

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

    G_DEFINE_TYPE_WITH_PRIVATE (FooWidget, foo_widget, GTK_TYPE_BOX)

    static void
    foo_widget_dispose (GObject *gobject)
    {
      gtk_widget_dispose_template (GTK_WIDGET (gobject), FOO_TYPE_WIDGET);

      G_OBJECT_CLASS (foo_widget_parent_class)->dispose (gobject);
    }

    static void
    foo_widget_class_init (FooWidgetClass *klass)
    {
      // ...
      G_OBJECT_CLASS (klass)->dispose = foo_widget_dispose;

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

    static void
    foo_widget_init (FooWidget *widget)
    {
      gtk_widget_init_template (GTK_WIDGET (widget));
    }

You can also use `gtk_widget_class_bind_template_callback_full()` (or is wrapper macro `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.

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

#### Ancestors

- GInitiallyUnowned
- GObject

#### Descendants

- GtkActionBar
- GtkAppChooserButton
- GtkAppChooserWidget
- GtkAspectFrame
- GtkBox
- GtkButton
- GtkCalendar
- GtkCellView
- GtkCenterBox
- GtkCheckButton
- GtkColorButton
- GtkColorChooserWidget
- GtkColorDialogButton
- GtkColumnView
- GtkComboBox
- GtkDragIcon
- GtkDrawingArea
- GtkDropDown
- GtkEditableLabel
- GtkEntry
- GtkExpander
- GtkFileChooserWidget
- GtkFixed
- GtkFlowBox
- GtkFlowBoxChild
- GtkFontButton
- GtkFontChooserWidget
- GtkFontDialogButton
- GtkFrame
- GtkGLArea
- GtkGraphicsOffload
- GtkGrid
- GtkHeaderBar
- GtkIconView
- GtkImage
- GtkInfoBar
- GtkInscription
- GtkLabel
- GtkLevelBar
- GtkListBase
- GtkListBox
- GtkListBoxRow
- GtkMediaControls
- GtkMenuButton
- GtkNotebook
- GtkOverlay
- GtkPaned
- GtkPasswordEntry
- GtkPicture
- GtkPopover
- GtkPopoverMenuBar
- GtkProgressBar
- GtkRange
- GtkRevealer
- GtkScaleButton
- GtkScrollbar
- GtkScrolledWindow
- GtkSearchBar
- GtkSearchEntry
- GtkSeparator
- GtkShortcutLabel
- GtkShortcutsShortcut
- GtkSpinButton
- GtkSpinner
- GtkStack
- GtkStackSidebar
- GtkStackSwitcher
- GtkStatusbar
- GtkSwitch
- GtkText
- GtkTextView
- GtkTreeExpander
- GtkTreeView
- GtkVideo
- GtkViewport
- GtkWindow
- GtkWindowControls
- GtkWindowHandle

#### Implements

- GtkAccessible
- GtkBuildable
- GtkConstraintTarget

#### Functions

###### gtk_widget_get_default_direction

Obtains the current default reading direction.

###### gtk_widget_set_default_direction

Sets the default reading direction for widgets.

#### Instance methods

###### gtk_widget_action_set_enabled

Enable or disable an action installed with gtk_widget_class_install_action().

###### gtk_widget_activate

For widgets that can be “activated” (buttons, menu items, etc.), this function activates them.

###### gtk_widget_activate_action

Looks up the action in the action groups associated with `widget` and its ancestors, and activates it.

###### gtk_widget_activate_action_variant

Looks up the action in the action groups associated with `widget` and its ancestors, and activates it.

###### gtk_widget_activate_default

Activates the `default.activate` action from `widget`.

###### gtk_widget_add_controller

Adds `controller` to `widget` so that it will receive events.

###### gtk_widget_add_css_class

Adds a style class to `widget`.

###### gtk_widget_add_mnemonic_label

Adds a widget to the list of mnemonic labels for this widget.

###### gtk_widget_add_tick_callback

Queues an animation frame update and adds a callback to be called before each frame.

###### gtk_widget_allocate

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

###### gtk_widget_child_focus

Called by widgets as the user moves around the window using keyboard shortcuts.

###### gtk_widget_compute_bounds

Computes the bounds for `widget` in the coordinate space of `target`.

###### gtk_widget_compute_expand

Computes whether a container should give this widget extra space when possible.

###### gtk_widget_compute_point

Translates the given `point` in `widget`‘s coordinates to coordinates relative to `target`’s coordinate system.

###### gtk_widget_compute_transform

Computes a matrix suitable to describe a transformation from `widget`‘s coordinate system into `target`‘s coordinate system.

###### gtk_widget_contains

Tests if the point at (`x`, `y`) is contained in `widget`.

###### gtk_widget_create_pango_context

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

###### gtk_widget_create_pango_layout

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

###### gtk_widget_dispose_template

Clears the template children for the given widget.

since: 4.8

###### gtk_drag_check_threshold

Checks to see if a drag movement has passed the GTK drag threshold.

###### gtk_widget_error_bell

Notifies the user about an input-related error on this widget.

###### gtk_widget_get_allocated_baseline

Returns the baseline that has currently been allocated to `widget`.

deprecated: 4.12

###### gtk_widget_get_allocated_height

Returns the height that has currently been allocated to `widget`.

deprecated: 4.12

###### gtk_widget_get_allocated_width

Returns the width that has currently been allocated to `widget`.

deprecated: 4.12

###### gtk_widget_get_allocation

Retrieves the widget’s allocation.

deprecated: 4.12

###### gtk_widget_get_ancestor

Gets the first ancestor of `widget` with type `widget_type`.

###### gtk_widget_get_baseline

Returns the baseline that has currently been allocated to `widget`.

since: 4.12

###### gtk_widget_get_can_focus

Determines whether the input focus can enter `widget` or any of its children.

###### gtk_widget_get_can_target

Queries whether `widget` can be the target of pointer events.

###### gtk_widget_get_child_visible

Gets the value set with gtk_widget_set_child_visible().

###### gtk_widget_get_clipboard

Gets the clipboard object for `widget`.

###### gtk_widget_get_color

Gets the current foreground color for the widget’s CSS style.

since: 4.10

###### gtk_widget_get_css_classes

Returns the list of style classes applied to `widget`.

###### gtk_widget_get_css_name

Returns the CSS name that is used for `self`.

###### gtk_widget_get_cursor

Queries the cursor set on `widget`.

###### gtk_widget_get_direction

Gets the reading direction for a particular widget.

###### gtk_widget_get_display

Get the `GdkDisplay` for the toplevel window associated with this widget.

###### gtk_widget_get_first_child

Returns the widget’s first child.

###### gtk_widget_get_focus_child

Returns the current focus child of `widget`.

###### gtk_widget_get_focus_on_click

Returns whether the widget should grab focus when it is clicked with the mouse.

###### gtk_widget_get_focusable

Determines whether `widget` can own the input focus.

###### gtk_widget_get_font_map

Gets the font map of `widget`.

###### gtk_widget_get_font_options

Returns the `cairo_font_options_t` of widget.

###### gtk_widget_get_frame_clock

Obtains the frame clock for a widget.

###### gtk_widget_get_halign

Gets the horizontal alignment of `widget`.

###### gtk_widget_get_has_tooltip

Returns the current value of the `has-tooltip` property.

###### gtk_widget_get_height

Returns the content height of the widget.

###### gtk_widget_get_hexpand

Gets whether the widget would like any available extra horizontal space.

###### gtk_widget_get_hexpand_set

Gets whether `gtk_widget_set_hexpand()` has been used to explicitly set the expand flag on this widget.

###### gtk_widget_get_last_child

Returns the widget’s last child.

###### gtk_widget_get_layout_manager

Retrieves the layout manager used by `widget`.

###### gtk_widget_get_mapped

Whether the widget is mapped.

###### gtk_widget_get_margin_bottom

Gets the bottom margin of `widget`.

###### gtk_widget_get_margin_end

Gets the end margin of `widget`.

###### gtk_widget_get_margin_start

Gets the start margin of `widget`.

###### gtk_widget_get_margin_top

Gets the top margin of `widget`.

###### gtk_widget_get_name

Retrieves the name of a widget.

###### gtk_widget_get_native

Returns the nearest `GtkNative` ancestor of `widget`.

###### gtk_widget_get_next_sibling

Returns the widget’s next sibling.

###### gtk_widget_get_opacity

`Fetches` the requested opacity for this widget.

###### gtk_widget_get_overflow

Returns the widget’s overflow value.

###### gtk_widget_get_pango_context

Gets a `PangoContext` with the appropriate font map, font description, and base direction for this widget.

###### gtk_widget_get_parent

Returns the parent widget of `widget`.

###### gtk_widget_get_preferred_size

Retrieves the minimum and natural size of a widget, taking into account the widget’s preference for height-for-width management.

###### gtk_widget_get_prev_sibling

Returns the widget’s previous sibling.

###### gtk_widget_get_primary_clipboard

Gets the primary clipboard of `widget`.

###### gtk_widget_get_realized

Determines whether `widget` is realized.

###### gtk_widget_get_receives_default

Determines whether `widget` is always treated as the default widget within its toplevel when it has the focus, even if another widget is the default.

###### gtk_widget_get_request_mode

Gets whether the widget prefers a height-for-width layout or a width-for-height layout.

###### gtk_widget_get_root

Returns the `GtkRoot` widget of `widget`.

###### gtk_widget_get_scale_factor

Retrieves the internal scale factor that maps from window coordinates to the actual device pixels.

###### gtk_widget_get_sensitive

Returns the widget’s sensitivity.

###### gtk_widget_get_settings

Gets the settings object holding the settings used for this widget.

###### gtk_widget_get_size

Returns the content width or height of the widget.

###### gtk_widget_get_size_request

Gets the size request that was explicitly set for the widget using gtk_widget_set_size_request().

###### gtk_widget_get_state_flags

Returns the widget state as a flag set.

###### gtk_widget_get_style_context

Returns the style context associated to `widget`.

deprecated: 4.10

###### gtk_widget_get_template_child

Fetch an object build from the template XML for `widget_type` in this `widget` instance.

###### gtk_widget_get_tooltip_markup

Gets the contents of the tooltip for `widget`.

###### gtk_widget_get_tooltip_text

Gets the contents of the tooltip for `widget`.

###### gtk_widget_get_valign

Gets the vertical alignment of `widget`.

###### gtk_widget_get_vexpand

Gets whether the widget would like any available extra vertical space.

###### gtk_widget_get_vexpand_set

Gets whether `gtk_widget_set_vexpand()` has been used to explicitly set the expand flag on this widget.

###### gtk_widget_get_visible

Determines whether the widget is visible.

###### gtk_widget_get_width

Returns the content width of the widget.

###### gtk_widget_grab_focus

Causes `widget` to have the keyboard focus for the `GtkWindow` it’s inside.

###### gtk_widget_has_css_class

Returns whether `css_class` is currently applied to `widget`.

###### gtk_widget_has_default

Determines whether `widget` is the current default widget within its toplevel.

###### gtk_widget_has_focus

Determines if the widget has the global input focus.

###### gtk_widget_has_visible_focus

Determines if the widget should show a visible indication that it has the global input focus.

###### gtk_widget_hide

Reverses the effects of gtk_widget_show().

deprecated: 4.10

###### gtk_widget_in_destruction

Returns whether the widget is currently being destroyed.

###### gtk_widget_init_template

Creates and initializes child widgets defined in templates.

###### gtk_widget_insert_action_group

Inserts `group` into `widget`.

###### gtk_widget_insert_after

Inserts `widget` into the child widget list of `parent`.

###### gtk_widget_insert_before

Inserts `widget` into the child widget list of `parent`.

###### gtk_widget_is_ancestor

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

###### gtk_widget_is_drawable

Determines whether `widget` can be drawn to.

###### gtk_widget_is_focus

Determines if the widget is the focus widget within its toplevel.

###### gtk_widget_is_sensitive

Returns the widget’s effective sensitivity.

###### gtk_widget_is_visible

Determines whether the widget and all its parents are marked as visible.

###### gtk_widget_keynav_failed

Emits the `::keynav-failed` signal on the widget.

###### gtk_widget_list_mnemonic_labels

Returns the widgets for which this widget is the target of a mnemonic.

###### gtk_widget_map

Causes a widget to be mapped if it isn’t already.

###### gtk_widget_measure

Measures `widget` in the orientation `orientation` and for the given `for_size`.

###### gtk_widget_mnemonic_activate

Emits the ::mnemonic-activate signal.

###### gtk_widget_observe_children

Returns a `GListModel` to track the children of `widget`.

###### gtk_widget_observe_controllers

Returns a `GListModel` to track the `GtkEventController`s of `widget`.

###### gtk_widget_pick

Finds the descendant of `widget` closest to the point (`x`, `y`).

###### gtk_widget_queue_allocate

Flags the widget for a rerun of the `Gtk.WidgetClass.size_allocate` function.

###### gtk_widget_queue_draw

Schedules this widget to be redrawn in the paint phase of the current or the next frame.

###### gtk_widget_queue_resize

Flags a widget to have its size renegotiated.

###### gtk_widget_realize

Creates the GDK resources associated with a widget.

###### gtk_widget_remove_controller

Removes `controller` from `widget`, so that it doesn’t process events anymore.

###### gtk_widget_remove_css_class

Removes a style from `widget`.

###### gtk_widget_remove_mnemonic_label

Removes a widget from the list of mnemonic labels for this widget.

###### gtk_widget_remove_tick_callback

Removes a tick callback previously registered with gtk_widget_add_tick_callback().

###### gtk_widget_set_can_focus

Specifies whether the input focus can enter the widget or any of its children.

###### gtk_widget_set_can_target

Sets whether `widget` can be the target of pointer events.

###### gtk_widget_set_child_visible

Sets whether `widget` should be mapped along with its parent.

###### gtk_widget_set_css_classes

Clear all style classes applied to `widget` and replace them with `classes`.

###### gtk_widget_set_cursor

Sets the cursor to be shown when pointer devices point towards `widget`.

###### gtk_widget_set_cursor_from_name

Sets a named cursor to be shown when pointer devices point towards `widget`.

###### gtk_widget_set_direction

Sets the reading direction on a particular widget.

###### gtk_widget_set_focus_child

Set `child` as the current focus child of `widget`.

###### gtk_widget_set_focus_on_click

Sets whether the widget should grab focus when it is clicked with the mouse.

###### gtk_widget_set_focusable

Specifies whether `widget` can own the input focus.

###### gtk_widget_set_font_map

Sets the font map to use for Pango rendering.

###### gtk_widget_set_font_options

Sets the `cairo_font_options_t` used for Pango rendering in this widget.

###### gtk_widget_set_halign

Sets the horizontal alignment of `widget`.

###### gtk_widget_set_has_tooltip

Sets the `has-tooltip` property on `widget` to `has_tooltip`.

###### gtk_widget_set_hexpand

Sets whether the widget would like any available extra horizontal space.

###### gtk_widget_set_hexpand_set

Sets whether the hexpand flag will be used.

###### gtk_widget_set_layout_manager

Sets the layout manager delegate instance that provides an implementation for measuring and allocating the children of `widget`.

###### gtk_widget_set_margin_bottom

Sets the bottom margin of `widget`.

###### gtk_widget_set_margin_end

Sets the end margin of `widget`.

###### gtk_widget_set_margin_start

Sets the start margin of `widget`.

###### gtk_widget_set_margin_top

Sets the top margin of `widget`.

###### gtk_widget_set_name

Sets a widgets name.

###### gtk_widget_set_opacity

Request the `widget` to be rendered partially transparent.

###### gtk_widget_set_overflow

Sets how `widget` treats content that is drawn outside the widget’s content area.

###### gtk_widget_set_parent

Sets `parent` as the parent widget of `widget`.

###### gtk_widget_set_receives_default

Specifies whether `widget` will be treated as the default widget within its toplevel when it has the focus, even if another widget is the default.

###### gtk_widget_set_sensitive

Sets the sensitivity of a widget.

###### gtk_widget_set_size_request

Sets the minimum size of a widget.

###### gtk_widget_set_state_flags

Turns on flag values in the current widget state.

###### gtk_widget_set_tooltip_markup

Sets `markup` as the contents of the tooltip, which is marked up with Pango markup.

###### gtk_widget_set_tooltip_text

Sets `text` as the contents of the tooltip.

###### gtk_widget_set_valign

Sets the vertical alignment of `widget`.

###### gtk_widget_set_vexpand

Sets whether the widget would like any available extra vertical space.

###### gtk_widget_set_vexpand_set

Sets whether the vexpand flag will be used.

###### gtk_widget_set_visible

Sets the visibility state of `widget`.

###### gtk_widget_should_layout

Returns whether `widget` should contribute to the measuring and allocation of its parent.

###### gtk_widget_show

Flags a widget to be displayed.

deprecated: 4.10

###### gtk_widget_size_allocate

Allocates widget with a transformation that translates the origin to the position in `allocation`.

###### gtk_widget_snapshot_child

Snapshot the a child of `widget`.

###### gtk_widget_translate_coordinates

Translate coordinates relative to `src_widget`’s allocation to coordinates relative to `dest_widget`’s allocations.

deprecated: 4.12

###### gtk_widget_trigger_tooltip_query

Triggers a tooltip query on the display where the toplevel of `widget` is located.

###### gtk_widget_unmap

Causes a widget to be unmapped if it’s currently mapped.

###### gtk_widget_unparent

Dissociate `widget` from its parent.

###### gtk_widget_unrealize

Causes a widget to be unrealized (frees all GDK resources associated with the widget).

###### gtk_widget_unset_state_flags

Turns off flag values for the current widget state.

##### Methods inherited from GObject (43)

Please see GObject for a full list of methods.

##### Methods inherited from GtkAccessible (19)

###### gtk_accessible_announce

Requests the user’s screen reader to announce the given message.

since: 4.14

###### gtk_accessible_get_accessible_parent

Retrieves the accessible parent for an accessible object.

since: 4.10

###### gtk_accessible_get_accessible_role

Retrieves the accessible role of an accessible object.

###### gtk_accessible_get_at_context

Retrieves the accessible implementation for the given `GtkAccessible`.

since: 4.10

###### gtk_accessible_get_bounds

Queries the coordinates and dimensions of this accessible.

since: 4.10

###### gtk_accessible_get_first_accessible_child

Retrieves the first accessible child of an accessible object.

since: 4.10

###### gtk_accessible_get_next_accessible_sibling

Retrieves the next accessible sibling of an accessible object.

since: 4.10

###### gtk_accessible_get_platform_state

Query a platform state, such as focus.

since: 4.10

###### gtk_accessible_reset_property

Resets the accessible `property` to its default value.

###### gtk_accessible_reset_relation

Resets the accessible `relation` to its default value.

###### gtk_accessible_reset_state

Resets the accessible `state` to its default value.

###### gtk_accessible_set_accessible_parent

Sets the parent and sibling of an accessible object.

since: 4.10

###### gtk_accessible_update_next_accessible_sibling

Updates the next accessible sibling of `self`.

since: 4.10

###### gtk_accessible_update_property

Updates a list of accessible properties.

###### gtk_accessible_update_property_value

Updates an array of accessible properties.

###### gtk_accessible_update_relation

Updates a list of accessible relations.

###### gtk_accessible_update_relation_value

Updates an array of accessible relations.

###### gtk_accessible_update_state

Updates a list of accessible states. See the `GtkAccessibleState` documentation for the value types of accessible states.

###### gtk_accessible_update_state_value

Updates an array of accessible states.

##### Methods inherited from GtkBuildable (1)

###### gtk_buildable_get_buildable_id

Gets the ID of the `buildable` object.

#### Properties

###### Gtk.Widget:can-focus

Whether the widget or any of its descendents can accept the input focus.

###### Gtk.Widget:can-target

Whether the widget can receive pointer events.

###### Gtk.Widget:css-classes

A list of css classes applied to this widget.

###### Gtk.Widget:css-name

The name of this widget in the CSS tree.

###### Gtk.Widget:cursor

The cursor used by `widget`.

###### Gtk.Widget:focus-on-click

Whether the widget should grab focus when it is clicked with the mouse.

###### Gtk.Widget:focusable

Whether this widget itself will accept the input focus.

###### Gtk.Widget:halign

How to distribute horizontal space if widget gets extra space.

###### Gtk.Widget:has-default

Whether the widget is the default widget.

###### Gtk.Widget:has-focus

Whether the widget has the input focus.

###### Gtk.Widget:has-tooltip

Enables or disables the emission of the ::query-tooltip signal on `widget`.

###### Gtk.Widget:height-request

Override for height request of the widget.

###### Gtk.Widget:hexpand

Whether to expand horizontally.

###### Gtk.Widget:hexpand-set

Whether to use the `hexpand` property.

###### Gtk.Widget:layout-manager

The `GtkLayoutManager` instance to use to compute the preferred size of the widget, and allocate its children.

###### Gtk.Widget:margin-bottom

Margin on bottom side of widget.

###### Gtk.Widget:margin-end

Margin on end of widget, horizontally.

###### Gtk.Widget:margin-start

Margin on start of widget, horizontally.

###### Gtk.Widget:margin-top

Margin on top side of widget.

###### Gtk.Widget:name

The name of the widget.

###### Gtk.Widget:opacity

The requested opacity of the widget.

###### Gtk.Widget:overflow

How content outside the widget’s content area is treated.

###### Gtk.Widget:parent

The parent widget of this widget.

###### Gtk.Widget:receives-default

Whether the widget will receive the default action when it is focused.

###### Gtk.Widget:root

The `GtkRoot` widget of the widget tree containing this widget.

###### Gtk.Widget:scale-factor

The scale factor of the widget.

###### Gtk.Widget:sensitive

Whether the widget responds to input.

###### Gtk.Widget:tooltip-markup

Sets the text of tooltip to be the given string, which is marked up with Pango markup.

###### Gtk.Widget:tooltip-text

Sets the text of tooltip to be the given string.

###### Gtk.Widget:valign

How to distribute vertical space if widget gets extra space.

###### Gtk.Widget:vexpand

Whether to expand vertically.

###### Gtk.Widget:vexpand-set

Whether to use the `vexpand` property.

###### Gtk.Widget:visible

Whether the widget is visible.

###### Gtk.Widget:width-request

Override for width request of the widget.

##### Properties inherited from GtkAccessible (1)

###### GtkAccessible:accessible-role

The accessible role of the given `GtkAccessible` implementation.

#### Signals

###### Gtk.Widget::destroy

Signals that all holders of a reference to the widget should release the reference that they hold.

###### Gtk.Widget::direction-changed

Emitted when the text direction of a widget changes.

###### Gtk.Widget::hide

Emitted when `widget` is hidden.

###### Gtk.Widget::keynav-failed

Emitted if keyboard navigation fails.

###### Gtk.Widget::map

Emitted when `widget` is going to be mapped.

###### Gtk.Widget::mnemonic-activate

Emitted when a widget is activated via a mnemonic.

###### Gtk.Widget::move-focus

Emitted when the focus is moved.

###### Gtk.Widget::query-tooltip

Emitted when the widget’s tooltip is about to be shown.

###### Gtk.Widget::realize

Emitted when `widget` is associated with a `GdkSurface`.

###### Gtk.Widget::show

Emitted when `widget` is shown.

###### Gtk.Widget::state-flags-changed

Emitted when the widget state changes.

###### Gtk.Widget::unmap

Emitted when `widget` is going to be unmapped.

###### Gtk.Widget::unrealize

Emitted when the `GdkSurface` associated with `widget` is destroyed.

##### Signals inherited from GObject (1)

###### GObject::notify

The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.

#### Class structure

    struct GtkWidgetClass {
      GInitiallyUnownedClass parent_class;
      void (* show) (
        GtkWidget* widget
      );
      void (* hide) (
        GtkWidget* widget
      );
      void (* map) (
        GtkWidget* widget
      );
      void (* unmap) (
        GtkWidget* widget
      );
      void (* realize) (
        GtkWidget* widget
      );
      void (* unrealize) (
        GtkWidget* widget
      );
      void (* root) (
        GtkWidget* widget
      );
      void (* unroot) (
        GtkWidget* widget
      );
      void (* size_allocate) (
        GtkWidget* widget,
        int width,
        int height,
        int baseline
      );
      void (* state_flags_changed) (
        GtkWidget* widget,
        GtkStateFlags previous_state_flags
      );
      void (* direction_changed) (
        GtkWidget* widget,
        GtkTextDirection previous_direction
      );
      GtkSizeRequestMode (* get_request_mode) (
        GtkWidget* widget
      );
      void (* measure) (
        GtkWidget* widget,
        GtkOrientation orientation,
        int for_size,
        int* minimum,
        int* natural,
        int* minimum_baseline,
        int* natural_baseline
      );
      gboolean (* mnemonic_activate) (
        GtkWidget* widget,
        gboolean group_cycling
      );
      gboolean (* grab_focus) (
        GtkWidget* widget
      );
      gboolean (* focus) (
        GtkWidget* widget,
        GtkDirectionType direction
      );
      void (* set_focus_child) (
        GtkWidget* widget,
        GtkWidget* child
      );
      void (* move_focus) (
        GtkWidget* widget,
        GtkDirectionType direction
      );
      gboolean (* keynav_failed) (
        GtkWidget* widget,
        GtkDirectionType direction
      );
      gboolean (* query_tooltip) (
        GtkWidget* widget,
        int x,
        int y,
        gboolean keyboard_tooltip,
        GtkTooltip* tooltip
      );
      void (* compute_expand) (
        GtkWidget* widget,
        gboolean* hexpand_p,
        gboolean* vexpand_p
      );
      void (* css_changed) (
        GtkWidget* widget,
        GtkCssStyleChange* change
      );
      void (* system_setting_changed) (
        GtkWidget* widget,
        GtkSystemSetting settings
      );
      void (* snapshot) (
        GtkWidget* widget,
        GtkSnapshot* snapshot
      );
      gboolean (* contains) (
        GtkWidget* widget,
        double x,
        double y
      );

    }

No description available.

###### Class members

`parent_class: GInitiallyUnownedClass`

  The object class structure needs to be the first element in the widget class structure in order for the class mechanism to work correctly. This allows a GtkWidgetClass pointer to be cast to a GObjectClass pointer.

`show: void (* show) ( GtkWidget* widget )`

  Signal emitted when widget is shown.

`hide: void (* hide) ( GtkWidget* widget )`

  Signal emitted when widget is hidden.

`map: void (* map) ( GtkWidget* widget )`

  Signal emitted when widget is going to be mapped, that is when the widget is visible (which is controlled with gtk_widget_set_visible()) and all its parents up to the toplevel widget are also visible.

`unmap: void (* unmap) ( GtkWidget* widget )`

  Signal emitted when widget is going to be unmapped, which means that either it or any of its parents up to the toplevel widget have been set as hidden.

`realize: void (* realize) ( GtkWidget* widget )`

  Signal emitted when widget is associated with a `GdkSurface`, which means that `gtk_widget_realize()` has been called or the widget has been mapped (that is, it is going to be drawn).

`unrealize: void (* unrealize) ( GtkWidget* widget )`

  Signal emitted when the GdkSurface associated with widget is destroyed, which means that `gtk_widget_unrealize()` has been called or the widget has been unmapped (that is, it is going to be hidden).

`root: void (* root) ( GtkWidget* widget )`

  Called when the widget gets added to a `GtkRoot` widget. Must chain up.

`unroot: void (* unroot) ( GtkWidget* widget )`

  Called when the widget is about to be removed from its `GtkRoot` widget. Must chain up.

`size_allocate: void (* size_allocate) ( GtkWidget* widget, int width, int height, int baseline )`

  Called to set the allocation, if the widget does not have a layout manager.

`state_flags_changed: void (* state_flags_changed) ( GtkWidget* widget, GtkStateFlags previous_state_flags )`

  Signal emitted when the widget state changes, see gtk_widget_get_state_flags().

`direction_changed: void (* direction_changed) ( GtkWidget* widget, GtkTextDirection previous_direction )`

  Signal emitted when the text direction of a widget changes.

`get_request_mode: GtkSizeRequestMode (* get_request_mode) ( GtkWidget* widget )`

  Called to get the request mode, if the widget does not have a layout manager. This allows a widget to tell its parent container whether it prefers to be allocated in `GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH` or `GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT` mode. `GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH` means the widget prefers to have `GtkWidgetClass.measure()` called first to get the default width (passing a for_size of -1), then again to get the height for said default width. `GTK_SIZE_REQUEST_CONSTANT_SIZE` disables any height-for-width or width-for-height geometry management for said widget and is the default return. It’s important to note that any widget which trades height-for-width or width-for-height must respond properly to a for_size value >= -1 passed to `GtkWidgetClass.measure`, for both possible orientations.

`measure: void (* measure) ( GtkWidget* widget, GtkOrientation orientation, int for_size, int* minimum, int* natural, int* minimum_baseline, int* natural_baseline )`

  Called to obtain the minimum and natural size of the widget, if the widget does not have a layout manager. Depending on the orientation parameter, the passed for_size can be interpreted as width or height. A widget will never be allocated less than its minimum size.

`mnemonic_activate: gboolean (* mnemonic_activate) ( GtkWidget* widget, gboolean group_cycling )`

  Activates the `widget` if `group_cycling` is `FALSE`, and just grabs the focus if `group_cycling` is `TRUE`.

`grab_focus: gboolean (* grab_focus) ( GtkWidget* widget )`

  Causes `widget` to have the keyboard focus for the `GtkWindow` it’s inside.

`focus: gboolean (* focus) ( GtkWidget* widget, GtkDirectionType direction )`

  Vfunc for gtk_widget_child_focus().

`set_focus_child: void (* set_focus_child) ( GtkWidget* widget, GtkWidget* child )`

  Sets the focused child of a widget. Must chain up.

`move_focus: void (* move_focus) ( GtkWidget* widget, GtkDirectionType direction )`

  Signal emitted when a change of focus is requested.

`keynav_failed: gboolean (* keynav_failed) ( GtkWidget* widget, GtkDirectionType direction )`

  Signal emitted if keyboard navigation fails.

`query_tooltip: gboolean (* query_tooltip) ( GtkWidget* widget, int x, int y, gboolean keyboard_tooltip, GtkTooltip* tooltip )`

  Signal emitted when “has-tooltip” is `TRUE` and the hover timeout has expired with the cursor hovering “above” widget; or emitted when widget got focus in keyboard mode.

`compute_expand: void (* compute_expand) ( GtkWidget* widget, gboolean* hexpand_p, gboolean* vexpand_p )`

  Computes whether a container should give this widget extra space when possible.

`css_changed: void (* css_changed) ( GtkWidget* widget, GtkCssStyleChange* change )`

  Vfunc called when the CSS used by widget was changed. Widgets should then discard their caches that depend on CSS and queue resizes or redraws accordingly. The default implementation will take care of this for all the default CSS properties, so implementations must chain up.

`system_setting_changed: void (* system_setting_changed) ( GtkWidget* widget, GtkSystemSetting settings )`

  Emitted when a system setting was changed. Must chain up.

`snapshot: void (* snapshot) ( GtkWidget* widget, GtkSnapshot* snapshot )`

  Vfunc called when a new snapshot of the widget has to be taken.

`contains: gboolean (* contains) ( GtkWidget* widget, double x, double y )`

  Vfunc for gtk_widget_contains().

#### Virtual methods

###### Gtk.WidgetClass.compute_expand

Computes whether a container should give this widget extra space when possible.

###### Gtk.WidgetClass.contains

Tests if the point at (`x`, `y`) is contained in `widget`.

###### Gtk.WidgetClass.css_changed

Vfunc called when the CSS used by widget was changed. Widgets should then discard their caches that depend on CSS and queue resizes or redraws accordingly. The default implementation will take care of this for all the default CSS properties, so implementations must chain up.

###### Gtk.WidgetClass.direction_changed

Signal emitted when the text direction of a widget changes.

###### Gtk.WidgetClass.focus

Vfunc for gtk_widget_child_focus().

###### Gtk.WidgetClass.get_request_mode

Gets whether the widget prefers a height-for-width layout or a width-for-height layout.

###### Gtk.WidgetClass.grab_focus

Causes `widget` to have the keyboard focus for the `GtkWindow` it’s inside.

###### Gtk.WidgetClass.hide

Reverses the effects of gtk_widget_show().

deprecated: 4.10

###### Gtk.WidgetClass.keynav_failed

Emits the `::keynav-failed` signal on the widget.

###### Gtk.WidgetClass.map

Causes a widget to be mapped if it isn’t already.

###### Gtk.WidgetClass.measure

Measures `widget` in the orientation `orientation` and for the given `for_size`.

###### Gtk.WidgetClass.mnemonic_activate

Emits the ::mnemonic-activate signal.

###### Gtk.WidgetClass.move_focus

Signal emitted when a change of focus is requested.

###### Gtk.WidgetClass.query_tooltip

Signal emitted when “has-tooltip” is `TRUE` and the hover timeout has expired with the cursor hovering “above” widget; or emitted when widget got focus in keyboard mode.

###### Gtk.WidgetClass.realize

Creates the GDK resources associated with a widget.

###### Gtk.WidgetClass.root

Called when the widget gets added to a `GtkRoot` widget. Must chain up.

###### Gtk.WidgetClass.set_focus_child

Set `child` as the current focus child of `widget`.

###### Gtk.WidgetClass.show

Flags a widget to be displayed.

deprecated: 4.10

###### Gtk.WidgetClass.size_allocate

Called to set the allocation, if the widget does not have a layout manager.

###### Gtk.WidgetClass.snapshot

Vfunc called when a new snapshot of the widget has to be taken.

###### Gtk.WidgetClass.state_flags_changed

Signal emitted when the widget state changes, see gtk_widget_get_state_flags().

###### Gtk.WidgetClass.system_setting_changed

Emitted when a system setting was changed. Must chain up.

###### Gtk.WidgetClass.unmap

Causes a widget to be unmapped if it’s currently mapped.

###### Gtk.WidgetClass.unrealize

Causes a widget to be unrealized (frees all GDK resources associated with the widget).

###### Gtk.WidgetClass.unroot

Called when the widget is about to be removed from its `GtkRoot` widget. Must chain up.

#### Class methods

###### gtk_widget_class_add_binding

Creates a new shortcut for `widget_class` that calls the given `callback` with arguments read according to `format_string`.

###### gtk_widget_class_add_binding_action

Creates a new shortcut for `widget_class` that activates the given `action_name` with arguments read according to `format_string`.

###### gtk_widget_class_add_binding_signal

Creates a new shortcut for `widget_class` that emits the given action `signal` with arguments read according to `format_string`.

###### gtk_widget_class_add_shortcut

Installs a shortcut in `widget_class`.

###### gtk_widget_class_bind_template_callback_full

Declares a `callback_symbol` to handle `callback_name` from the template XML defined for `widget_type`.

###### gtk_widget_class_bind_template_child_full

Automatically assign an object declared in the class template XML to be set to a location on a freshly built instance’s private data, or alternatively accessible via `gtk_widget_get_template_child()`.

###### gtk_widget_class_get_accessible_role

Retrieves the accessible role used by the given `GtkWidget` class.

###### gtk_widget_class_get_activate_signal

Retrieves the signal id for the activation signal.

###### gtk_widget_class_get_css_name

Gets the name used by this class for matching in CSS code.

###### gtk_widget_class_get_layout_manager_type

Retrieves the type of the `GtkLayoutManager` used by widgets of class `widget_class`.

###### gtk_widget_class_install_action

This should be called at class initialization time to specify actions to be added for all instances of this class.

###### gtk_widget_class_install_property_action

Installs an action called `action_name` on `widget_class` and binds its state to the value of the `property_name` property.

###### gtk_widget_class_query_action

Returns details about the `index_`-th action that has been installed for `widget_class` during class initialization.

###### gtk_widget_class_set_accessible_role

Sets the accessible role used by the given `GtkWidget` class.

###### gtk_widget_class_set_activate_signal

Sets the `GtkWidgetClass.activate_signal` field with the given `signal_id`.

###### gtk_widget_class_set_activate_signal_from_name

Sets the `GtkWidgetClass.activate_signal` field with the signal id for the given `signal_name`.

###### gtk_widget_class_set_css_name

Sets the name to be used for CSS matching of widgets.

###### gtk_widget_class_set_layout_manager_type

Sets the type to be used for creating layout managers for widgets of `widget_class`.

###### gtk_widget_class_set_template

This should be called at class initialization time to specify the `GtkBuilder` XML to be used to extend a widget.

###### gtk_widget_class_set_template_from_resource

A convenience function that calls `gtk_widget_class_set_template()` with the contents of a `GResource`.

###### gtk_widget_class_set_template_scope

For use in language bindings, this will override the default `GtkBuilderScope` to be used when parsing GtkBuilder XML from this class’s template data.