GtkWidget

GtkWidget — Base class for all widgets

Functions

void (*GtkCallback) ()
GtkWidget * gtk_widget_new ()
gboolean gtk_widget_in_destruction ()
void gtk_widget_unparent ()
void gtk_widget_show ()
void gtk_widget_hide ()
void gtk_widget_map ()
void gtk_widget_unmap ()
void gtk_widget_realize ()
void gtk_widget_unrealize ()
void gtk_widget_queue_draw ()
void gtk_widget_queue_resize ()
void gtk_widget_queue_allocate ()
GdkFrameClock * gtk_widget_get_frame_clock ()
gint gtk_widget_get_scale_factor ()
gboolean (*GtkTickCallback) ()
guint gtk_widget_add_tick_callback ()
void gtk_widget_remove_tick_callback ()
void gtk_widget_size_allocate ()
void gtk_widget_allocate ()
void gtk_widget_class_add_shortcut ()
void gtk_widget_class_add_binding ()
void gtk_widget_class_add_binding_signal ()
void gtk_widget_class_add_binding_action ()
void gtk_widget_class_set_layout_manager_type ()
GType gtk_widget_class_get_layout_manager_type ()
gboolean gtk_widget_activate ()
gboolean gtk_widget_is_focus ()
gboolean gtk_widget_grab_focus ()
void gtk_widget_set_name ()
const gchar * gtk_widget_get_name ()
void gtk_widget_set_sensitive ()
void gtk_widget_set_parent ()
GtkRoot * gtk_widget_get_root ()
GtkNative * gtk_widget_get_native ()
GtkWidget * gtk_widget_get_ancestor ()
gboolean gtk_widget_is_ancestor ()
gboolean gtk_widget_translate_coordinates ()
void gtk_widget_add_controller ()
void gtk_widget_remove_controller ()
void gtk_widget_set_direction ()
GtkTextDirection gtk_widget_get_direction ()
void gtk_widget_set_default_direction ()
GtkTextDirection gtk_widget_get_default_direction ()
PangoContext * gtk_widget_create_pango_context ()
PangoContext * gtk_widget_get_pango_context ()
void gtk_widget_set_font_options ()
const cairo_font_options_t * gtk_widget_get_font_options ()
void gtk_widget_set_font_map ()
PangoFontMap * gtk_widget_get_font_map ()
PangoLayout * gtk_widget_create_pango_layout ()
GdkCursor * gtk_widget_get_cursor ()
void gtk_widget_set_cursor ()
void gtk_widget_set_cursor_from_name ()
gboolean gtk_widget_mnemonic_activate ()
void gtk_widget_class_set_accessible_type ()
void gtk_widget_class_set_accessible_role ()
AtkObject * gtk_widget_get_accessible ()
gboolean gtk_widget_child_focus ()
gboolean gtk_widget_get_child_visible ()
GtkWidget * gtk_widget_get_parent ()
GtkSettings * gtk_widget_get_settings ()
GdkClipboard * gtk_widget_get_clipboard ()
GdkClipboard * gtk_widget_get_primary_clipboard ()
GdkDisplay * gtk_widget_get_display ()
void gtk_widget_get_size_request ()
void gtk_widget_set_child_visible ()
void gtk_widget_set_size_request ()
GList * gtk_widget_list_mnemonic_labels ()
void gtk_widget_add_mnemonic_label ()
void gtk_widget_remove_mnemonic_label ()
void gtk_widget_error_bell ()
gboolean gtk_widget_keynav_failed ()
const char * gtk_widget_get_tooltip_markup ()
void gtk_widget_set_tooltip_markup ()
const char * gtk_widget_get_tooltip_text ()
void gtk_widget_set_tooltip_text ()
gboolean gtk_widget_get_has_tooltip ()
void gtk_widget_set_has_tooltip ()
void gtk_widget_trigger_tooltip_query ()
int gtk_widget_get_allocated_width ()
int gtk_widget_get_allocated_height ()
void gtk_widget_get_allocation ()
int gtk_widget_get_allocated_baseline ()
int gtk_widget_get_width ()
int gtk_widget_get_height ()
int gtk_widget_get_size ()
gboolean gtk_widget_compute_bounds ()
gboolean gtk_widget_compute_transform ()
gboolean gtk_widget_compute_point ()
gboolean gtk_widget_contains ()
GtkWidget * gtk_widget_pick ()
gboolean gtk_widget_get_can_focus ()
void gtk_widget_set_can_focus ()
gboolean gtk_widget_get_focusable ()
void gtk_widget_set_focusable ()
gboolean gtk_widget_get_focus_on_click ()
void gtk_widget_set_focus_on_click ()
void gtk_widget_set_focus_child ()
gboolean gtk_widget_get_can_target ()
void gtk_widget_set_can_target ()
gboolean gtk_widget_get_sensitive ()
gboolean gtk_widget_is_sensitive ()
gboolean gtk_widget_get_visible ()
gboolean gtk_widget_is_visible ()
void gtk_widget_set_visible ()
void gtk_widget_set_state_flags ()
void gtk_widget_unset_state_flags ()
GtkStateFlags gtk_widget_get_state_flags ()
gboolean gtk_widget_has_default ()
gboolean gtk_widget_has_focus ()
gboolean gtk_widget_has_visible_focus ()
gboolean gtk_widget_is_drawable ()
void gtk_widget_set_receives_default ()
gboolean gtk_widget_get_receives_default ()
void gtk_widget_set_support_multidevice ()
gboolean gtk_widget_get_support_multidevice ()
gboolean gtk_widget_get_realized ()
gboolean gtk_widget_get_mapped ()
gboolean gtk_widget_device_is_shadowed ()
double gtk_widget_get_opacity ()
void gtk_widget_set_opacity ()
GtkOverflow gtk_widget_get_overflow ()
void gtk_widget_set_overflow ()
void gtk_widget_measure ()
void gtk_widget_snapshot_child ()
GtkWidget * gtk_widget_get_next_sibling ()
GtkWidget * gtk_widget_get_prev_sibling ()
GtkWidget * gtk_widget_get_first_child ()
GtkWidget * gtk_widget_get_last_child ()
void gtk_widget_insert_before ()
void gtk_widget_insert_after ()
void gtk_widget_set_layout_manager ()
GtkLayoutManager * gtk_widget_get_layout_manager ()
gboolean gtk_widget_should_layout ()
const char * gtk_widget_get_css_name ()
void gtk_widget_add_css_class ()
void gtk_widget_remove_css_class ()
gboolean gtk_widget_has_css_class ()
char ** gtk_widget_get_css_classes ()
void gtk_widget_set_css_classes ()
GtkStyleContext * gtk_widget_get_style_context ()
const char * gtk_widget_class_get_css_name ()
void gtk_widget_class_set_css_name ()
GtkRequisition * gtk_requisition_new ()
GtkRequisition * gtk_requisition_copy ()
void gtk_requisition_free ()
GtkSizeRequestMode gtk_widget_get_request_mode ()
void gtk_widget_get_preferred_size ()
gint gtk_distribute_natural_allocation ()
GtkAlign gtk_widget_get_halign ()
void gtk_widget_set_halign ()
GtkAlign gtk_widget_get_valign ()
void gtk_widget_set_valign ()
gint gtk_widget_get_margin_start ()
void gtk_widget_set_margin_start ()
gint gtk_widget_get_margin_end ()
void gtk_widget_set_margin_end ()
gint gtk_widget_get_margin_top ()
void gtk_widget_set_margin_top ()
gint gtk_widget_get_margin_bottom ()
void gtk_widget_set_margin_bottom ()
gboolean gtk_widget_get_hexpand ()
void gtk_widget_set_hexpand ()
gboolean gtk_widget_get_hexpand_set ()
void gtk_widget_set_hexpand_set ()
gboolean gtk_widget_get_vexpand ()
void gtk_widget_set_vexpand ()
gboolean gtk_widget_get_vexpand_set ()
void gtk_widget_set_vexpand_set ()
gboolean gtk_widget_compute_expand ()
void gtk_widget_init_template ()
void gtk_widget_class_set_template ()
void gtk_widget_class_set_template_from_resource ()
GObject * gtk_widget_get_template_child ()
#define gtk_widget_class_bind_template_child()
#define gtk_widget_class_bind_template_child_internal()
#define gtk_widget_class_bind_template_child_private()
#define gtk_widget_class_bind_template_child_internal_private()
void gtk_widget_class_bind_template_child_full ()
#define gtk_widget_class_bind_template_callback()
void gtk_widget_class_bind_template_callback_full ()
void gtk_widget_class_set_template_scope ()
GListModel * gtk_widget_observe_children ()
GListModel * gtk_widget_observe_controllers ()
void gtk_widget_insert_action_group ()
gboolean gtk_widget_activate_action ()
gboolean gtk_widget_activate_action_variant ()
void gtk_widget_activate_default ()
void (*GtkWidgetActionActivateFunc) ()
void gtk_widget_class_install_action ()
void gtk_widget_class_install_property_action ()
gboolean gtk_widget_class_query_action ()
void gtk_widget_action_set_enabled ()

Properties

gboolean can-focus Read / Write
gboolean can-target Read / Write
GStrv css-classes Read / Write
gchar * css-name Read / Write / Construct Only
GdkCursor * cursor Read / Write
gboolean focus-on-click Read / Write
gboolean focusable Read / Write
GtkAlign halign Read / Write
gboolean has-default Read
gboolean has-focus Read
gboolean has-tooltip Read / Write
gint height-request Read / Write
gboolean hexpand Read / Write
gboolean hexpand-set Read / Write
GtkLayoutManager * layout-manager Read / Write
gint margin-bottom Read / Write
gint margin-end Read / Write
gint margin-start Read / Write
gint margin-top Read / Write
gchar * name Read / Write
gdouble opacity Read / Write
GtkOverflow overflow Read / Write
GtkWidget * parent Read
gboolean receives-default Read / Write
GtkRoot * root Read
gint scale-factor Read
gboolean sensitive Read / Write
gchar * tooltip-markup Read / Write
gchar * tooltip-text Read / Write
GtkAlign valign Read / Write
gboolean vexpand Read / Write
gboolean vexpand-set Read / Write
gboolean visible Read / Write
gint width-request Read / Write

Signals

void destroy No Hooks
void direction-changed Run First
void grab-notify Run First
void hide Run First
gboolean keynav-failed Run Last
void map Run First
gboolean mnemonic-activate Run Last
void move-focus Action
gboolean query-tooltip Run Last
void realize Run First
void show Run First
void state-flags-changed Run First
void unmap Run First
void unrealize Run Last

Object Hierarchy

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

Known Derived Interfaces

GtkWidget is required by GtkActionable, GtkAppChooser, GtkCellEditable, GtkEditable, GtkNative and GtkRoot.

Implemented Interfaces

GtkWidget implements AtkImplementorIface, GtkBuildable and GtkConstraintTarget.

Includes

#include <gtk/gtk.h>

Description

GtkWidget is the base class all widgets in GTK+ derive from. It manages the widget lifecycle, 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:

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 GtkWidgetClass.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 GtkWidgetClass.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 (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 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 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.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:

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
26
27
28
29
30
31
32
33
34
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 GtkWidgetClass.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 of GTK_ALIGN_BASELINE, 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 GtkWidgetClass.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_allocated_baseline(). If this 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 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="GtkLabel" 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>

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
<object class="MyGrid" id="grid1">
  <child>
    <object class="GtkLabel" id="label1">
      <property name="label">Description</property>
      <layout>
        <property name="left-attach">0</property>
        <property name="top-attach">0</property>
        <property name="row-span">1</property>
        <property name="col-span">1</property>
      </layout>
    </object>
  </child>
  <child>
    <object class="GtkEntry" id="description_entry">
      <layout>
        <property name="left-attach">1</property>
        <property name="top-attach">0</property>
        <property name="row-span">1</property>
        <property name="col-span">1</property>
      </layout>
    </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">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
19
20
21
22
23
24
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);
}

static void
foo_widget_init (FooWidget *widget)
{

}

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

Functions

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

Parameters

widget

the widget to operate on

 

data

user-supplied data.

[closure]

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.

Parameters

type

type ID of the widget to create

 

first_property_name

name of first property to set

 

...

value of first property, followed by more properties, NULL-terminated

 

Returns

a new GtkWidget of type widget_type


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.

Parameters

widget

a GtkWidget

 

Returns

TRUE if widget is being destroyed


gtk_widget_unparent ()

void
gtk_widget_unparent (GtkWidget *widget);

This function is only for use in widget implementations. Should be called by parent widgets to dissociate widget from the parent.

Parameters

widget

a GtkWidget

 

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.

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.

Parameters

widget

a GtkWidget

 

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

Parameters

widget

a GtkWidget

 

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.

Parameters

widget

a GtkWidget

 

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.

Parameters

widget

a GtkWidget

 

gtk_widget_realize ()

void
gtk_widget_realize (GtkWidget *widget);

Creates the GDK (windowing system) resources associated with a widget. 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 “realize”.

Parameters

widget

a GtkWidget

 

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

Parameters

widget

a GtkWidget

 

gtk_widget_queue_draw ()

void
gtk_widget_queue_draw (GtkWidget *widget);

Schedules this widget to be redrawn in paint phase of the current or the next frame. This means widget 's GtkWidgetClass.snapshot() implementation will be called.

Parameters

widget

a GtkWidget

 

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.

Parameters

widget

a GtkWidget

 

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

Parameters

widget

a GtkWidget

 

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.

Parameters

widget

a GtkWidget

 

Returns

a GdkFrameClock, or NULL if widget is unrealized.

[nullable][transfer none]


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

Parameters

widget

a GtkWidget

 

Returns

the scale factor for widget


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

Parameters

widget

the widget

 

frame_clock

the frame clock for the widget (same as calling gtk_widget_get_frame_clock())

 

user_data

user data passed to gtk_widget_add_tick_callback().

 

Returns

G_SOURCE_CONTINUE if the tick callback should continue to be called, G_SOURCE_REMOVE if the tick callback should be removed.


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

Parameters

widget

a GtkWidget

 

callback

function to call for updating animations

 

user_data

data to pass to callback .

[closure]

notify

function to call to free user_data when the callback is removed.

 

Returns

an id for the connection of this callback. Remove the callback by passing the id returned from this function to gtk_widget_remove_tick_callback()


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

Parameters

widget

a GtkWidget

 

id

an id returned by gtk_widget_add_tick_callback()

 

gtk_widget_size_allocate ()

void
gtk_widget_size_allocate (GtkWidget *widget,
                          const GtkAllocation *allocation,
                          int baseline);

This is a simple form of gtk_widget_allocate() that takes the new position of widget as part of allocation .

Parameters

widget

a GtkWidget

 

allocation

position and size to be allocated to widget

 

baseline

The baseline of the child, or -1

 

gtk_widget_allocate ()

void
gtk_widget_allocate (GtkWidget *widget,
                     int width,
                     int height,
                     int baseline,
                     GskTransform *transform);

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

In this function, the allocation and baseline may be adjusted. The given allocation will be forced to be bigger than the widget's minimum size, as well as at least 0×0 in size.

For a version that does not take a transform, see gtk_widget_size_allocate()

Parameters

widget

A GtkWidget

 

width

New width of widget

 

height

New height of widget

 

baseline

New baseline of widget , or -1

 

transform

Transformation to be applied to widget .

[transfer full][allow-none]

gtk_widget_class_add_shortcut ()

void
gtk_widget_class_add_shortcut (GtkWidgetClass *widget_class,
                               GtkShortcut *shortcut);

Installs a shortcut in widget_class . Every instance created for widget_class or its subclasses will inherit this shortcut and trigger it.

Shortcuts added this way will be triggered in the GTK_PHASE_BUBBLE phase, which means they may also trigger if child widgets have focus.

This function must only be used in class initialization functions otherwise it is not guaranteed that the shortcut will be installed.

Parameters

widget_class

the class to add the shortcut to

 

shortcut

the GtkShortcut to add.

[transfer none]

gtk_widget_class_add_binding ()

void
gtk_widget_class_add_binding (GtkWidgetClass *widget_class,
                              guint keyval,
                              GdkModifierType mods,
                              GtkShortcutFunc callback,
                              const gchar *format_string,
                              ...);

Creates a new shortcut for widget_class that calls the given callback with arguments read according to format_string . The arguments and format string must be provided in the same way as with g_variant_new().

This function is a convenience wrapper around gtk_widget_class_add_shortcut() and must be called during class initialization. It does not provide for user_data, if you need that, you will have to use gtk_widget_class_add_shortcut() with a custom shortcut.

[skip]

Parameters

widget_class

the class to add the binding to

 

keyval

key value of binding to install

 

mods

key modifier of binding to install

 

callback

the callback to call upon activation

 

format_string

GVariant format string for arguments or NULL for no arguments

 

...

arguments, as given by format string.

 

gtk_widget_class_add_binding_signal ()

void
gtk_widget_class_add_binding_signal (GtkWidgetClass *widget_class,
                                     guint keyval,
                                     GdkModifierType mods,
                                     const gchar *signal,
                                     const gchar *format_string,
                                     ...);

Creates a new shortcut for widget_class that emits the given action signal with arguments read according to format_string . The arguments and format string must be provided in the same way as with g_variant_new().

This function is a convenience wrapper around gtk_widget_class_add_shortcut() and must be called during class initialization.

[skip]

Parameters

widget_class

the class to add the binding to

 

keyval

key value of binding to install

 

mods

key modifier of binding to install

 

signal

the signal to execute

 

format_string

GVariant format string for arguments or NULL for no arguments

 

...

arguments, as given by format string.

 

gtk_widget_class_add_binding_action ()

void
gtk_widget_class_add_binding_action (GtkWidgetClass *widget_class,
                                     guint keyval,
                                     GdkModifierType mods,
                                     const gchar *action_name,
                                     const gchar *format_string,
                                     ...);

Creates a new shortcut for widget_class that activates the given action_name with arguments read according to format_string . The arguments and format string must be provided in the same way as with g_variant_new().

This function is a convenience wrapper around gtk_widget_class_add_shortcut() and must be called during class initialization.

[skip]

Parameters

widget_class

the class to add the binding to

 

keyval

key value of binding to install

 

mods

key modifier of binding to install

 

action_name

the action to activate

 

format_string

GVariant format string for arguments or NULL for no arguments

 

...

arguments, as given by format string.

 

gtk_widget_class_set_layout_manager_type ()

void
gtk_widget_class_set_layout_manager_type
                               (GtkWidgetClass *widget_class,
                                GType type);

Sets the type to be used for creating layout managers for widgets of widget_class . The given type must be a subtype of GtkLayoutManager.

This function should only be called from class init functions of widgets.

Parameters

widget_class

class to set the layout manager type for

 

type

The object type that implements the GtkLayoutManager for widget_class

 

gtk_widget_class_get_layout_manager_type ()

GType
gtk_widget_class_get_layout_manager_type
                               (GtkWidgetClass *widget_class);

Retrieves the type of the GtkLayoutManager used by the GtkWidget class.

See also: gtk_widget_class_set_layout_manager_type()

Parameters

widget_class

a GtkWidgetClass

 

Returns

a GtkLayoutManager subclass, or G_TYPE_INVALID


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.

Parameters

widget

a GtkWidget that’s activatable

 

Returns

TRUE if the widget was activatable


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

Parameters

widget

a GtkWidget

 

Returns

TRUE if the widget is the focus widget.


gtk_widget_grab_focus ()

gboolean
gtk_widget_grab_focus (GtkWidget *widget);

Causes widget (or one of its descendents) to have the keyboard focus for the GtkWindow it's inside.

If widget is not focusable, or its ::grab_focus implementation cannot transfer the focus to a descendant of widget that is focusable, it will not take focus and FALSE will be returned.

Calling gtk_widget_grab_focus() on an already focused widget is allowed, should not have an effect, and return TRUE.

Parameters

widget

a GtkWidget

 

Returns

TRUE if focus is now inside widget .


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.

Parameters

widget

a GtkWidget

 

name

name for the widget

 

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.

Parameters

widget

a GtkWidget

 

Returns

name of the widget. This string is owned by GTK+ and should not be modified or freed


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.

Parameters

widget

a GtkWidget

 

sensitive

TRUE to make the widget sensitive

 

gtk_widget_set_parent ()

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

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

Parameters

widget

a GtkWidget

 

parent

parent widget

 

gtk_widget_get_root ()

GtkRoot *
gtk_widget_get_root (GtkWidget *widget);

Returns the GtkRoot widget of widget or NULL if the widget is not contained inside a widget tree with a root widget.

GtkRoot widgets will return themselves here.

Parameters

widget

a GtkWidget

 

Returns

the root widget of widget , or NULL.

[transfer none][nullable]


gtk_widget_get_native ()

GtkNative *
gtk_widget_get_native (GtkWidget *widget);

Returns the GtkNative widget that contains widget , or NULL if the widget is not contained inside a widget tree with a native ancestor.

GtkNative widgets will return themselves here.

Parameters

widget

a GtkWidget

 

Returns

the GtkNative widget of widget , or NULL.

[transfer none][nullable]


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.

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

Parameters

widget

a GtkWidget

 

widget_type

ancestor type

 

Returns

the ancestor widget, or NULL if not found.

[transfer none][nullable]


gtk_widget_is_ancestor ()

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

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

Parameters

widget

a GtkWidget

 

ancestor

another GtkWidget

 

Returns

TRUE if ancestor contains widget as a child, grandchild, great grandchild, etc.


gtk_widget_translate_coordinates ()

gboolean
gtk_widget_translate_coordinates (GtkWidget *src_widget,
                                  GtkWidget *dest_widget,
                                  double src_x,
                                  double src_y,
                                  double *dest_x,
                                  double *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 widget must share a common toplevel.

Parameters

src_widget

a GtkWidget

 

dest_widget

a GtkWidget

 

src_x

X position relative to src_widget

 

src_y

Y position relative to src_widget

 

dest_x

location to store X position relative to dest_widget .

[out][optional]

dest_y

location to store Y position relative to dest_widget .

[out][optional]

Returns

FALSE if src_widget and dest_widget have no common ancestor. In this case, 0 is stored in *dest_x and *dest_y . Otherwise TRUE.


gtk_widget_add_controller ()

void
gtk_widget_add_controller (GtkWidget *widget,
                           GtkEventController *controller);

Adds controller to widget so that it will receive events. You will usually want to call this function right after creating any kind of GtkEventController.

Parameters

widget

a GtkWidget

 

controller

a GtkEventController that hasn't been added to a widget yet.

[transfer full]

gtk_widget_remove_controller ()

void
gtk_widget_remove_controller (GtkWidget *widget,
                              GtkEventController *controller);

Removes controller from widget , so that it doesn't process events anymore. It should not be used again.

Widgets will remove all event controllers automatically when they are destroyed, there is normally no need to call this function.

Parameters

widget

a GtkWidget

 

controller

a GtkEventController.

[transfer none]

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.

Parameters

widget

a GtkWidget

 

dir

the new direction

 

gtk_widget_get_direction ()

GtkTextDirection
gtk_widget_get_direction (GtkWidget *widget);

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

Parameters

widget

a GtkWidget

 

Returns

the reading direction for the widget.


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

Parameters

dir

the new default direction. This cannot be GTK_TEXT_DIR_NONE.

 

gtk_widget_get_default_direction ()

GtkTextDirection
gtk_widget_get_default_direction (void);

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

Returns

the current default direction.


gtk_widget_create_pango_context ()

PangoContext *
gtk_widget_create_pango_context (GtkWidget *widget);

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

Parameters

widget

a GtkWidget

 

Returns

the new PangoContext.

[transfer full]


gtk_widget_get_pango_context ()

PangoContext *
gtk_widget_get_pango_context (GtkWidget *widget);

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

Parameters

widget

a GtkWidget

 

Returns

the PangoContext for the widget.

[transfer none]


gtk_widget_set_font_options ()

void
gtk_widget_set_font_options (GtkWidget *widget,
                             const cairo_font_options_t *options);

Sets the cairo_font_options_t used for Pango rendering in this widget. When not set, the default font options for the GdkDisplay will be used.

Parameters

widget

a GtkWidget

 

options

a cairo_font_options_t, or NULL to unset any previously set default font options.

[allow-none]

gtk_widget_get_font_options ()

const cairo_font_options_t *
gtk_widget_get_font_options (GtkWidget *widget);

Returns the cairo_font_options_t used for Pango rendering. When not set, the defaults font options for the GdkDisplay will be used.

Parameters

widget

a GtkWidget

 

Returns

the cairo_font_options_t or NULL if not set.

[transfer none][nullable]


gtk_widget_set_font_map ()

void
gtk_widget_set_font_map (GtkWidget *widget,
                         PangoFontMap *font_map);

Sets the font map to use for Pango rendering. When not set, the widget will inherit the font map from its parent.

Parameters

widget

a GtkWidget

 

font_map

a PangoFontMap, or NULL to unset any previously set font map.

[allow-none]

gtk_widget_get_font_map ()

PangoFontMap *
gtk_widget_get_font_map (GtkWidget *widget);

Gets the font map that has been set with gtk_widget_set_font_map().

Parameters

widget

a GtkWidget

 

Returns

A PangoFontMap, or NULL.

[transfer none][nullable]


gtk_widget_create_pango_layout ()

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

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

If you keep a PangoLayout created in this way around, you need to re-create it when the widget PangoContext is replaced. This can be tracked by listening to changes of the “root” property on the widget.

Parameters

widget

a GtkWidget

 

text

text to set on the layout (can be NULL).

[nullable]

Returns

the new PangoLayout.

[transfer full]


gtk_widget_get_cursor ()

GdkCursor *
gtk_widget_get_cursor (GtkWidget *widget);

Queries the cursor set via gtk_widget_set_cursor(). See that function for details.

Parameters

widget

a GtkWidget

 

Returns

the cursor currently in use or NULL to use the default.

[nullable][transfer none]


gtk_widget_set_cursor ()

void
gtk_widget_set_cursor (GtkWidget *widget,
                       GdkCursor *cursor);

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

If the cursor is NULL, widget will use the cursor inherited from the parent widget.

Parameters

widget

a GtkWidget

 

cursor

the new cursor or NULL to use the default cursor.

[allow-none]

gtk_widget_set_cursor_from_name ()

void
gtk_widget_set_cursor_from_name (GtkWidget *widget,
                                 const char *name);

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

This is a utility function that creates a cursor via gdk_cursor_new_from_name() and then sets it on widget with gtk_widget_set_cursor(). See those 2 functions for details.

On top of that, this function allows name to be NULL, which will do the same as calling gtk_widget_set_cursor() with a NULL cursor.

Parameters

widget

a GtkWidget

 

name

The name of the cursor or NULL to use the default cursor.

[nullable]

gtk_widget_mnemonic_activate ()

gboolean
gtk_widget_mnemonic_activate (GtkWidget *widget,
                              gboolean group_cycling);

Emits the “mnemonic-activate” signal.

Parameters

widget

a GtkWidget

 

group_cycling

TRUE if there are other widgets with the same mnemonic

 

Returns

TRUE if the signal has been handled


gtk_widget_class_set_accessible_type ()

void
gtk_widget_class_set_accessible_type (GtkWidgetClass *widget_class,
                                      GType type);

Sets the type to be used for creating accessibles for widgets of widget_class . The given type must be a subtype of the type used for accessibles of the parent class.

This function should only be called from class init functions of widgets.

Parameters

widget_class

class to set the accessible type for

 

type

The object type that implements the accessible for widget_class

 

gtk_widget_class_set_accessible_role ()

void
gtk_widget_class_set_accessible_role (GtkWidgetClass *widget_class,
                                      AtkRole role);

Sets the default AtkRole to be set on accessibles created for widgets of widget_class . Accessibles may decide to not honor this setting if their role reporting is more refined. Calls to gtk_widget_class_set_accessible_type() will reset this value.

In cases where you want more fine-grained control over the role of accessibles created for widget_class , you should provide your own accessible type and use gtk_widget_class_set_accessible_type() instead.

If role is ATK_ROLE_INVALID, the default role will not be changed and the accessible’s default role will be used instead.

This function should only be called from class init functions of widgets.

Parameters

widget_class

class to set the accessible role for

 

role

The role to use for accessibles created for widget_class

 

gtk_widget_get_accessible ()

AtkObject *
gtk_widget_get_accessible (GtkWidget *widget);

Returns the accessible object that describes the widget to an assistive technology.

If accessibility support is not available, this AtkObject instance may be a no-op. Likewise, if no class-specific AtkObject implementation is available for the widget instance in question, it will inherit an AtkObject implementation from the first ancestor class for which such an implementation is defined.

The documentation of the ATK library contains more information about accessible objects and their uses.

Parameters

widget

a GtkWidget

 

Returns

the AtkObject associated with widget .

[transfer none]


gtk_widget_child_focus ()

gboolean
gtk_widget_child_focus (GtkWidget *widget,
                        GtkDirectionType direction);

This function is used by custom widget implementations; if you're writing an app, you’d use gtk_widget_grab_focus() to move the focus to a particular widget.

gtk_widget_child_focus() is called by widgets as the user moves around the window using keyboard shortcuts. direction indicates what kind of motion is taking place (up, down, left, right, tab forward, tab backward). gtk_widget_child_focus() emits the “focus” signal; widgets override the default handler for this signal in order to implement appropriate focus behavior.

The default ::focus handler for a widget should return TRUE if moving in direction left the focus on a focusable location inside that widget, and FALSE if moving in direction moved the focus outside the widget. If returning TRUE, widgets normally call gtk_widget_grab_focus() to place the focus accordingly; if returning FALSE, they don’t modify the current focus location.

Parameters

widget

a GtkWidget

 

direction

direction of focus movement

 

Returns

TRUE if focus ended up inside widget


gtk_widget_get_child_visible ()

gboolean
gtk_widget_get_child_visible (GtkWidget *widget);

Gets the value set with gtk_widget_set_child_visible(). If you feel a need to use this function, your code probably needs reorganization.

This function is only useful for container implementations and never should be called by an application.

Parameters

widget

a GtkWidget

 

Returns

TRUE if the widget is mapped with the parent.


gtk_widget_get_parent ()

GtkWidget *
gtk_widget_get_parent (GtkWidget *widget);

Returns the parent widget of widget .

Parameters

widget

a GtkWidget

 

Returns

the parent widget of widget , or NULL.

[transfer none][nullable]


gtk_widget_get_settings ()

GtkSettings *
gtk_widget_get_settings (GtkWidget *widget);

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

Note that this function can only be called when the GtkWidget is attached to a toplevel, since the settings object is specific to a particular GdkDisplay. If you want to monitor the widget for changes in its settings, connect to notify::display.

Parameters

widget

a GtkWidget

 

Returns

the relevant GtkSettings object.

[transfer none]


gtk_widget_get_clipboard ()

GdkClipboard *
gtk_widget_get_clipboard (GtkWidget *widget);

This is a utility function to get the clipboard object for the GdkDisplay that widget is using.

Note that this function always works, even when widget is not realized yet.

Parameters

widget

a GtkWidget

 

Returns

the appropriate clipboard object.

[transfer none]


gtk_widget_get_primary_clipboard ()

GdkClipboard *
gtk_widget_get_primary_clipboard (GtkWidget *widget);

This is a utility function to get the primary clipboard object for the GdkDisplay that widget is using.

Note that this function always works, even when widget is not realized yet.

Parameters

widget

a GtkWidget

 

Returns

the appropriate clipboard object.

[transfer none]


gtk_widget_get_display ()

GdkDisplay *
gtk_widget_get_display (GtkWidget *widget);

Get the GdkDisplay for the toplevel window associated with this widget. This function can only be called after the widget has been added to a widget hierarchy with a GtkWindow at the top.

In general, you should only create display specific resources when a widget has been realized, and you should free those resources when the widget is unrealized.

Parameters

widget

a GtkWidget

 

Returns

the GdkDisplay for the toplevel for this widget.

[transfer none]


gtk_widget_get_size_request ()

void
gtk_widget_get_size_request (GtkWidget *widget,
                             gint *width,
                             gint *height);

Gets the size request that was explicitly set for the widget using gtk_widget_set_size_request(). A value of -1 stored in width or height indicates that that dimension has not been set explicitly and the natural requisition of the widget will be used instead. See gtk_widget_set_size_request(). To get the size a widget will actually request, call gtk_widget_measure() instead of this function.

Parameters

widget

a GtkWidget

 

width

return location for width, or NULL.

[out][allow-none]

height

return location for height, or NULL.

[out][allow-none]

gtk_widget_set_child_visible ()

void
gtk_widget_set_child_visible (GtkWidget *widget,
                              gboolean child_visible);

Sets whether widget should be mapped along with its when its parent is mapped and widget has been shown with gtk_widget_show().

The child visibility can be set for widget before it is added to a container with gtk_widget_set_parent(), to avoid mapping children unnecessary before immediately unmapping them. However it will be reset to its default state of TRUE when the widget is removed from a container.

Note that changing the child visibility of a widget does not queue a resize on the widget. Most of the time, the size of a widget is computed from all visible children, whether or not they are mapped. If this is not the case, the container can queue a resize itself.

This function is only useful for container implementations and never should be called by an application.

Parameters

widget

a GtkWidget

 

child_visible

if TRUE, widget should be mapped along with its parent.

 

gtk_widget_set_size_request ()

void
gtk_widget_set_size_request (GtkWidget *widget,
                             gint width,
                             gint height);

Sets the minimum size of a widget; that is, the widget’s size request will be at least width by height . You can use this function to force a widget to be larger than it normally would be.

In most cases, gtk_window_set_default_size() is a better choice for toplevel windows than this function; setting the default size will still allow users to shrink the window. Setting the size request will force them to leave the window at least as large as the size request. When dealing with window sizes, gtk_window_set_geometry_hints() can be a useful function as well.

Note the inherent danger of setting any fixed size - themes, translations into other languages, different fonts, and user action can all change the appropriate size for a given widget. So, it's basically impossible to hardcode a size that will always be correct.

The size request of a widget is the smallest size a widget can accept while still functioning well and drawing itself correctly. However in some strange cases a widget may be allocated less than its requested size, and in many cases a widget may be allocated more space than it requested.

If the size request in a given direction is -1 (unset), then the “natural” size request of the widget will be used instead.

The size request set here does not include any margin from the GtkWidget properties margin-left, margin-right, margin-top, and margin-bottom, but it does include pretty much all other padding or border properties set by any subclass of GtkWidget.

Parameters

widget

a GtkWidget

 

width

width widget should request, or -1 to unset

 

height

height widget should request, or -1 to unset

 

gtk_widget_list_mnemonic_labels ()

GList *
gtk_widget_list_mnemonic_labels (GtkWidget *widget);

Returns a newly allocated list of the widgets, normally labels, for which this widget is the target of a mnemonic (see for example, gtk_label_set_mnemonic_widget()).

The widgets in the list are not individually referenced. If you want to iterate through the list and perform actions involving callbacks that might destroy the widgets, you must call g_list_foreach (result, (GFunc)g_object_ref, NULL) first, and then unref all the widgets afterwards.

Parameters

widget

a GtkWidget

 

Returns

the list of mnemonic labels; free this list with g_list_free() when you are done with it.

[element-type GtkWidget][transfer container]


gtk_widget_add_mnemonic_label ()

void
gtk_widget_add_mnemonic_label (GtkWidget *widget,
                               GtkWidget *label);

Adds a widget to the list of mnemonic labels for this widget. (See gtk_widget_list_mnemonic_labels()). Note the list of mnemonic labels for the widget is cleared when the widget is destroyed, so the caller must make sure to update its internal state at this point as well, by using a connection to the “destroy” signal or a weak notifier.

Parameters

widget

a GtkWidget

 

label

a GtkWidget that acts as a mnemonic label for widget

 

gtk_widget_remove_mnemonic_label ()

void
gtk_widget_remove_mnemonic_label (GtkWidget *widget,
                                  GtkWidget *label);

Removes a widget from the list of mnemonic labels for this widget. (See gtk_widget_list_mnemonic_labels()). The widget must have previously been added to the list with gtk_widget_add_mnemonic_label().

Parameters

widget

a GtkWidget

 

label

a GtkWidget that was previously set as a mnemonic label for widget with gtk_widget_add_mnemonic_label().

 

gtk_widget_error_bell ()

void
gtk_widget_error_bell (GtkWidget *widget);

Notifies the user about an input-related error on this widget. If the “gtk-error-bell” setting is TRUE, it calls gdk_surface_beep(), otherwise it does nothing.

Note that the effect of gdk_surface_beep() can be configured in many ways, depending on the windowing backend and the desktop environment or window manager that is used.

Parameters

widget

a GtkWidget

 

gtk_widget_keynav_failed ()

gboolean
gtk_widget_keynav_failed (GtkWidget *widget,
                          GtkDirectionType direction);

This function should be called whenever keyboard navigation within a single widget hits a boundary. The function emits the “keynav-failed” signal on the widget and its return value should be interpreted in a way similar to the return value of gtk_widget_child_focus():

When TRUE is returned, stay in the widget, the failed keyboard navigation is OK and/or there is nowhere we can/should move the focus to.

When FALSE is returned, the caller should continue with keyboard navigation outside the widget, e.g. by calling gtk_widget_child_focus() on the widget’s toplevel.

The default ::keynav-failed handler returns FALSE for GTK_DIR_TAB_FORWARD and GTK_DIR_TAB_BACKWARD. For the other values of GtkDirectionType it returns TRUE.

Whenever the default handler returns TRUE, it also calls gtk_widget_error_bell() to notify the user of the failed keyboard navigation.

A use case for providing an own implementation of ::keynav-failed (either by connecting to it or by overriding it) would be a row of GtkEntry widgets where the user should be able to navigate the entire row with the cursor keys, as e.g. known from user interfaces that require entering license keys.

Parameters

widget

a GtkWidget

 

direction

direction of focus movement

 

Returns

TRUE if stopping keyboard navigation is fine, FALSE if the emitting widget should try to handle the keyboard navigation attempt in its parent container(s).


gtk_widget_get_tooltip_markup ()

const char *
gtk_widget_get_tooltip_markup (GtkWidget *widget);

Gets the contents of the tooltip for widget set using gtk_widget_set_tooltip_markup().

Parameters

widget

a GtkWidget

 

Returns

the tooltip text.

[nullable]


gtk_widget_set_tooltip_markup ()

void
gtk_widget_set_tooltip_markup (GtkWidget *widget,
                               const char *markup);

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

This function will take care of setting the “has-tooltip” as a side effect, and of the default handler for the “query-tooltip” signal.

See also the “tooltip-markup” property and gtk_tooltip_set_markup().

Parameters

widget

a GtkWidget

 

markup

the contents of the tooltip for widget .

[nullable]

gtk_widget_get_tooltip_text ()

const char *
gtk_widget_get_tooltip_text (GtkWidget *widget);

Gets the contents of the tooltip for widget .

If the widget 's tooltip was set using gtk_widget_set_tooltip_markup(), this function will return the escaped text.

Parameters

widget

a GtkWidget

 

Returns

the tooltip text.

[nullable]


gtk_widget_set_tooltip_text ()

void
gtk_widget_set_tooltip_text (GtkWidget *widget,
                             const char *text);

Sets text as the contents of the tooltip.

If text contains any markup, it will be escaped.

This function will take care of setting “has-tooltip” as a side effect, and of the default handler for the “query-tooltip” signal.

See also the “tooltip-text” property and gtk_tooltip_set_text().

Parameters

widget

a GtkWidget

 

text

the contents of the tooltip for widget .

[nullable]

gtk_widget_get_has_tooltip ()

gboolean
gtk_widget_get_has_tooltip (GtkWidget *widget);

Returns the current value of the has-tooltip property. See “has-tooltip” for more information.

Parameters

widget

a GtkWidget

 

Returns

current value of has-tooltip on widget .


gtk_widget_set_has_tooltip ()

void
gtk_widget_set_has_tooltip (GtkWidget *widget,
                            gboolean has_tooltip);

Sets the has-tooltip property on widget to has_tooltip . See “has-tooltip” for more information.

Parameters

widget

a GtkWidget

 

has_tooltip

whether or not widget has a tooltip.

 

gtk_widget_trigger_tooltip_query ()

void
gtk_widget_trigger_tooltip_query (GtkWidget *widget);

Triggers a tooltip query on the display where the toplevel of widget is located. See gtk_tooltip_trigger_tooltip_query() for more information.

Parameters

widget

a GtkWidget

 

gtk_widget_get_allocated_width ()

int
gtk_widget_get_allocated_width (GtkWidget *widget);

Returns the width that has currently been allocated to widget .

Parameters

widget

the widget to query

 

Returns

the width of the widget


gtk_widget_get_allocated_height ()

int
gtk_widget_get_allocated_height (GtkWidget *widget);

Returns the height that has currently been allocated to widget .

Parameters

widget

the widget to query

 

Returns

the height of the widget


gtk_widget_get_allocation ()

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

Retrieves the widget’s allocation.

Note, when implementing a GtkContainer: a widget’s allocation will be its “adjusted” allocation, that is, the widget’s parent container typically calls gtk_widget_size_allocate() with an allocation, and that allocation is then adjusted (to handle margin and alignment for example) before assignment to the widget. gtk_widget_get_allocation() returns the adjusted allocation that was actually assigned to the widget. The adjusted allocation is guaranteed to be completely contained within the gtk_widget_size_allocate() allocation, however. So a GtkContainer is guaranteed that its children stay inside the assigned bounds, but not that they have exactly the bounds the container assigned.

Parameters

widget

a GtkWidget

 

allocation

a pointer to a GtkAllocation to copy to.

[out]

gtk_widget_get_allocated_baseline ()

int
gtk_widget_get_allocated_baseline (GtkWidget *widget);

Returns the baseline that has currently been allocated to widget . This function is intended to be used when implementing handlers for the GtkWidgetClass.snapshot() function, and when allocating child widgets in “size_allocate”.

Parameters

widget

the widget to query

 

Returns

the baseline of the widget , or -1 if none


gtk_widget_get_width ()

int
gtk_widget_get_width (GtkWidget *widget);

Returns the content width of the widget, as passed to its size-allocate implementation. This is the size you should be using in GtkWidgetClass.snapshot(). For pointer events, see gtk_widget_contains().

Parameters

widget

a GtkWidget

 

Returns

The width of widget


gtk_widget_get_height ()

int
gtk_widget_get_height (GtkWidget *widget);

Returns the content height of the widget, as passed to its size-allocate implementation. This is the size you should be using in GtkWidgetClass.snapshot(). For pointer events, see gtk_widget_contains().

Parameters

widget

a GtkWidget

 

Returns

The height of widget


gtk_widget_get_size ()

int
gtk_widget_get_size (GtkWidget *widget,
                     GtkOrientation orientation);

Returns the content width or height of the widget, depending on orientation . This is equivalent to calling gtk_widget_get_width() for GTK_ORIENTATION_HORIZONTAL or gtk_widget_get_height() for GTK_ORIENTATION_VERTICAL, but can be used when writing orientation-independent code, such as when implementing GtkOrientable widgets.

Parameters

widget

a GtkWidget

 

orientation

the orientation to query

 

Returns

The size of widget in orientation .


gtk_widget_compute_bounds ()

gboolean
gtk_widget_compute_bounds (GtkWidget *widget,
                           GtkWidget *target,
                           graphene_rect_t *out_bounds);

Computes the bounds for widget in the coordinate space of target . FIXME: Explain what "bounds" are.

If the operation is successful, TRUE is returned. If widget has no bounds or the bounds cannot be expressed in target 's coordinate space (for example if both widgets are in different windows), FALSE is returned and bounds is set to the zero rectangle.

It is valid for widget and target to be the same widget.

Parameters

widget

the GtkWidget to query

 

target

the GtkWidget

 

out_bounds

the rectangle taking the bounds.

[out caller-allocates]

Returns

TRUE if the bounds could be computed


gtk_widget_compute_transform ()

gboolean
gtk_widget_compute_transform (GtkWidget *widget,
                              GtkWidget *target,
                              graphene_matrix_t *out_transform);

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

Parameters

widget

a GtkWidget

 

target

the target widget that the matrix will transform to

 

out_transform

location to store the final transformation.

[out caller-allocates]

Returns

TRUE if the transform could be computed, FALSE otherwise. The transform can not be computed in certain cases, for example when widget and target do not share a common ancestor. In that case out_transform gets set to the identity matrix.


gtk_widget_compute_point ()

gboolean
gtk_widget_compute_point (GtkWidget *widget,
                          GtkWidget *target,
                          const graphene_point_t *point,
                          graphene_point_t *out_point);

Translates the given point in widget 's coordinates to coordinates relative to target ’s coordinate system. In order to perform this operation, both widgets must share a common root.

Parameters

widget

the GtkWidget to query

 

target

the GtkWidget to transform into

 

point

a point in widget 's coordinate system

 

out_point

Set to the corresponding coordinates in target 's coordinate system.

[out caller-allocates]

Returns

TRUE if the point could be determined, FALSE on failure. In this case, 0 is stored in out_point .


gtk_widget_contains ()

gboolean
gtk_widget_contains (GtkWidget *widget,
                     gdouble x,
                     gdouble y);

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

The coordinates for (x , y ) must be in widget coordinates, so (0, 0) is assumed to be the top left of widget 's content area.

Parameters

widget

the widget to query

 

x

X coordinate to test, relative to widget 's origin

 

y

Y coordinate to test, relative to widget 's origin

 

Returns

TRUE if widget contains (x , y ).


gtk_widget_pick ()

GtkWidget *
gtk_widget_pick (GtkWidget *widget,
                 gdouble x,
                 gdouble y,
                 GtkPickFlags flags);

Finds the descendant of widget (including widget itself) closest to the screen at the point (x , y ). The point must be given in widget coordinates, so (0, 0) is assumed to be the top left of widget 's content area.

Usually widgets will return NULL if the given coordinate is not contained in widget checked via gtk_widget_contains(). Otherwise they will recursively try to find a child that does not return NULL. Widgets are however free to customize their picking algorithm.

This function is used on the toplevel to determine the widget below the mouse cursor for purposes of hover hilighting and delivering events.

Parameters

widget

the widget to query

 

x

X coordinate to test, relative to widget 's origin

 

y

Y coordinate to test, relative to widget 's origin

 

flags

Flags to influence what is picked

 

Returns

The widget descendant at the given coordinate or NULL if none.

[nullable][transfer none]


gtk_widget_get_can_focus ()

gboolean
gtk_widget_get_can_focus (GtkWidget *widget);

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

See gtk_widget_set_focusable().

Parameters

widget

a GtkWidget

 

Returns

TRUE if the input focus can enter widget , FALSE otherwise


gtk_widget_set_can_focus ()

void
gtk_widget_set_can_focus (GtkWidget *widget,
                          gboolean can_focus);

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

Applications should set can_focus to FALSE to mark a widget as for pointer/touch use only.

Note that having can_focus be TRUE is only one of the necessary conditions for being focusable. A widget must also be sensitive and focusable and not have an ancestor that is marked as not can-focus in order to receive input focus.

See gtk_widget_grab_focus() for actually setting the input focus on a widget.

Parameters

widget

a GtkWidget

 

can_focus

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

 

gtk_widget_get_focusable ()

gboolean
gtk_widget_get_focusable (GtkWidget *widget);

Determines whether widget can own the input focus. See gtk_widget_set_focusable().

Parameters

widget

a GtkWidget

 

Returns

TRUE if widget can own the input focus, FALSE otherwise


gtk_widget_set_focusable ()

void
gtk_widget_set_focusable (GtkWidget *widget,
                          gboolean focusable);

Specifies whether widget can own the input focus.

Widget implementations should set focusable to TRUE in their init() function if they want to receive keyboard input.

Note that having focusable be TRUE is only one of the necessary conditions for being focusable. A widget must also be sensitive and can-focus and not have an ancestor that is marked as not can-focus in order to receive input focus.

See gtk_widget_grab_focus() for actually setting the input focus on a widget.

Parameters

widget

a GtkWidget

 

focusable

whether or not widget can own the input focus

 

gtk_widget_get_focus_on_click ()

gboolean
gtk_widget_get_focus_on_click (GtkWidget *widget);

Returns whether the widget should grab focus when it is clicked with the mouse. See gtk_widget_set_focus_on_click().

Parameters

widget

a GtkWidget

 

Returns

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


gtk_widget_set_focus_on_click ()

void
gtk_widget_set_focus_on_click (GtkWidget *widget,
                               gboolean focus_on_click);

Sets whether the widget should grab focus when it is clicked with the mouse. Making mouse clicks not grab focus is useful in places like toolbars where you don’t want the keyboard focus removed from the main area of the application.

Parameters

widget

a GtkWidget

 

focus_on_click

whether the widget should grab focus when clicked with the mouse

 

gtk_widget_set_focus_child ()

void
gtk_widget_set_focus_child (GtkWidget *widget,
                            GtkWidget *child);

Set child as the current focus child of widget . The previous focus child will be unset.

This function is only suitable for widget implementations. If you want a certain widget to get the input focus, call gtk_widget_grab_focus() on it.

Parameters

widget

a GtkWidget

 

child

a direct child widget of widget or NULL to unset the focus child of widget .

[nullable]

gtk_widget_get_can_target ()

gboolean
gtk_widget_get_can_target (GtkWidget *widget);

Queries whether widget can be the target of pointer events.

Parameters

widget

a GtkWidget

 

Returns

TRUE if widget can receive pointer events


gtk_widget_set_can_target ()

void
gtk_widget_set_can_target (GtkWidget *widget,
                           gboolean can_target);

Sets whether widget can be the target of pointer events.

Parameters

widget

a GtkWidget

 

can_target

whether this widget should be able to receive pointer events

 

gtk_widget_get_sensitive ()

gboolean
gtk_widget_get_sensitive (GtkWidget *widget);

Returns the widget’s sensitivity (in the sense of returning the value that has been set using gtk_widget_set_sensitive()).

The effective sensitivity of a widget is however determined by both its own and its parent widget’s sensitivity. See gtk_widget_is_sensitive().

Parameters

widget

a GtkWidget

 

Returns

TRUE if the widget is sensitive


gtk_widget_is_sensitive ()

gboolean
gtk_widget_is_sensitive (GtkWidget *widget);

Returns the widget’s effective sensitivity, which means it is sensitive itself and also its parent widget is sensitive

Parameters

widget

a GtkWidget

 

Returns

TRUE if the widget is effectively sensitive


gtk_widget_get_visible ()

gboolean
gtk_widget_get_visible (GtkWidget *widget);

Determines whether the widget is visible. If you want to take into account whether the widget’s parent is also marked as visible, use gtk_widget_is_visible() instead.

This function does not check if the widget is obscured in any way.

See gtk_widget_set_visible().

Parameters

widget

a GtkWidget

 

Returns

TRUE if the widget is visible


gtk_widget_is_visible ()

gboolean
gtk_widget_is_visible (GtkWidget *widget);

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

This function does not check if the widget is obscured in any way.

See also gtk_widget_get_visible() and gtk_widget_set_visible()

Parameters

widget

a GtkWidget

 

Returns

TRUE if the widget and all its parents are visible


gtk_widget_set_visible ()

void
gtk_widget_set_visible (GtkWidget *widget,
                        gboolean visible);

Sets the visibility state of widget . Note that setting this to TRUE doesn’t mean the widget is actually viewable, see gtk_widget_get_visible().

This function simply calls gtk_widget_show() or gtk_widget_hide() but is nicer to use when the visibility of the widget depends on some condition.

Parameters

widget

a GtkWidget

 

visible

whether the widget should be shown or not

 

gtk_widget_set_state_flags ()

void
gtk_widget_set_state_flags (GtkWidget *widget,
                            GtkStateFlags flags,
                            gboolean clear);

This function is for use in widget implementations. Turns on flag values in the current widget state (insensitive, prelighted, etc.).

This function accepts the values GTK_STATE_FLAG_DIR_LTR and GTK_STATE_FLAG_DIR_RTL but ignores them. If you want to set the widget's direction, use gtk_widget_set_direction().

It is worth mentioning that any other state than GTK_STATE_FLAG_INSENSITIVE, will be propagated down to all non-internal children if widget is a GtkContainer, while GTK_STATE_FLAG_INSENSITIVE itself will be propagated down to all GtkContainer children by different means than turning on the state flag down the hierarchy, both gtk_widget_get_state_flags() and gtk_widget_is_sensitive() will make use of these.

Parameters

widget

a GtkWidget

 

flags

State flags to turn on

 

clear

Whether to clear state before turning on flags

 

gtk_widget_unset_state_flags ()

void
gtk_widget_unset_state_flags (GtkWidget *widget,
                              GtkStateFlags flags);

This function is for use in widget implementations. Turns off flag values for the current widget state (insensitive, prelighted, etc.). See gtk_widget_set_state_flags().

Parameters

widget

a GtkWidget

 

flags

State flags to turn off

 

gtk_widget_get_state_flags ()

GtkStateFlags
gtk_widget_get_state_flags (GtkWidget *widget);

Returns the widget state as a flag set. It is worth mentioning that the effective GTK_STATE_FLAG_INSENSITIVE state will be returned, that is, also based on parent insensitivity, even if widget itself is sensitive.

Also note that if you are looking for a way to obtain the GtkStateFlags to pass to a GtkStyleContext method, you should look at gtk_style_context_get_state().

Parameters

widget

a GtkWidget

 

Returns

The state flags for widget


gtk_widget_has_default ()

gboolean
gtk_widget_has_default (GtkWidget *widget);

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

Parameters

widget

a GtkWidget

 

Returns

TRUE if widget is the current default widget within its toplevel, FALSE otherwise


gtk_widget_has_focus ()

gboolean
gtk_widget_has_focus (GtkWidget *widget);

Determines if the widget has the global input focus. See gtk_widget_is_focus() for the difference between having the global input focus, and only having the focus within a toplevel.

Parameters

widget

a GtkWidget

 

Returns

TRUE if the widget has the global input focus.


gtk_widget_has_visible_focus ()

gboolean
gtk_widget_has_visible_focus (GtkWidget *widget);

Determines if the widget should show a visible indication that it has the global input focus. This is a convenience function that takes into account whether focus indication should currently be shown in the toplevel window of widget . See gtk_window_get_focus_visible() for more information about focus indication.

To find out if the widget has the global input focus, use gtk_widget_has_focus().

Parameters

widget

a GtkWidget

 

Returns

TRUE if the widget should display a “focus rectangle”


gtk_widget_is_drawable ()

gboolean
gtk_widget_is_drawable (GtkWidget *widget);

Determines whether widget can be drawn to. A widget can be drawn if it is mapped and visible.

Parameters

widget

a GtkWidget

 

Returns

TRUE if widget is drawable, FALSE otherwise


gtk_widget_set_receives_default ()

void
gtk_widget_set_receives_default (GtkWidget *widget,
                                 gboolean 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.

Parameters

widget

a GtkWidget

 

receives_default

whether or not widget can be a default widget.

 

gtk_widget_get_receives_default ()

gboolean
gtk_widget_get_receives_default (GtkWidget *widget);

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.

See gtk_widget_set_receives_default().

Parameters

widget

a GtkWidget

 

Returns

TRUE if widget acts as the default widget when focused, FALSE otherwise


gtk_widget_set_support_multidevice ()

void
gtk_widget_set_support_multidevice (GtkWidget *widget,
                                    gboolean support_multidevice);

Enables or disables multiple pointer awareness. If this setting is TRUE, widget will start receiving multiple, per device enter/leave events. Note that if custom GdkSurfaces are created in “realize”, gdk_surface_set_support_multidevice() will have to be called manually on them.

Parameters

widget

a GtkWidget

 

support_multidevice

TRUE to support input from multiple devices.

 

gtk_widget_get_support_multidevice ()

gboolean
gtk_widget_get_support_multidevice (GtkWidget *widget);

Returns TRUE if widget is multiple pointer aware. See gtk_widget_set_support_multidevice() for more information.

Parameters

widget

a GtkWidget

 

Returns

TRUE if widget is multidevice aware.


gtk_widget_get_realized ()

gboolean
gtk_widget_get_realized (GtkWidget *widget);

Determines whether widget is realized.

Parameters

widget

a GtkWidget

 

Returns

TRUE if widget is realized, FALSE otherwise


gtk_widget_get_mapped ()

gboolean
gtk_widget_get_mapped (GtkWidget *widget);

Whether the widget is mapped.

Parameters

widget

a GtkWidget

 

Returns

TRUE if the widget is mapped, FALSE otherwise.


gtk_widget_device_is_shadowed ()

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

Returns TRUE if device has been shadowed by a GTK+ device grab on another widget, so it would stop sending events to widget . This may be used in the “grab-notify” signal to check for specific devices. See gtk_device_grab_add().

Parameters

widget

a GtkWidget

 

device

a GdkDevice

 

Returns

TRUE if there is an ongoing grab on device by another GtkWidget than widget .


gtk_widget_get_opacity ()

double
gtk_widget_get_opacity (GtkWidget *widget);

Fetches the requested opacity for this widget. See gtk_widget_set_opacity().

Parameters

widget

a GtkWidget

 

Returns

the requested opacity for this widget.


gtk_widget_set_opacity ()

void
gtk_widget_set_opacity (GtkWidget *widget,
                        double opacity);

Request the widget to be rendered partially transparent, with opacity 0 being fully transparent and 1 fully opaque. (Opacity values are clamped to the [0,1] range.). This works on both toplevel widget, and child widgets, although there are some limitations:

For toplevel widgets this depends on the capabilities of the windowing system. On X11 this has any effect only on X displays with a compositing manager running. See gdk_display_is_composited(). On Windows it should work always, although setting a window’s opacity after the window has been shown causes it to flicker once on Windows.

For child widgets it doesn’t work if any affected widget has a native window.

Parameters

widget

a GtkWidget

 

opacity

desired opacity, between 0 and 1

 

gtk_widget_get_overflow ()

GtkOverflow
gtk_widget_get_overflow (GtkWidget *widget);

Returns the value set via gtk_widget_set_overflow().

Parameters

widget

a GtkWidget

 

Returns

The widget's overflow.


gtk_widget_set_overflow ()

void
gtk_widget_set_overflow (GtkWidget *widget,
                         GtkOverflow overflow);

Sets how widget treats content that is drawn outside the widget's content area. See the definition of GtkOverflow for details.

This setting is provided for widget implementations and should not be used by application code.

The default value is GTK_OVERFLOW_VISIBLE.

Parameters

widget

a GtkWidget

 

overflow

desired overflow

 

gtk_widget_measure ()

void
gtk_widget_measure (GtkWidget *widget,
                    GtkOrientation orientation,
                    int for_size,
                    int *minimum,
                    int *natural,
                    int *minimum_baseline,
                    int *natural_baseline);

Measures widget in the orientation orientation and for the given for_size . As an example, if orientation is GTK_ORIENTATION_HORIZONTAL and for_size is 300, this functions will compute the minimum and natural width of widget if it is allocated at a height of 300 pixels.

See GtkWidget’s geometry management section for a more details on implementing GtkWidgetClass.measure().

Parameters

widget

A GtkWidget instance

 

orientation

the orientation to measure

 

for_size

Size for the opposite of orientation , i.e. if orientation is GTK_ORIENTATION_HORIZONTAL, this is the height the widget should be measured with. The GTK_ORIENTATION_VERTICAL case is analogous. This way, both height-for-width and width-for-height requests can be implemented. If no size is known, -1 can be passed.

 

minimum

location to store the minimum size, or NULL.

[out][optional]

natural

location to store the natural size, or NULL.

[out][optional]

minimum_baseline

location to store the baseline position for the minimum size, or NULL.

[out][optional]

natural_baseline

location to store the baseline position for the natural size, or NULL.

[out][optional]

gtk_widget_snapshot_child ()

void
gtk_widget_snapshot_child (GtkWidget *widget,
                           GtkWidget *child,
                           GtkSnapshot *snapshot);

When a widget receives a call to the snapshot function, it must send synthetic GtkWidgetClass.snapshot() calls to all children. This function provides a convenient way of doing this. A widget, when it receives a call to its GtkWidgetClass.snapshot() function, calls gtk_widget_snapshot_child() once for each child, passing in the snapshot the widget received.

gtk_widget_snapshot_child() takes care of translating the origin of snapshot , and deciding whether the child needs to be snapshot.

This function does nothing for children that implement GtkNative.

Parameters

widget

a GtkWidget

 

child

a child of widget

 

snapshot

GtkSnapshot as passed to the widget. In particular, no calls to gtk_snapshot_translate() or other transform calls should have been made.

 

gtk_widget_get_next_sibling ()

GtkWidget *
gtk_widget_get_next_sibling (GtkWidget *widget);

Returns the widgets next sibling.

Parameters

widget

a GtkWidget

 

Returns

The widget's next sibling.

[transfer none][nullable]


gtk_widget_get_prev_sibling ()

GtkWidget *
gtk_widget_get_prev_sibling (GtkWidget *widget);

Returns the widgets previous sibling.

Parameters

widget

a GtkWidget

 

Returns

The widget's previous sibling.

[transfer none][nullable]


gtk_widget_get_first_child ()

GtkWidget *
gtk_widget_get_first_child (GtkWidget *widget);

Returns the widgets first child.

Parameters

widget

a GtkWidget

 

Returns

The widget's first child.

[transfer none][nullable]


gtk_widget_get_last_child ()

GtkWidget *
gtk_widget_get_last_child (GtkWidget *widget);

Returns the widgets last child.

Parameters

widget

a GtkWidget

 

Returns

The widget's last child.

[transfer none][nullable]


gtk_widget_insert_before ()

void
gtk_widget_insert_before (GtkWidget *widget,
                          GtkWidget *parent,
                          GtkWidget *next_sibling);

Inserts widget into the child widget list of parent . It will be placed before next_sibling , or at the end if next_sibling is NULL.

After calling this function, gtk_widget_get_next_sibling(widget) will return next_sibling .

If parent is already set as the parent widget of widget , this function can also be used to reorder widget in the child widget list of parent .

Parameters

widget

a GtkWidget

 

parent

the parent GtkWidget to insert widget into

 

next_sibling

the new next sibling of widget or NULL.

[nullable]

gtk_widget_insert_after ()

void
gtk_widget_insert_after (GtkWidget *widget,
                         GtkWidget *parent,
                         GtkWidget *previous_sibling);

Inserts widget into the child widget list of parent . It will be placed after previous_sibling , or at the beginning if previous_sibling is NULL.

After calling this function, gtk_widget_get_prev_sibling(widget) will return previous_sibling .

If parent is already set as the parent widget of widget , this function can also be used to reorder widget in the child widget list of parent .

Parameters

widget

a GtkWidget

 

parent

the parent GtkWidget to insert widget into

 

previous_sibling

the new previous sibling of widget or NULL.

[nullable]

gtk_widget_set_layout_manager ()

void
gtk_widget_set_layout_manager (GtkWidget *widget,
                               GtkLayoutManager *layout_manager);

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

Parameters

widget

a GtkWidget

 

layout_manager

a GtkLayoutManager.

[nullable][transfer full]

gtk_widget_get_layout_manager ()

GtkLayoutManager *
gtk_widget_get_layout_manager (GtkWidget *widget);

Retrieves the layout manager set using gtk_widget_set_layout_manager().

Parameters

widget

a GtkWidget

 

Returns

a GtkLayoutManager.

[transfer none][nullable]


gtk_widget_should_layout ()

gboolean
gtk_widget_should_layout (GtkWidget *widget);

Returns whether widget should contribute to the measuring and allocation of its parent. This is FALSE for invisible children, but also for children that have their own surface.

Parameters

widget

a widget

 

Returns

TRUE if child should be included in measuring and allocating


gtk_widget_get_css_name ()

const char *
gtk_widget_get_css_name (GtkWidget *self);

Returns the CSS name that is used for self .

Parameters

self

a GtkWidget

 

Returns

the CSS name.

[transfer none]


gtk_widget_add_css_class ()

void
gtk_widget_add_css_class (GtkWidget *widget,
                          const char *css_class);

Adds css_class to widget . After calling this function, widget 's style will match for css_class , after the CSS matching rules.

Parameters

widget

a GtkWidget

 

css_class

The style class to add to widget , without the leading '.' used for notation of style classes

 

gtk_widget_remove_css_class ()

void
gtk_widget_remove_css_class (GtkWidget *widget,
                             const char *css_class);

Removes css_class from widget . After this, the style of widget will stop matching for css_class .

Parameters

widget

a GtkWidget

 

css_class

The style class to remove from widget , without the leading '.' used for notation of style classes

 

gtk_widget_has_css_class ()

gboolean
gtk_widget_has_css_class (GtkWidget *widget,
                          const char *css_class);

Returns whether css_class is currently applied to widget .

Parameters

widget

a GtkWidget

 

css_class

A CSS style class, without the leading '.' used for notation of style classes

 

Returns

TRUE if css_class is currently applied to widget , FALSE otherwise.


gtk_widget_get_css_classes ()

char **
gtk_widget_get_css_classes (GtkWidget *widget);

Returns the list of css classes applied to widget .

Parameters

widget

a GtkWidget

 

Returns

a NULL-terminated list of css classes currently applied to widget . The returned list can be freed using g_strfreev().

[transfer full]


gtk_widget_set_css_classes ()

void
gtk_widget_set_css_classes (GtkWidget *widget,
                            const char **classes);

Will clear all css classes applied to widget and replace them with classes .

Parameters

widget

a GtkWidget

 

classes

NULL-terminated list of css classes to apply to widget .

[transfer none][array zero-terminated=1]

gtk_widget_get_style_context ()

GtkStyleContext *
gtk_widget_get_style_context (GtkWidget *widget);

Returns the style context associated to widget . The returned object is guaranteed to be the same for the lifetime of widget .

Parameters

widget

a GtkWidget

 

Returns

a GtkStyleContext. This memory is owned by widget and must not be freed.

[transfer none]


gtk_widget_class_get_css_name ()

const char *
gtk_widget_class_get_css_name (GtkWidgetClass *widget_class);

Gets the name used by this class for matching in CSS code. See gtk_widget_class_set_css_name() for details.

Parameters

widget_class

class to set the name on

 

Returns

the CSS name of the given class


gtk_widget_class_set_css_name ()

void
gtk_widget_class_set_css_name (GtkWidgetClass *widget_class,
                               const char *name);

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

If this function is not called for a given class, the name of the parent class is used.

Parameters

widget_class

class to set the name on

 

name

name to use

 

gtk_requisition_new ()

GtkRequisition *
gtk_requisition_new (void);

Allocates a new GtkRequisition and initializes its elements to zero.

Returns

a new empty GtkRequisition. The newly allocated GtkRequisition should be freed with gtk_requisition_free().


gtk_requisition_copy ()

GtkRequisition *
gtk_requisition_copy (const GtkRequisition *requisition);

Copies a GtkRequisition.

Parameters

requisition

a GtkRequisition

 

Returns

a copy of requisition


gtk_requisition_free ()

void
gtk_requisition_free (GtkRequisition *requisition);

Frees a GtkRequisition.

Parameters

requisition

a GtkRequisition

 

gtk_widget_get_request_mode ()

GtkSizeRequestMode
gtk_widget_get_request_mode (GtkWidget *widget);

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

GtkBin widgets generally propagate the preference of their child, container widgets need to request something either in context of their children or in context of their allocation capabilities.

Parameters

widget

a GtkWidget instance

 

Returns

The GtkSizeRequestMode preferred by widget .


gtk_widget_get_preferred_size ()

void
gtk_widget_get_preferred_size (GtkWidget *widget,
                               GtkRequisition *minimum_size,
                               GtkRequisition *natural_size);

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

This is used to retrieve a suitable size by container widgets which do not impose any restrictions on the child placement. It can be used to deduce toplevel window and menu sizes as well as child widgets in free-form containers such as GtkLayout.

Handle with care. Note that the natural height of a height-for-width widget will generally be a smaller size than the minimum height, since the required height for the natural width is generally smaller than the required height for the minimum width.

Use gtk_widget_measure() if you want to support baseline alignment.

Parameters

widget

a GtkWidget instance

 

minimum_size

location for storing the minimum size, or NULL.

[out][allow-none]

natural_size

location for storing the natural size, or NULL.

[out][allow-none]

gtk_distribute_natural_allocation ()

gint
gtk_distribute_natural_allocation (gint extra_space,
                                   guint n_requested_sizes,
                                   GtkRequestedSize *sizes);

Distributes extra_space to child sizes by bringing smaller children up to natural size first.

The remaining space will be added to the minimum_size member of the GtkRequestedSize struct. If all sizes reach their natural size then the remaining space is returned.

Parameters

extra_space

Extra space to redistribute among children after subtracting minimum sizes and any child padding from the overall allocation

 

n_requested_sizes

Number of requests to fit into the allocation

 

sizes

An array of structs with a client pointer and a minimum/natural size in the orientation of the allocation.

 

Returns

The remainder of extra_space after redistributing space to sizes .


gtk_widget_get_halign ()

GtkAlign
gtk_widget_get_halign (GtkWidget *widget);

Gets the value of the “halign” property.

For backwards compatibility reasons this method will never return GTK_ALIGN_BASELINE, but instead it will convert it to GTK_ALIGN_FILL. Baselines are not supported for horizontal alignment.

Parameters

widget

a GtkWidget

 

Returns

the horizontal alignment of widget


gtk_widget_set_halign ()

void
gtk_widget_set_halign (GtkWidget *widget,
                       GtkAlign align);

Sets the horizontal alignment of widget . See the “halign” property.

Parameters

widget

a GtkWidget

 

align

the horizontal alignment

 

gtk_widget_get_valign ()

GtkAlign
gtk_widget_get_valign (GtkWidget *widget);

Gets the value of the “valign” property.

Parameters

widget

a GtkWidget

 

Returns

the vertical alignment of widget


gtk_widget_set_valign ()

void
gtk_widget_set_valign (GtkWidget *widget,
                       GtkAlign align);

Sets the vertical alignment of widget . See the “valign” property.

Parameters

widget

a GtkWidget

 

align

the vertical alignment

 

gtk_widget_get_margin_start ()

gint
gtk_widget_get_margin_start (GtkWidget *widget);

Gets the value of the “margin-start” property.

Parameters

widget

a GtkWidget

 

Returns

The start margin of widget


gtk_widget_set_margin_start ()

void
gtk_widget_set_margin_start (GtkWidget *widget,
                             gint margin);

Sets the start margin of widget . See the “margin-start” property.

Parameters

widget

a GtkWidget

 

margin

the start margin

 

gtk_widget_get_margin_end ()

gint
gtk_widget_get_margin_end (GtkWidget *widget);

Gets the value of the “margin-end” property.

Parameters

widget

a GtkWidget

 

Returns

The end margin of widget


gtk_widget_set_margin_end ()

void
gtk_widget_set_margin_end (GtkWidget *widget,
                           gint margin);

Sets the end margin of widget . See the “margin-end” property.

Parameters

widget

a GtkWidget

 

margin

the end margin

 

gtk_widget_get_margin_top ()

gint
gtk_widget_get_margin_top (GtkWidget *widget);

Gets the value of the “margin-top” property.

Parameters

widget

a GtkWidget

 

Returns

The top margin of widget


gtk_widget_set_margin_top ()

void
gtk_widget_set_margin_top (GtkWidget *widget,
                           gint margin);

Sets the top margin of widget . See the “margin-top” property.

Parameters

widget

a GtkWidget

 

margin

the top margin

 

gtk_widget_get_margin_bottom ()

gint
gtk_widget_get_margin_bottom (GtkWidget *widget);

Gets the value of the “margin-bottom” property.

Parameters

widget

a GtkWidget

 

Returns

The bottom margin of widget


gtk_widget_set_margin_bottom ()

void
gtk_widget_set_margin_bottom (GtkWidget *widget,
                              gint margin);

Sets the bottom margin of widget . See the “margin-bottom” property.

Parameters

widget

a GtkWidget

 

margin

the bottom margin

 

gtk_widget_get_hexpand ()

gboolean
gtk_widget_get_hexpand (GtkWidget *widget);

Gets whether the widget would like any available extra horizontal space. When a user resizes a GtkWindow, widgets with expand=TRUE generally receive the extra space. For example, a list or scrollable area or document in your window would often be set to expand.

Containers should use gtk_widget_compute_expand() rather than this function, to see whether a widget, or any of its children, has the expand flag set. If any child of a widget wants to expand, the parent may ask to expand also.

This function only looks at the widget’s own hexpand flag, rather than computing whether the entire widget tree rooted at this widget wants to expand.

Parameters

widget

the widget

 

Returns

whether hexpand flag is set


gtk_widget_set_hexpand ()

void
gtk_widget_set_hexpand (GtkWidget *widget,
                        gboolean expand);

Sets whether the widget would like any available extra horizontal space. When a user resizes a GtkWindow, widgets with expand=TRUE generally receive the extra space. For example, a list or scrollable area or document in your window would often be set to expand.

Call this function to set the expand flag if you would like your widget to become larger horizontally when the window has extra room.

By default, widgets automatically expand if any of their children want to expand. (To see if a widget will automatically expand given its current children and state, call gtk_widget_compute_expand(). A container can decide how the expandability of children affects the expansion of the container by overriding the compute_expand virtual method on GtkWidget.).

Setting hexpand explicitly with this function will override the automatic expand behavior.

This function forces the widget to expand or not to expand, regardless of children. The override occurs because gtk_widget_set_hexpand() sets the hexpand-set property (see gtk_widget_set_hexpand_set()) which causes the widget’s hexpand value to be used, rather than looking at children and widget state.

Parameters

widget

the widget

 

expand

whether to expand

 

gtk_widget_get_hexpand_set ()

gboolean
gtk_widget_get_hexpand_set (GtkWidget *widget);

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

If hexpand is set, then it overrides any computed expand value based on child widgets. If hexpand is not set, then the expand value depends on whether any children of the widget would like to expand.

There are few reasons to use this function, but it’s here for completeness and consistency.

Parameters

widget

the widget

 

Returns

whether hexpand has been explicitly set


gtk_widget_set_hexpand_set ()

void
gtk_widget_set_hexpand_set (GtkWidget *widget,
                            gboolean set);

Sets whether the hexpand flag (see gtk_widget_get_hexpand()) will be used.

The hexpand-set property will be set automatically when you call gtk_widget_set_hexpand() to set hexpand, so the most likely reason to use this function would be to unset an explicit expand flag.

If hexpand is set, then it overrides any computed expand value based on child widgets. If hexpand is not set, then the expand value depends on whether any children of the widget would like to expand.

There are few reasons to use this function, but it’s here for completeness and consistency.

Parameters

widget

the widget

 

set

value for hexpand-set property

 

gtk_widget_get_vexpand ()

gboolean
gtk_widget_get_vexpand (GtkWidget *widget);

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

See gtk_widget_get_hexpand() for more detail.

Parameters

widget

the widget

 

Returns

whether vexpand flag is set


gtk_widget_set_vexpand ()

void
gtk_widget_set_vexpand (GtkWidget *widget,
                        gboolean expand);

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

See gtk_widget_set_hexpand() for more detail.

Parameters

widget

the widget

 

expand

whether to expand

 

gtk_widget_get_vexpand_set ()

gboolean
gtk_widget_get_vexpand_set (GtkWidget *widget);

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

See gtk_widget_get_hexpand_set() for more detail.

Parameters

widget

the widget

 

Returns

whether vexpand has been explicitly set


gtk_widget_set_vexpand_set ()

void
gtk_widget_set_vexpand_set (GtkWidget *widget,
                            gboolean set);

Sets whether the vexpand flag (see gtk_widget_get_vexpand()) will be used.

See gtk_widget_set_hexpand_set() for more detail.

Parameters

widget

the widget

 

set

value for vexpand-set property

 

gtk_widget_compute_expand ()

gboolean
gtk_widget_compute_expand (GtkWidget *widget,
                           GtkOrientation orientation);

Computes whether a container should give this widget extra space when possible. Containers should check this, rather than looking at gtk_widget_get_hexpand() or gtk_widget_get_vexpand().

This function already checks whether the widget is visible, so visibility does not need to be checked separately. Non-visible widgets are not expanded.

The computed expand value uses either the expand setting explicitly set on the widget itself, or, if none has been explicitly set, the widget may expand if some of its children do.

Parameters

widget

the widget

 

orientation

expand direction

 

Returns

whether widget tree rooted here should be expanded


gtk_widget_init_template ()

void
gtk_widget_init_template (GtkWidget *widget);

Creates and initializes child widgets defined in templates. This function must be called in the instance initializer for any class which assigned itself a template using gtk_widget_class_set_template()

It is important to call this function in the instance initializer of a GtkWidget subclass and not in GObject.constructed() or GObject.constructor() for two reasons.

One reason is that generally derived widgets will assume that parent class composite widgets have been created in their instance initializers.

Another reason is that when calling g_object_new() on a widget with composite templates, it’s important to build the composite widgets before the construct properties are set. Properties passed to g_object_new() should take precedence over properties set in the private template XML.

Parameters

widget

a GtkWidget

 

gtk_widget_class_set_template ()

void
gtk_widget_class_set_template (GtkWidgetClass *widget_class,
                               GBytes *template_bytes);

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

For convenience, gtk_widget_class_set_template_from_resource() is also provided.

Note that any class that installs templates must call gtk_widget_init_template() in the widget’s instance initializer.

Parameters

widget_class

A GtkWidgetClass

 

template_bytes

A GBytes holding the GtkBuilder XML

 

gtk_widget_class_set_template_from_resource ()

void
gtk_widget_class_set_template_from_resource
                               (GtkWidgetClass *widget_class,
                                const gchar *resource_name);

A convenience function to call gtk_widget_class_set_template().

Note that any class that installs templates must call gtk_widget_init_template() in the widget’s instance initializer.

Parameters

widget_class

A GtkWidgetClass

 

resource_name

The name of the resource to load the template from

 

gtk_widget_get_template_child ()

GObject *
gtk_widget_get_template_child (GtkWidget *widget,
                               GType widget_type,
                               const gchar *name);

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

This will only report children which were previously declared with gtk_widget_class_bind_template_child_full() or one of its variants.

This function is only meant to be called for code which is private to the widget_type which declared the child and is meant for language bindings which cannot easily make use of the GObject structure offsets.

Parameters

widget

A GtkWidget

 

widget_type

The GType to get a template child for

 

name

The “id” of the child defined in the template XML

 

Returns

The object built in the template XML with the id name .

[transfer none]


gtk_widget_class_bind_template_child()

#define             gtk_widget_class_bind_template_child(widget_class, TypeName, member_name)

Binds a child widget defined in a template to the widget_class .

This macro is a convenience wrapper around the gtk_widget_class_bind_template_child_full() function.

This macro will use the offset of the member_name inside the TypeName instance structure.

Parameters

widget_class

a GtkWidgetClass

 

TypeName

the type name of this widget

 

member_name

name of the instance member in the instance struct for data_type

 

gtk_widget_class_bind_template_child_internal()

#define             gtk_widget_class_bind_template_child_internal(widget_class, TypeName, member_name)

Binds a child widget defined in a template to the widget_class , and also makes it available as an internal child in GtkBuilder, under the name member_name .

This macro is a convenience wrapper around the gtk_widget_class_bind_template_child_full() function.

This macro will use the offset of the member_name inside the TypeName instance structure.

Parameters

widget_class

a GtkWidgetClass

 

TypeName

the type name, in CamelCase

 

member_name

name of the instance member in the instance struct for data_type

 

gtk_widget_class_bind_template_child_private()

#define             gtk_widget_class_bind_template_child_private(widget_class, TypeName, member_name)

Binds a child widget defined in a template to the widget_class .

This macro is a convenience wrapper around the gtk_widget_class_bind_template_child_full() function.

This macro will use the offset of the member_name inside the TypeName private data structure (it uses G_PRIVATE_OFFSET(), so the private struct must be added with G_ADD_PRIVATE()).

Parameters

widget_class

a GtkWidgetClass

 

TypeName

the type name of this widget

 

member_name

name of the instance private member in the private struct for data_type

 

gtk_widget_class_bind_template_child_internal_private()

#define             gtk_widget_class_bind_template_child_internal_private(widget_class, TypeName, member_name)

Binds a child widget defined in a template to the widget_class , and also makes it available as an internal child in GtkBuilder, under the name member_name .

This macro is a convenience wrapper around the gtk_widget_class_bind_template_child_full() function.

This macro will use the offset of the member_name inside the TypeName private data structure.

Parameters

widget_class

a GtkWidgetClass

 

TypeName

the type name, in CamelCase

 

member_name

name of the instance private member on the private struct for data_type

 

gtk_widget_class_bind_template_child_full ()

void
gtk_widget_class_bind_template_child_full
                               (GtkWidgetClass *widget_class,
                                const gchar *name,
                                gboolean internal_child,
                                gssize struct_offset);

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

The struct can point either into the public instance, then you should use G_STRUCT_OFFSET(WidgetType, member) for struct_offset , or in the private struct, then you should use G_PRIVATE_OFFSET(WidgetType, member).

An explicit strong reference will be held automatically for the duration of your instance’s life cycle, it will be released automatically when GObjectClass.dispose() runs on your instance and if a struct_offset that is != 0 is specified, then the automatic location in your instance public or private data will be set to NULL. You can however access an automated child pointer the first time your classes GObjectClass.dispose() runs, or alternatively in GtkWidgetClass.destroy().

If internal_child is specified, GtkBuildableIface.get_internal_child() will be automatically implemented by the GtkWidget class so there is no need to implement it manually.

The wrapper macros gtk_widget_class_bind_template_child(), gtk_widget_class_bind_template_child_internal(), gtk_widget_class_bind_template_child_private() and gtk_widget_class_bind_template_child_internal_private() might be more convenient to use.

Note that this must be called from a composite widget classes class initializer after calling gtk_widget_class_set_template().

Parameters

widget_class

A GtkWidgetClass

 

name

The “id” of the child defined in the template XML

 

internal_child

Whether the child should be accessible as an “internal-child” when this class is used in GtkBuilder XML

 

struct_offset

The structure offset into the composite widget’s instance public or private structure where the automated child pointer should be set, or 0 to not assign the pointer.

 

gtk_widget_class_bind_template_callback()

#define             gtk_widget_class_bind_template_callback(widget_class, callback)

Binds a callback function defined in a template to the widget_class .

This macro is a convenience wrapper around the gtk_widget_class_bind_template_callback_full() function. It is not supported after gtk_widget_class_set_template_scope() has been used on widget_class .

Parameters

widget_class

a GtkWidgetClass

 

callback

the callback symbol

 

gtk_widget_class_bind_template_callback_full ()

void
gtk_widget_class_bind_template_callback_full
                               (GtkWidgetClass *widget_class,
                                const gchar *callback_name,
                                GCallback callback_symbol);

Declares a callback_symbol to handle callback_name from the template XML defined for widget_type . This function is not supported after gtk_widget_class_set_template_scope() has been used on widget_class . See gtk_builder_cscope_add_callback_symbol().

Note that this must be called from a composite widget classes class initializer after calling gtk_widget_class_set_template().

Parameters

widget_class

A GtkWidgetClass

 

callback_name

The name of the callback as expected in the template XML

 

callback_symbol

The callback symbol.

[scope async]

gtk_widget_class_set_template_scope ()

void
gtk_widget_class_set_template_scope (GtkWidgetClass *widget_class,
                                     GtkBuilderScope *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.

Note that this must be called from a composite widget classes class initializer after calling gtk_widget_class_set_template().

Parameters

widget_class

A GtkWidgetClass

 

scope

The GtkBuilderScope to use when loading the class template.

[transfer none]

gtk_widget_observe_children ()

GListModel *
gtk_widget_observe_children (GtkWidget *widget);

Returns a GListModel to track the children of widget .

Calling this function will enable extra internal bookkeeping to track children and emit signals on the returned listmodel. It may slow down operations a lot.

Applications should try hard to avoid calling this function because of the slowdowns.

Parameters

widget

a GtkWidget

 

Returns

a GListModel tracking widget 's children.

[transfer full][attributes element-type=GtkWidget]


gtk_widget_observe_controllers ()

GListModel *
gtk_widget_observe_controllers (GtkWidget *widget);

Returns a GListModel to track the GtkEventControllers of widget .

Calling this function will enable extra internal bookkeeping to track controllers and emit signals on the returned listmodel. It may slow down operations a lot.

Applications should try hard to avoid calling this function because of the slowdowns.

Parameters

widget

a GtkWidget

 

Returns

a GListModel tracking widget 's controllers.

[transfer full][attributes element-type=GtkEventController]


gtk_widget_insert_action_group ()

void
gtk_widget_insert_action_group (GtkWidget *widget,
                                const gchar *name,
                                GActionGroup *group);

Inserts group into widget . Children of widget that implement GtkActionable can then be associated with actions in group by setting their “action-name” to prefix .action-name.

Note that inheritance is defined for individual actions. I.e. even if you insert a group with prefix prefix , actions with the same prefix will still be inherited from the parent, unless the group contains an action with the same name.

If group is NULL, a previously inserted group for name is removed from widget .

Parameters

widget

a GtkWidget

 

name

the prefix for actions in group

 

group

a GActionGroup, or NULL.

[allow-none]

gtk_widget_activate_action ()

gboolean
gtk_widget_activate_action (GtkWidget *widget,
                            const char *name,
                            const char *format_string,
                            ...);

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

This is a wrapper around gtk_widget_activate_action_variant() that constructs the args variant according to format_string .

Parameters

widget

a GtkWidget

 

name

the name of the action to activate

 

format_string

GVariant format string for arguments or NULL for no arguments

 

...

arguments, as given by format string

 

Returns

TRUE if the action was activated, FALSE if the action does not exist.


gtk_widget_activate_action_variant ()

gboolean
gtk_widget_activate_action_variant (GtkWidget *widget,
                                    const char *name,
                                    GVariant *args);

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

If the action is in an action group added with gtk_widget_insert_action_group(), the name is expected to be prefixed with the prefix that was used when the group was inserted.

The arguments must match the actions expected parameter type, as returned by g_action_get_parameter_type().

[rename-to gtk_widget_activate_action]

Parameters

widget

a GtkWidget

 

name

the name of the action to activate

 

args

parameters to use, or NULL.

[allow-none]

Returns

TRUE if the action was activated, FALSE if the action does not exist.


gtk_widget_activate_default ()

void
gtk_widget_activate_default (GtkWidget *widget);

Activate the default.activate action from widget .

Parameters

widget

a GtkWidget

 

GtkWidgetActionActivateFunc ()

void
(*GtkWidgetActionActivateFunc) (GtkWidget *widget,
                                const char *action_name,
                                GVariant *parameter);

The type of the callback functions used for activating actions installed with gtk_widget_class_install_action().

The parameter must match the parameter_type of the action.

Parameters

widget

the widget to which the action belongs

 

action_name

the action name

 

parameter

parameter for activation

 

gtk_widget_class_install_action ()

void
gtk_widget_class_install_action (GtkWidgetClass *widget_class,
                                 const char *action_name,
                                 const char *parameter_type,
                                 GtkWidgetActionActivateFunc activate);

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

Actions installed by this function are stateless. The only state they have is whether they are enabled or not.

Parameters

widget_class

a GtkWidgetClass

 

action_name

a prefixed action name, such as "clipboard.paste"

 

parameter_type

the parameter type, or NULL.

[nullable]

activate

callback to use when the action is activated.

[scope call]

gtk_widget_class_install_property_action ()

void
gtk_widget_class_install_property_action
                               (GtkWidgetClass *widget_class,
                                const char *action_name,
                                const char *property_name);

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

This function will perform a few santity checks on the property selected via property_name . Namely, the property must exist, must be readable, writable and must not be construct-only. There are also restrictions on the type of the given property, it must be boolean, int, unsigned int, double or string. If any of these conditions are not met, a critical warning will be printed and no action will be added.

The state type of the action matches the property type.

If the property is boolean, the action will have no parameter and toggle the property value. Otherwise, the action will have a parameter of the same type as the property.

Parameters

widget_class

a GtkWidgetClass

 

action_name

name of the action

 

property_name

name of the property in instances of widget_class or any parent class.

 

gtk_widget_class_query_action ()

gboolean
gtk_widget_class_query_action (GtkWidgetClass *widget_class,
                               guint index_,
                               GType *owner,
                               const char **action_name,
                               const GVariantType **parameter_type,
                               const char **property_name);

Queries the actions that have been installed for a widget class using gtk_widget_class_install_action() during class initialization.

Note that this function will also return actions defined by parent classes. You can identify those by looking at owner .

Parameters

widget_class

a GtkWidgetClass

 

index_

position of the action to query

 

owner

return location for the type where the action was defined.

[out]

action_name

return location for the action name.

[out]

parameter_type

return location for the parameter type.

[out]

property_name

return location for the property name.

[out]

Returns

TRUE if the action was found, FALSE if index_ is out of range


gtk_widget_action_set_enabled ()

void
gtk_widget_action_set_enabled (GtkWidget *widget,
                               const char *action_name,
                               gboolean enabled);

Enable or disable an action installed with gtk_widget_class_install_action().

Parameters

widget

a GtkWidget

 

action_name

action name, such as "clipboard.paste"

 

enabled

whether the action is now enabled

 

Types and Values

GtkWidget

typedef struct _GtkWidget GtkWidget;

struct GtkWidgetClass

struct GtkWidgetClass {
  GInitiallyUnownedClass parent_class;

  guint activate_signal;

  /* basics */
  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);
  void (* grab_notify)         (GtkWidget        *widget,
                                gboolean          was_grabbed);

  /* size requests */
  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);

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

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

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

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

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

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

  void         (* css_changed)                 (GtkWidget            *widget,
                                                GtkCssStyleChange    *change);

  void         (* system_setting_changed)      (GtkWidget            *widget,
                                                GtkSystemSetting      settings);

  void         (* snapshot)                    (GtkWidget            *widget,
                                                GtkSnapshot          *snapshot);

  gboolean     (* contains)                    (GtkWidget *widget,
                                                gdouble    x,
                                                gdouble    y);
};

Members

guint activate_signal;

The signal to emit when a widget of this class is activated, gtk_widget_activate() handles the emission. Implementation of this signal is optional.

 

show ()

Signal emitted when widget is shown

 

hide ()

Signal emitted when widget is hidden.

 

map ()

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

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

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

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

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

 

unroot ()

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

 

size_allocate ()

Signal emitted to get the widget allocation.

 

state_flags_changed ()

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

 

direction_changed ()

Signal emitted when the text direction of a widget changes.

 

grab_notify ()

Signal emitted when a widget becomes shadowed by a GTK+ grab (not a pointer or keyboard grab) on another widget, or when it becomes unshadowed due to a grab being removed.

 

get_request_mode ()

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

This is called by containers to obtain the minimum and natural size of the widget. 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 ()

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

 

grab_focus ()

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

 

focus ()

Vfunc for gtk_widget_child_focus()

 

set_focus_child ()

Sets the focused child of a widget. Must chain up

 

move_focus ()

Signal emitted when a change of focus is requested

 

keynav_failed ()

Signal emitted if keyboard navigation fails.

 

get_accessible ()

Returns the accessible object that describes the widget to an assistive technology.

 

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.

 

compute_expand ()

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

 

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.

 

system_setting_changed ()

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

 

snapshot ()

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

 

contains ()

Vfunc for gtk_widget_contains().

 

GtkRequisition

typedef struct {
  gint width;
  gint height;
} GtkRequisition;

A GtkRequisition represents the desired size of a widget. See GtkWidget’s geometry management section for more information.

Members

gint width;

the widget’s desired width

 

gint height;

the widget’s desired height

 

GtkAllocation

typedef         GdkRectangle       GtkAllocation;

A GtkAllocation of a widget represents region which has been allocated to the widget by its parent. It is a subregion of its parents allocation. See GtkWidget’s geometry management section for more information.


enum GtkTextDirection

Reading directions for text.

Members

GTK_TEXT_DIR_NONE

No direction.

 

GTK_TEXT_DIR_LTR

Left to right text direction.

 

GTK_TEXT_DIR_RTL

Right to left text direction.

 

enum GtkPickFlags

Flags that influence the behavior of gtk_widget_pick()

Members

GTK_PICK_DEFAULT

The default behavior, include widgets that are receiving events

 

GTK_PICK_INSENSITIVE

Include widgets that are insensitive

 

GTK_PICK_NON_TARGETABLE

Include widgets that are marked as non-targetable. See “can-target”

 

enum GtkOverflow

Defines how content overflowing a given area should be handled, such as with gtk_widget_set_overflow(). This property is modeled after the CSS overflow property, but implements it only partially.

Members

GTK_OVERFLOW_VISIBLE

No change is applied. Content is drawn at the specified position.

 

GTK_OVERFLOW_HIDDEN

Content is clipped to the bounds of the area. Content outside the area is not drawn and cannot be interacted with.

 

enum GtkSizeRequestMode

Specifies a preference for height-for-width or width-for-height geometry management.

Members

GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH

Prefer height-for-width geometry management

 

GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT

Prefer width-for-height geometry management

 

GTK_SIZE_REQUEST_CONSTANT_SIZE

Don’t trade height-for-width or width-for-height

 

struct GtkRequestedSize

struct GtkRequestedSize {
  gpointer data;
  gint     minimum_size;
  gint     natural_size;
};

Represents a request of a screen object in a given orientation. These are primarily used in container implementations when allocating a natural size for children calling. See gtk_distribute_natural_allocation().

Members

gpointer data;

A client pointer

 

gint minimum_size;

The minimum size needed for allocation in a given orientation

 

gint natural_size;

The natural size for allocation in a given orientation

 

enum GtkAlign

Controls how a widget deals with extra space in a single (x or y) dimension.

Alignment only matters if the widget receives a “too large” allocation, for example if you packed the widget with the “expand” flag inside a GtkBox, then the widget might get extra space. If you have for example a 16x16 icon inside a 32x32 space, the icon could be scaled and stretched, it could be centered, or it could be positioned to one side of the space.

Note that in horizontal context GTK_ALIGN_START and GTK_ALIGN_END are interpreted relative to text direction.

GTK_ALIGN_BASELINE support is optional for containers and widgets, and it is only supported for vertical alignment. When it's not supported by a child or a container it is treated as GTK_ALIGN_FILL .

Members

GTK_ALIGN_FILL

stretch to fill all space if possible, center if no meaningful way to stretch

 

GTK_ALIGN_START

snap to left or top side, leaving space on right or bottom

 

GTK_ALIGN_END

snap to right or bottom side, leaving space on left or top

 

GTK_ALIGN_CENTER

center natural width of widget inside the allocation

 

GTK_ALIGN_BASELINE

align the widget according to the baseline. See GtkWidget

 

Property Details

The “can-focus” property

  “can-focus”                gboolean

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

Owner: GtkWidget

Flags: Read / Write

Default value: TRUE


The “can-target” property

  “can-target”               gboolean

Whether the widget can receive pointer events.

Owner: GtkWidget

Flags: Read / Write

Default value: FALSE


The “css-classes” property

  “css-classes”              GStrv

A list of css classes applied to this widget.

Owner: GtkWidget

Flags: Read / Write


The “css-name” property

  “css-name”                 gchar *

The name of this widget in the CSS tree.

Owner: GtkWidget

Flags: Read / Write / Construct Only

Default value: NULL


The “cursor” property

  “cursor”                   GdkCursor *

The cursor used by widget . See gtk_widget_set_cursor() for details.

Owner: GtkWidget

Flags: Read / Write


The “focus-on-click” property

  “focus-on-click”           gboolean

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

This property is only relevant for widgets that can take focus.

Owner: GtkWidget

Flags: Read / Write

Default value: TRUE


The “focusable” property

  “focusable”                gboolean

Whether this widget itself will accept the input focus.

Owner: GtkWidget

Flags: Read / Write

Default value: FALSE


The “halign” property

  “halign”                   GtkAlign

How to distribute horizontal space if widget gets extra space, see GtkAlign

Owner: GtkWidget

Flags: Read / Write

Default value: GTK_ALIGN_FILL


The “has-default” property

  “has-default”              gboolean

Whether the widget is the default widget.

Owner: GtkWidget

Flags: Read

Default value: FALSE


The “has-focus” property

  “has-focus”                gboolean

Whether the widget has the input focus.

Owner: GtkWidget

Flags: Read

Default value: FALSE


The “has-tooltip” property

  “has-tooltip”              gboolean

Enables or disables the emission of “query-tooltip” on widget . A value of TRUE indicates that widget can have a tooltip, in this case the widget will be queried using “query-tooltip” to determine whether it will provide a tooltip or not.

Owner: GtkWidget

Flags: Read / Write

Default value: FALSE


The “height-request” property

  “height-request”           gint

Override for height request of the widget, or -1 if natural request should be used.

Owner: GtkWidget

Flags: Read / Write

Allowed values: >= -1

Default value: -1


The “hexpand” property

  “hexpand”                  gboolean

Whether to expand horizontally. See gtk_widget_set_hexpand().

Owner: GtkWidget

Flags: Read / Write

Default value: FALSE


The “hexpand-set” property

  “hexpand-set”              gboolean

Whether to use the “hexpand” property. See gtk_widget_get_hexpand_set().

Owner: GtkWidget

Flags: Read / Write

Default value: FALSE


The “layout-manager” property

  “layout-manager”           GtkLayoutManager *

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

Owner: GtkWidget

Flags: Read / Write


The “margin-bottom” property

  “margin-bottom”            gint

Margin on bottom side of widget.

This property adds margin outside of the widget's normal size request, the margin will be added in addition to the size from gtk_widget_set_size_request() for example.

Owner: GtkWidget

Flags: Read / Write

Allowed values: [0,32767]

Default value: 0


The “margin-end” property

  “margin-end”               gint

Margin on end of widget, horizontally. This property supports left-to-right and right-to-left text directions.

This property adds margin outside of the widget's normal size request, the margin will be added in addition to the size from gtk_widget_set_size_request() for example.

Owner: GtkWidget

Flags: Read / Write

Allowed values: [0,32767]

Default value: 0


The “margin-start” property

  “margin-start”             gint

Margin on start of widget, horizontally. This property supports left-to-right and right-to-left text directions.

This property adds margin outside of the widget's normal size request, the margin will be added in addition to the size from gtk_widget_set_size_request() for example.

Owner: GtkWidget

Flags: Read / Write

Allowed values: [0,32767]

Default value: 0


The “margin-top” property

  “margin-top”               gint

Margin on top side of widget.

This property adds margin outside of the widget's normal size request, the margin will be added in addition to the size from gtk_widget_set_size_request() for example.

Owner: GtkWidget

Flags: Read / Write

Allowed values: [0,32767]

Default value: 0


The “name” property

  “name”                     gchar *

The name of the widget.

Owner: GtkWidget

Flags: Read / Write

Default value: NULL


The “opacity” property

  “opacity”                  gdouble

The requested opacity of the widget. See gtk_widget_set_opacity() for more details about window opacity.

Before 3.8 this was only available in GtkWindow

Owner: GtkWidget

Flags: Read / Write

Allowed values: [0,1]

Default value: 1


The “overflow” property

  “overflow”                 GtkOverflow

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

Owner: GtkWidget

Flags: Read / Write

Default value: GTK_OVERFLOW_VISIBLE


The “parent” property

  “parent”                   GtkWidget *

The parent widget of this widget.

Owner: GtkWidget

Flags: Read


The “receives-default” property

  “receives-default”         gboolean

If TRUE, the widget will receive the default action when it is focused.

Owner: GtkWidget

Flags: Read / Write

Default value: FALSE


The “root” property

  “root”                     GtkRoot *

The GtkRoot widget of the widget tree containing this widget or NULL if the widget is not contained in a root widget.

Owner: GtkWidget

Flags: Read


The “scale-factor” property

  “scale-factor”             gint

The scale factor of the widget. See gtk_widget_get_scale_factor() for more details about widget scaling.

Owner: GtkWidget

Flags: Read

Allowed values: >= 1

Default value: 1


The “sensitive” property

  “sensitive”                gboolean

Whether the widget responds to input.

Owner: GtkWidget

Flags: Read / Write

Default value: TRUE


The “tooltip-markup” property

  “tooltip-markup”           gchar *

Sets the text of tooltip to be the given string, which is marked up with the Pango text markup language. Also see gtk_tooltip_set_markup().

This is a convenience property which will take care of getting the tooltip shown if the given string is not NULL: “has-tooltip” will automatically be set to TRUE and there will be taken care of “query-tooltip” in the default signal handler.

Note that if both “tooltip-text” and “tooltip-markup” are set, the last one wins.

Owner: GtkWidget

Flags: Read / Write

Default value: NULL


The “tooltip-text” property

  “tooltip-text”             gchar *

Sets the text of tooltip to be the given string.

Also see gtk_tooltip_set_text().

This is a convenience property which will take care of getting the tooltip shown if the given string is not NULL: “has-tooltip” will automatically be set to TRUE and there will be taken care of “query-tooltip” in the default signal handler.

Note that if both “tooltip-text” and “tooltip-markup” are set, the last one wins.

Owner: GtkWidget

Flags: Read / Write

Default value: NULL


The “valign” property

  “valign”                   GtkAlign

How to distribute vertical space if widget gets extra space, see GtkAlign

Owner: GtkWidget

Flags: Read / Write

Default value: GTK_ALIGN_FILL


The “vexpand” property

  “vexpand”                  gboolean

Whether to expand vertically. See gtk_widget_set_vexpand().

Owner: GtkWidget

Flags: Read / Write

Default value: FALSE


The “vexpand-set” property

  “vexpand-set”              gboolean

Whether to use the “vexpand” property. See gtk_widget_get_vexpand_set().

Owner: GtkWidget

Flags: Read / Write

Default value: FALSE


The “visible” property

  “visible”                  gboolean

Whether the widget is visible.

Owner: GtkWidget

Flags: Read / Write

Default value: TRUE


The “width-request” property

  “width-request”            gint

Override for width request of the widget, or -1 if natural request should be used.

Owner: GtkWidget

Flags: Read / Write

Allowed values: >= -1

Default value: -1

Signal Details

The “destroy” signal

void
user_function (GtkWidget *object,
               gpointer   user_data)

Signals that all holders of a reference to the widget should release the reference that they hold. May result in finalization of the widget if all references are released.

This signal is not suitable for saving widget state.

Parameters

object

the object which received the signal

 

user_data

user data set when the signal handler was connected.

 

Flags: No Hooks


The “direction-changed” signal

void
user_function (GtkWidget       *widget,
               GtkTextDirection previous_direction,
               gpointer         user_data)

The ::direction-changed signal is emitted when the text direction of a widget changes.

Parameters

widget

the object on which the signal is emitted

 

previous_direction

the previous text direction of widget

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “grab-notify” signal

void
user_function (GtkWidget *widget,
               gboolean   was_grabbed,
               gpointer   user_data)

The ::grab-notify signal is emitted when a widget becomes shadowed by a GTK+ grab (not a pointer or keyboard grab) on another widget, or when it becomes unshadowed due to a grab being removed.

A widget is shadowed by a gtk_grab_add() when the topmost grab widget in the grab stack of its window group is not its ancestor.

Parameters

widget

the object which received the signal

 

was_grabbed

FALSE if the widget becomes shadowed, TRUE if it becomes unshadowed

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “hide” signal

void
user_function (GtkWidget *widget,
               gpointer   user_data)

The ::hide signal is emitted when widget is hidden, for example with gtk_widget_hide().

Parameters

widget

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “keynav-failed” signal

gboolean
user_function (GtkWidget       *widget,
               GtkDirectionType direction,
               gpointer         user_data)

Gets emitted if keyboard navigation fails. See gtk_widget_keynav_failed() for details.

Parameters

widget

the object which received the signal

 

direction

the direction of movement

 

user_data

user data set when the signal handler was connected.

 

Returns

TRUE if stopping keyboard navigation is fine, FALSE if the emitting widget should try to handle the keyboard navigation attempt in its parent widget(s).

Flags: Run Last


The “map” signal

void
user_function (GtkWidget *widget,
               gpointer   user_data)

The ::map signal is 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.

The ::map signal can be used to determine whether a widget will be drawn, for instance it can resume an animation that was stopped during the emission of “unmap”.

Parameters

widget

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “mnemonic-activate” signal

gboolean
user_function (GtkWidget *widget,
               gboolean   group_cycling,
               gpointer   user_data)

The default handler for this signal activates widget if group_cycling is FALSE, or just makes widget grab focus if group_cycling is TRUE.

Parameters

widget

the object which received the signal.

 

group_cycling

TRUE if there are other widgets with the same mnemonic

 

user_data

user data set when the signal handler was connected.

 

Returns

TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

Flags: Run Last


The “move-focus” signal

void
user_function (GtkWidget       *widget,
               GtkDirectionType direction,
               gpointer         user_data)

Parameters

widget

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Action


The “query-tooltip” signal

gboolean
user_function (GtkWidget  *widget,
               gint        x,
               gint        y,
               gboolean    keyboard_mode,
               GtkTooltip *tooltip,
               gpointer    user_data)

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.

Using the given coordinates, the signal handler should determine whether a tooltip should be shown for widget . If this is the case TRUE should be returned, FALSE otherwise. Note that if keyboard_mode is TRUE, the values of x and y are undefined and should not be used.

The signal handler is free to manipulate tooltip with the therefore destined function calls.

Parameters

widget

the object which received the signal

 

x

the x coordinate of the cursor position where the request has been emitted, relative to widget 's left side

 

y

the y coordinate of the cursor position where the request has been emitted, relative to widget 's top

 

keyboard_mode

TRUE if the tooltip was triggered using the keyboard

 

tooltip

a GtkTooltip

 

user_data

user data set when the signal handler was connected.

 

Returns

TRUE if tooltip should be shown right now, FALSE otherwise.

Flags: Run Last


The “realize” signal

void
user_function (GtkWidget *widget,
               gpointer   user_data)

The ::realize signal is 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).

Parameters

widget

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “show” signal

void
user_function (GtkWidget *widget,
               gpointer   user_data)

The ::show signal is emitted when widget is shown, for example with gtk_widget_show().

Parameters

widget

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “state-flags-changed” signal

void
user_function (GtkWidget    *widget,
               GtkStateFlags flags,
               gpointer      user_data)

The ::state-flags-changed signal is emitted when the widget state changes, see gtk_widget_get_state_flags().

Parameters

widget

the object which received the signal.

 

flags

The previous state flags.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “unmap” signal

void
user_function (GtkWidget *widget,
               gpointer   user_data)

The ::unmap signal is 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.

As ::unmap indicates that a widget will not be shown any longer, it can be used to, for example, stop an animation on the widget.

Parameters

widget

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “unrealize” signal

void
user_function (GtkWidget *widget,
               gpointer   user_data)

The ::unrealize signal is 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).

Parameters

widget

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last