Sets our main struct and passes it to the parent class.
Enable or disable an action installed with gtk_widget_class_install_action().
For widgets that can be “activated” (buttons, menu items, etc.) this function activates them.
Looks up the action in the action groups associated with @widget and its ancestors, and activates it.
Activates the default.activate action from @widget.
Adds @controller to @widget so that it will receive events.
Adds a style class to @widget.
Adds a widget to the list of mnemonic labels for this widget.
Signals that all holders of a reference to the widget should release the reference that they hold.
Emitted when the text direction of a widget changes.
Emitted when @widget is hidden.
Emitted if keyboard navigation fails.
Emitted when @widget is going to be mapped.
Emitted when a widget is activated via a mnemonic.
Emitted when the focus is moved.
Emitted when the widgets tooltip is about to be shown.
Emitted when @widget is associated with a GdkSurface.
Emitted when @widget is shown.
Emitted when the widget state changes.
Emitted when @widget is going to be unmapped.
Emitted when the GdkSurface associated with @widget is destroyed.
Queues an animation frame update and adds a callback to be called before each frame.
This function is only used by GtkWidget subclasses, to assign a size, position and (optionally) baseline to their child widgets.
Called by widgets as the user moves around the window using keyboard shortcuts.
Computes the bounds for @widget in the coordinate space of @target.
Computes whether a container should give this widget extra space when possible.
Translates the given @point in @widget's coordinates to coordinates relative to @target’s coordinate system.
Computes a matrix suitable to describe a transformation from @widget's coordinate system into @target's coordinate system.
Tests if the point at (@x, @y) is contained in @widget.
Creates a new PangoContext with the appropriate font map, font options, font description, and base direction for drawing text for this widget.
Creates a new PangoLayout with the appropriate font map, font description, and base direction for drawing text for this widget.
Checks to see if a drag movement has passed the GTK drag threshold.
Notifies the user about an input-related error on this widget.
Returns the baseline that has currently been allocated to @widget.
Returns the height that has currently been allocated to @widget.
Returns the width that has currently been allocated to @widget.
Retrieves the widget’s allocation.
Gets the first ancestor of @widget with type @widget_type.
Determines whether the input focus can enter @widget or any of its children.
Queries whether @widget can be the target of pointer events.
Gets the value set with gtk_widget_set_child_visible().
Gets the clipboard object for @widget.
Returns the list of style classes applied to @widget.
Returns the CSS name that is used for @self.
Queries the cursor set on @widget.
Gets the reading direction for a particular widget.
Get the GdkDisplay for the toplevel window associated with this widget.
Returns the widgets first child.
Returns the current focus child of @widget.
Returns whether the widget should grab focus when it is clicked with the mouse.
Determines whether @widget can own the input focus.
Gets the font map of @widget.
Returns the cairo_font_options_t used for Pango rendering.
Obtains the frame clock for a widget.
Gets the horizontal alignment of @widget.
Returns the current value of the has-tooltip property.
Returns the content height of the widget.
Gets whether the widget would like any available extra horizontal space.
Gets whether gtk_widget_set_hexpand() has been used to explicitly set the expand flag on this widget.
Returns the widgets last child.
Retrieves the layout manager used by @widget
Whether the widget is mapped.
Gets the bottom margin of @widget.
Gets the end margin of @widget.
Gets the start margin of @widget.
Gets the top margin of @widget.
Retrieves the name of a widget.
Returns the GtkNative widget that contains @widget.
Returns the widgets next sibling.
#Fetches the requested opacity for this widget.
Returns the widgets overflow value.
Gets a PangoContext with the appropriate font map, font description, and base direction for this widget.
Returns the parent widget of @widget.
Retrieves the minimum and natural size of a widget, taking into account the widget’s preference for height-for-width management.
Returns the widgets previous sibling.
Gets the primary clipboard of @widget.
Determines whether @widget is realized.
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.
Gets whether the widget prefers a height-for-width layout or a width-for-height layout.
Returns the GtkRoot widget of @widget.
Retrieves the internal scale factor that maps from window coordinates to the actual device pixels.
Returns the widget’s sensitivity.
Gets the settings object holding the settings used for this widget.
Returns the content width or height of the widget.
Gets the size request that was explicitly set for the widget using gtk_widget_set_size_request().
Returns the widget state as a flag set.
the main Gtk struct as a void*
Returns the style context associated to @widget.
Fetch an object build from the template XML for @widget_type in this @widget instance.
Gets the contents of the tooltip for @widget.
Gets the contents of the tooltip for @widget.
Gets the vertical alignment of @widget.
Gets whether the widget would like any available extra vertical space.
Gets whether gtk_widget_set_vexpand() has been used to explicitly set the expand flag on this widget.
Determines whether the widget is visible.
Get the main Gtk struct
Returns the content width of the widget.
Causes @widget to have the keyboard focus for the GtkWindow it's inside.
Returns whether @css_class is currently applied to @widget.
Determines whether @widget is the current default widget within its toplevel.
Determines if the widget has the global input focus.
Determines if the widget should show a visible indication that it has the global input focus.
Reverses the effects of gtk_widget_show().
Returns whether the widget is currently being destroyed.
Creates and initializes child widgets defined in templates.
Inserts @group into @widget.
Inserts @widget into the child widget list of @parent.
Inserts @widget into the child widget list of @parent.
Determines whether @widget is somewhere inside @ancestor, possibly with intermediate containers.
Determines whether @widget can be drawn to.
Determines if the widget is the focus widget within its toplevel.
Returns the widget’s effective sensitivity.
Determines whether the widget and all its parents are marked as visible.
Emits the ::keynav-failed signal on the widget.
Returns the widgets for which this widget is the target of a mnemonic.
Causes a widget to be mapped if it isn’t already.
Measures @widget in the orientation @orientation and for the given @for_size.
Emits the GtkWidget::mnemonic-activate signal.
Returns a GListModel to track the children of @widget.
Returns a GListModel to track the [class@Gtk.EventController]s of @widget.
Finds the descendant of @widget closest to the screen at the point (@x, @y).
Flags the widget for a rerun of the GtkWidgetClass::size_allocate function.
Schedules this widget to be redrawn in paint phase of the current or the next frame.
Flags a widget to have its size renegotiated.
Creates the GDK resources associated with a widget.
Removes @controller from @widget, so that it doesn't process events anymore.
Removes a style from @widget.
Removes a widget from the list of mnemonic labels for this widget.
Removes a tick callback previously registered with gtk_widget_add_tick_callback().
Specifies whether the input focus can enter the widget or any of its children.
Sets whether @widget can be the target of pointer events.
Sets whether @widget should be mapped along with its parent.
Will clear all style classes applied to @widget and replace them with @classes.
Sets the cursor to be shown when pointer devices point towards @widget.
Sets a named cursor to be shown when pointer devices point towards @widget.
Sets the reading direction on a particular widget.
Set @child as the current focus child of @widget.
Sets whether the widget should grab focus when it is clicked with the mouse.
Specifies whether @widget can own the input focus.
Sets the font map to use for Pango rendering.
Sets the cairo_font_options_t used for Pango rendering in this widget.
Sets the horizontal alignment of @widget.
Sets the has-tooltip property on @widget to @has_tooltip.
Sets whether the widget would like any available extra horizontal space.
Sets whether the hexpand flag will be used.
Sets the layout manager delegate instance that provides an implementation for measuring and allocating the children of @widget.
Sets the bottom margin of @widget.
Sets the end margin of @widget.
Sets the start margin of @widget.
Sets the top margin of @widget.
Sets a widgets name.
Request the @widget to be rendered partially transparent.
Sets how @widget treats content that is drawn outside the widget's content area.
Sets @parent as the parent widget of @widget.
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.
Sets the sensitivity of a widget.
Sets the minimum size of a widget.
Turns on flag values in the current widget state.
Sets @markup as the contents of the tooltip, which is marked up with Pango markup.
Sets @text as the contents of the tooltip.
Sets the vertical alignment of @widget.
Sets whether the widget would like any available extra vertical space.
Sets whether the vexpand flag will be used.
Sets the visibility state of @widget.
Returns whether @widget should contribute to the measuring and allocation of its parent.
Flags a widget to be displayed.
Allocates widget with a transformation that translates the origin to the position in @allocation.
Snapshot the a child of @widget.
Translate coordinates relative to @src_widget’s allocation to coordinates relative to @dest_widget’s allocations.
Triggers a tooltip query on the display where the toplevel of @widget is located.
Causes a widget to be unmapped if it’s currently mapped.
Dissociate @widget from its parent.
Causes a widget to be unrealized (frees all GDK resources associated with the widget).
Turns off flag values for the current widget state.
Obtains the current default reading direction.
Sets the default reading direction for widgets.
the main Gtk struct
the main Gtk struct
Get the main Gtk struct
the main Gtk struct as a void*
Gets a D Object from the objects table of associations.
The notify signal is emitted on an object when one of its properties has been changed. Note that getting this signal doesn't guarantee that the value of the property has actually changed, it may also be emitted when the setter for the property is called to reinstate the previous value.
Find the #GParamSpec with the given name for an interface. Generally, the interface vtable passed in as @g_iface will be the default vtable from g_type_default_interface_ref(), or, if you know the interface has already been loaded, g_type_default_interface_peek().
Add a property to an interface; this is only useful for interfaces that are added to GObject-derived types. Adding a property to an interface forces all objects classes with that interface to have a compatible property. The compatible property could be a newly created #GParamSpec, but normally g_object_class_override_property() will be used so that the object class only needs to provide an implementation and inherits the property description, default value, bounds, and so forth from the interface property.
Lists the properties of an interface.Generally, the interface vtable passed in as @g_iface will be the default vtable from g_type_default_interface_ref(), or, if you know the interface has already been loaded, g_type_default_interface_peek().
Increases the reference count of the object by one and sets a callback to be called when all other references to the object are dropped, or when this is already the last reference to the object and another reference is established.
Adds a weak reference from weak_pointer to @object to indicate that the pointer located at @weak_pointer_location is only valid during the lifetime of @object. When the @object is finalized, @weak_pointer will be set to %NULL.
Creates a binding between @source_property on @source and @target_property on @target. Whenever the @source_property is changed the @target_property is updated using the same value. For instance:
Complete version of g_object_bind_property().
Creates a binding between @source_property on @source and @target_property on @target, allowing you to set the transformation functions to be used by the binding.
This is a variant of g_object_get_data() which returns a 'duplicate' of the value. @dup_func defines the meaning of 'duplicate' in this context, it could e.g. take a reference on a ref-counted object.
This is a variant of g_object_get_qdata() which returns a 'duplicate' of the value. @dup_func defines the meaning of 'duplicate' in this context, it could e.g. take a reference on a ref-counted object.
This function is intended for #GObject implementations to re-enforce a floating[floating-ref] object reference. Doing this is seldom required: all #GInitiallyUnowneds are created with a floating reference which usually just needs to be sunken by calling g_object_ref_sink().
Increases the freeze count on @object. If the freeze count is non-zero, the emission of "notify" signals on @object is stopped. The signals are queued until the freeze count is decreased to zero. Duplicate notifications are squashed so that at most one #GObject::notify signal is emitted for each property modified while the object is frozen.
Gets a named field from the objects table of associations (see g_object_set_data()).
Gets a property of an object.
This function gets back user data pointers stored via g_object_set_qdata().
Gets properties of an object.
Gets @n_properties properties for an @object. Obtained properties will be set to @values. All properties must be valid. Warnings will be emitted and undefined behaviour may result if invalid properties are passed in.
Checks whether @object has a floating[floating-ref] reference.
Emits a "notify" signal for the property @property_name on @object.
Emits a "notify" signal for the property specified by @pspec on @object.
Increases the reference count of @object.
Increase the reference count of @object, and possibly remove the floating[floating-ref] reference, if @object has a floating reference.
Removes a reference added with g_object_add_toggle_ref(). The reference count of the object is decreased by one.
Removes a weak reference from @object that was previously added using g_object_add_weak_pointer(). The @weak_pointer_location has to match the one used with g_object_add_weak_pointer().
Compares the user data for the key @key on @object with @oldval, and if they are the same, replaces @oldval with @newval.
Compares the user data for the key @quark on @object with @oldval, and if they are the same, replaces @oldval with @newval.
Releases all references to other objects. This can be used to break reference cycles.
Each object carries around a table of associations from strings to pointers. This function lets you set an association.
Like g_object_set_data() except it adds notification for when the association is destroyed, either by setting it to a different value or when the object is destroyed.
Sets a property on an object.
This sets an opaque, named pointer on an object. The name is specified through a #GQuark (retrieved e.g. via g_quark_from_static_string()), and the pointer can be gotten back from the @object with g_object_get_qdata() until the @object is finalized. Setting a previously set user data pointer, overrides (frees) the old pointer set, using #NULL as pointer essentially removes the data stored.
This function works like g_object_set_qdata(), but in addition, a void (*destroy) (gpointer) function may be specified which is called with @data as argument when the @object is finalized, or the data is being overwritten by a call to g_object_set_qdata() with the same @quark.
Sets properties on an object.
Sets @n_properties properties for an @object. Properties to be set will be taken from @values. All properties must be valid. Warnings will be emitted and undefined behaviour may result if invalid properties are passed in.
Remove a specified datum from the object's data associations, without invoking the association's destroy handler.
This function gets back user data pointers stored via g_object_set_qdata() and removes the @data from object without invoking its destroy() function (if any was set). Usually, calling this function is only required to update user data pointers with a destroy notifier, for example: |[<!-- language="C" --> void object_add_to_user_list (GObject *object, const gchar *new_string) { // the quark, naming the object data GQuark quark_string_list = g_quark_from_static_string ("my-string-list"); // retrieve the old string list GList *list = g_object_steal_qdata (object, quark_string_list);
Reverts the effect of a previous call to g_object_freeze_notify(). The freeze count is decreased on @object and when it reaches zero, queued "notify" signals are emitted.
Decreases the reference count of @object. When its reference count drops to 0, the object is finalized (i.e. its memory is freed).
This function essentially limits the life time of the @closure to the life time of the object. That is, when the object is finalized, the @closure is invalidated by calling g_closure_invalidate() on it, in order to prevent invocations of the closure with a finalized (nonexisting) object. Also, g_object_ref() and g_object_unref() are added as marshal guards to the @closure, to ensure that an extra reference count is held on @object during invocation of the @closure. Usually, this function will be called on closures that use this @object as closure data.
Adds a weak reference callback to an object. Weak references are used for notification when an object is disposed. They are called "weak references" because they allow you to safely hold a pointer to an object without calling g_object_ref() (g_object_ref() adds a strong reference, that is, forces the object to stay alive).
Removes a weak reference callback to an object.
Clears a reference to a #GObject.
Get the main Gtk struct
the main Gtk struct as a void*
Retrieves the GtkAccessibleRole for the given GtkAccessible.
Resets the accessible @property to its default value.
Resets the accessible @relation to its default value.
Resets the accessible @state to its default value.
Updates an array of accessible properties.
Updates an array of accessible relations.
Updates an array of accessible states.
Get the main Gtk struct
the main Gtk struct as a void*
Gets the ID of the @buildable object.
Get the main Gtk struct
the main Gtk struct as a void*
The base class for all widgets.
GtkWidget is the base class all widgets in GTK derive from. It manages the widget lifecycle, layout, states and style.
Height-for-width Geometry Management
GTK uses a height-for-width (and width-for-height) geometry management system. Height-for-width means that a widget can change how much vertical space it needs, depending on the amount of horizontal space that it is given (and similar for width-for-height). The most common example is a label that reflows to fill up the available width, wraps to fewer lines, and therefore needs less height.
Height-for-width geometry management is implemented in GTK by way of two virtual methods:
- [vfunc@Gtk.Widget.get_request_mode] - [vfunc@Gtk.Widget.measure]
There are some important things to keep in mind when implementing height-for-width and when using it in widget implementations.
If you implement a direct GtkWidget subclass that supports height-for-width or width-for-height geometry management for itself or its child widgets, the [vfunc@Gtk.Widget.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 [vfunc@Gtk.Widget.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 [enum@Gtk.SizeRequestMode] 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 [id@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 [id@gtk_widget_measure] with an orientation of %GTK_ORIENTATION_VERTICAL and a for_size of the just computed width. This will also be a highly recursive operation. The minimum height for the minimum width is normally used to set the minimum size constraint on the toplevel.
After the toplevel window has initially requested its size in both dimensions it can go on to allocate itself a reasonable size (or a size previously specified with [method@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 [class@Gtk.Label] that does height-for-width word wrapping will not expect to have [vfunc@Gtk.Widget.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:
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 [method@Gtk.Widget.measure] inside your own [vfunc@Gtk.Widget.size_allocate] implementation. These return a request adjusted by [class@Gtk.SizeGroup], 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 [id@gtk_widget_measure]; otherwise, you would not properly consider widget margins, [class@Gtk.SizeGroup], 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 [vfunc@Gtk.Widget.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 [id@gtk_widget_get_allocated_baseline]. If the baseline has a value other than -1 you need to align the widget such that the baseline appears at the position.
GtkWidget as GtkBuildable
The GtkWidget implementation of the GtkBuildable interface supports various custom elements to specify additional aspects of widgets that are not directly expressed as properties.
If the widget uses a [class@Gtk.LayoutManager], GtkWidget supports a custom <layout> element, used to define layout properties:
GtkWidget allows style information such as style classes to be associated with widgets, using the custom <style> element:
GtkWidget allows defining accessibility information, such as properties, relations, and states, using the custom <accessibility> element:
Building composite widgets from template XML
GtkWidget exposes some facilities to automate the procedure of creating composite widgets using "templates".
To create composite widgets with GtkBuilder XML, one must associate the interface description with the widget class at class initialization time using [method@Gtk.WidgetClass.set_template].
The interface description semantics expected in composite template descriptions is slightly different from regular [class@Gtk.Builder] XML.
Unlike regular interface descriptions, [method@Gtk.WidgetClass.set_template] will expect a <template> tag as a direct child of the toplevel <interface> tag. The <template> tag must specify the “class” attribute which must be the type name of the widget. Optionally, the “parent” attribute may be specified to specify the direct parent type of the widget type, this is ignored by GtkBuilder but required for UI design tools like 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 the widget itself. You may set properties on a widget by inserting <property> tags into the <template> tag, and also add <child> tags to add children and extend a widget in the normal way you would with <object> tags.
Additionally, <object> tags can also be added before and after the initial <template> tag in the normal way, allowing one to define auxiliary objects which might be referenced by other widgets declared as children of the <template> tag.
An example of a template definition:
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 [method@Gtk.WidgetClass.set_template_from_resource] from the class initialization of your GtkWidget type:
You will also need to call [method@Gtk.Widget.init_template] from the instance initialization function:
You can access widgets defined in the template using the [id@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 [method@Gtk.WidgetClass.bind_template_child_full] (or one of its wrapper macros [func@Gtk.widget_class_bind_template_child] and [func@Gtk.widget_class_bind_template_child_private]) with that name, e.g.
You can also use [method@Gtk.WidgetClass.bind_template_callback_full] (or is wrapper macro [func@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.