Package: gtk
Class gtk-widget
Superclassesgtk-buildable, g-object, common-lisp:standard-object, common-lisp:t Documented Subclassesgtk-calendar, gtk-cell-view, gtk-container, gtk-drawing-area, gtk-entry, gtk-hsv, gtk-invisible, gtk-level-bar, gtk-misc, gtk-progress-bar, gtk-range, gtk-separator, gtk-spinner, gtk-switch Direct SlotsDetails The gtk-widget class is the base class all widgets in GTK derive from.
It manages the widget life cycle, states and style. Height-for-width Geometry ManagementGTK 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.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 :baseline, and is inside a container that supports baselines and has a natural "row" that it aligns to the baseline, or a baseline assigned to it by the grandparent. If a widget ends up baseline aligned it will be allocated all the space in the parent as if it was :fill, but the selected baseline can be found via the gtk-widget-allocated-baseline function. If this has a value other than -1 you need to align the widget such that the baseline appears at the position. Style PropertiesThe gtk-widget class introduces style properties - these are basically object properties that are stored not on the object, but in the style object associated to the widget. Style properties are set in resource files. This mechanism is used for configuring such things as the location of the scrollbar arrows through the theme, giving theme authors more control over the look of applications without the need to write a theme engine.Use the gtk-widget-class-find-style-property or gtk-widget-class-list-style-properties functions to get information about existing style properties and the gtk-widget-style-property function to obtain the value of a style property. GtkWidget as GtkBuildableThe gtk-widget implementation of the gtk-buildable interface supports a custom <accelerator> element, which has attributes named key, modifiers and signal and allows to specify accelerators.Example: A UI definition fragment specifying an accelerator <object class="GtkButton"> <accelerator key="q" modifiers="GDK_CONTROL_MASK" signal="clicked"/> </object>In addition to accelerators, the gtk-widget implementation 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 gtk-widget object. Example: A UI definition fragment specifying an accessible
<object class="GtkButton" id="label1"/>
<property name="label">I am a Label for a Button</property>
</object>
<object class="GtkButton" id="button1">
<accessibility>
<action action_name="click"
translatable="yes">Click the button.</action>
<relation target="label1" type="labelled-by"/>
</accessibility>
<child internal-child="accessible">
<object class="AtkObject" id="a11y-button1">
<property name="AtkObject::name">Clickable Button</property>
</object>
</child>
</object> Finally, the gtk-widget implementation allows style information such as style classes to be associated with widgets, using the custom <style>
element:Example: A UI definition fragment specifying an style class
<object class="GtkButton" id="button1">
<style>
<class name="my-special-button-class"/>
<class name="dark-button"/>
</style>
</object> Building composite widgets from template XMLThe gtk-widget implementation exposes some facilities to automate the proceedure of creating composite widgets using the gtk-builder interface description language.To create composite widgets with gtk-builder XML, one must associate the interface description with the widget class at class initialization time using the gtk-widget-class-set-template function. The interface description semantics expected in composite template descriptions is slightly different from regulare gtk-builder XML. Unlike regular interface descriptions, the gtk-widget-class-set-template function 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 gtk-builder object 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 the widget itself. You may set properties on the widget by inserting <property> tags into the <template> tag, and also add <child> tags to add children and extend the 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 auxilary objects which might be referenced by other widgets declared as children of the <template> tag. Example: A btk-builder template definition
<interface>
<template class="FooWidget" parent="GtkBox">
<property name="orientation">GTK_ORIENTATION_HORIZONTAL</property>
<property name="spacing">4</property>
<child>
<object class="GtkButton" id="hello_button">
<property name="label">Hello World</property>
</object>
</child>
<child>
<object class="GtkButton" id="goodbye_button">
<property name="label">Goodbye World</property>
</object>
</child>
</template>
</interface> Style Property Details
Signal DetailsThe "accel-closures-changed" signallambda (widget)
The "button-press-event" signallambda (widget event) :run-lastEmitted when a button typically from a mouse is pressed. To receive this signal, the gdk-window object associated to the widget needs to enable the :button-press-mask mask of the gdk-event-mask flags. The signal will be sent to the grab widget if there is one.
The "button-release-event" signallambda (widget event) :run-lastEmitted when a button typically from a mouse is released. To receive this signal, the gdk-window object associated to the widget needs to enable the :button-realease-mask mask of the gdk-event-mask flags. The signal will be sent to the grab widget if there is one.
The "can-activate-accel" signallambda (widget signal) :run-lastDetermines whether an accelerator that activates the signal identified by signal can currently be activated. The signal is present to allow applications and derived widgets to override the default handling for determining whether an accelerator can be activated.
The "child-notify" signallambda (widget pspec) :no-hooksEmitted for each child property that has changed on an object. The detail of the signal holds the property name.
The "composited-changed" signallambda (widget) :actionEmitted when the composited status of widgets screen changes. Warning: The "composited-changed" signal has been deprecated since version 3.22 and should not be used in newly written code. Use the "composited-changed" signal of the gdk-screen class instead.
The "configure-event" signallambda (widget event) :run-lastEmitted when the size, position or stacking of the GDK window of the widget has changed. To receive this signal, the gdk-window object associated to the widget needs to enable the :structure-mask mask of the gdk-event-mask flags. GDK will enable this mask automatically for all new windows.
The "damage-event" signallambda (widget event) :run-lastEmitted when a redirected window belonging to the widget gets drawn into. The region/area members of the event shows what area of the redirected drawable was drawn into.
The "delete-event" signallambda (widget event) :run-lastEmitted if a user requests that a toplevel window is closed. The default handler for this signal destroys the window. Connecting the gtk-widget-hide-on-delete function to this signal will cause the window to be hidden instead, so that it can later be shown again without reconstructing it.
The "destroy" signallambda (widget) :no-hooksSignals 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.
The "destroy-event" signallambda (widget event) :run-lastEmitted when a gdk-window object is destroyed. You rarely get this signal, because most widgets disconnect themselves from their GDK window before they destroy it, so no widget owns the GDK window at destroy time. To receive this signal, the gdk-window object associated to the widget needs to enable the :structure-mask mask of the gdk-event-mask flags. GDK will enable this mask automatically for all new windows.
The "direction-changed" signallambda (widget direction) :run-firstEmitted when the text direction of a widget changes.
The "drag-begin" signallambda (widget context) :run-lastEmitted on the drag source when a drag is started. A typical reason to connect to this signal is to set up a custom drag icon with e.g. the gtk-drag-source-set-icon-pixbuf function. Note that some widgets set up a drag icon in the default handler of this signal, so you may have to use the g-signal-connect function to override what the default handler did.
The "drag-data-delete" signallambda (widget context) :run-lastEmitted on the drag source when a drag with the :move action of the gdk-drag-action flags is successfully completed. The signal handler is responsible for deleting the data that has been dropped. What "delete" means depends on the context of the drag operation.
The "drag-data-get" signallambda (widget context selection info time) :run-lastEmitted on the drag source when the drop site requests the data which is dragged. It is the responsibility of the signal handler to fill the selection argument with the data in the format which is indicated by the info argument. See the gtk-selection-data-set and gtk-selection-data-text functions.
The "drag-data-received" signallambda (widget context x y selection info time) :run-lastEmitted on the drop site when the dragged data has been received. If the data was received in order to determine whether the drop will be accepted, the handler is expected to call the gdk-drag-status function and not finish the drag. If the data was received in response to a "drag-drop" signal and this is the last target to be received, the handler for this signal is expected to process the received data and then call the gtk-drag-finish function, setting the success parameter depending on whether the data was processed successfully. Applications must create some means to determine why the signal was emitted and therefore whether to call the gdk-drag-status or gtk-drag-finish functions. The handler may inspect the selected action with the gdk-drag-context-selected-action function before calling the gtk-drag-finish function, e.g. to implement the :ask value of the gdk-drag-action flags as shown in the following example:
void
drag_data_received (GtkWidget *widget,
GdkDragContext *context,
gint x,
gint y,
GtkSelectionData *data,
guint info,
guint time)
{
if ((data->length >= 0) && (data->format == 8))
{
GdkDragAction action;
The "drag-drop" signallambda (widget context x y time) :run-lastEmitted on the drop site when the user drops the data onto the widget. The signal handler must determine whether the cursor position is in a drop zone or not. If it is not in a drop zone, it returns false and no further processing is necessary. Otherwise, the handler returns true. In this case, the handler must ensure that the gtk-drag-finish function is called to let the source know that the drop is done. The call to the gtk-drag-finish function can be done either directly or in a "drag-data-received" signal handler which gets triggered by calling the gtk-drag-data function to receive the data for one or more of the supported targets.
The "drag-end" signallambda (widget context) :run-lastEmitted on the drag source when a drag is finished. A typical reason to connect to this signal is to undo things done in the "drag-begin" signal handler.
The "drag-failed" signallambda (widget context result) :run-lastEmitted on the drag source when a drag has failed. The signal handler may hook custom code to handle a failed DND operation based on the type of error, it returns true if the failure has been already handled, not showing the default "drag operation failed" animation, otherwise it returns false.
The "drag-leave" signallambda (widget context time) :run-lastEmitted on the drop site when the cursor leaves the widget. A typical reason to connect to this signal is to undo things done in a "drag-motion" signal handler, e.g. undo highlighting with the gtk-drag-unhighlight function. Likewise, the "drag-leave" signal is also emitted before the "drag-drop"signal, for instance to allow cleaning up of a preview item created in the "drag-motion" signal handler.
The "drag-motion" signallambda (widget context x y time) :run-lastEmitted on the drop site when the user moves the cursor over the widget during a drag. The signal handler must determine whether the cursor position is in a drop zone or not. If it is not in a drop zone, it returns false and no further processing is necessary. Otherwise, the handler returns true. In this case, the handler is responsible for providing the necessary information for displaying feedback to the user, by calling the gdk-drag-status function. If the decision whether the drop will be accepted or rejected cannot be made based solely on the cursor position and the type of the data, the handler may inspect the dragged data by calling the gtk-drag-data function and defer the gdk-drag-status function call to the "drag-data-received" signal handler. Note that you cannot pass the :drop, :motion or :all values of the gtk-dest-defaults flags to the gtk-drag-dest-set function when using the "drag-motion" signal that way. Also note that there is no "drag-enter" signal. The drag receiver has to keep track of whether he has received any "drag-motion" signals since the last "drag-leave" signal and if not, treat the "drag-motion" signal as an "enter" signal. Upon an "enter", the handler will typically highlight the drop site with the gtk-drag-highlight function.
static void
drag_motion (GtkWidget *widget,
GdkDragContext *context,
gint x,
gint y,
guint time)
{
GdkAtom target;
The "draw" signallambda (widget cr) :run-lastEmitted when a widget is supposed to render itself. The top left corner of the widget must be painted at the origin of the passed in Cairo context and be sized to the values returned by the gtk-widget-allocated-width and gtk-widget-allocated-height functions. Signal handlers connected to this signal can modify the Cairo context in any way they like and do not need to restore it. The signal emission takes care of calling the cairo-save function before and the cairo-restore function after invoking the handler.
The "enter-notify-event" signallambda (widget event) :run-lastEmitted when the pointer enters the GDK window of the widget. To receive this signal, the gdk-window object associated to the widget needs to enable the :enter-notify-mask mask of the gdk-event-mask flags. The signal will be sent to the grab widget if there is one.
The "event" signallambda (widget event) :run-lastThe GTK main loop will emit three signals for each GDK event delivered to a widget: one generic "event" signal, another, more specific, signal that matches the type of event delivered, e.g. the "key-press-event" signal, and finally a generic "event-after" signal.
The "event-after" signallambda (widget event)After the emission of the "event" signal and optionally the second more specific signal, the signal "event-after" will be emitted regardless of the previous two signals handlers return values.
The "focus" signallambda (widget direction) :run-last
The "focus-in-event" signallambda (widget event) :run-lastEmitted when the keyboard focus enters the GDK window of the widget. To receive this signal, the gdk-window object associated to the widget needs to enable the :focus-change-mask mask of the gdk-event-mask flags.
The "focus-out-event" signallambda (widget event) :run-lastEmitted when the keyboard focus leaves the GDK window of the widget. To receive this signal, the gdk-window object associated to the widget needs to enable the :focus-change-mask mask of the gdk-event-mask flags.
The "grab-broken-event" signallambda (widget event) : run-lastEmitted when a pointer or keyboard grab on a GDK window belonging to the widget gets broken. On X11, this happens when the grab window becomes unviewable, i.e. it or one of its ancestors is unmapped, or if the same application grabs the pointer or keyboard again.
The "grab-focus" signallambda (widget) :action
The "grab-notify" signallambda (widget grabbed) :run-firstEmitted 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 the gtk-grab-add function when the topmost grab widget in the grab stack of its window group is not its ancestor.
The "hide" signallambda (widget) :run-firstEmitted when the widget is hidden, for example with the gtk-widget-hide function.
The "hierarchy-changed" signallambda (widget toplevel) :run-lastEmitted when the anchored state of a widget changes. A widget is anchored when its toplevel ancestor is a gtk-window widget. The signal is emitted when a widget changes from un-anchored to anchored or vice-versa.
The "key-press-event" signallambda (widget event) :run-lastEmitted when a key is pressed. The signal emission will reoccur at the key-repeat rate when the key is kept pressed. To receive this signal, the gdk-window object associated to the widget needs to enable the :key-press-mask mask of the gdk-event-mask flags. This signal will be sent to the grab widget if there is one.
The "key-release-event" signallambda (widget event) :run-lastEmitted when a key is released. To receive this signal, the gdk-window object associated to the widget needs to enable the :key-release-mask mask of the gdk-event-mask flags. This signal will be sent to the grab widget if there is one.
The "keynav-failed" signallambda (widget direction) :run-lastGets emitted if keyboard navigation fails.
The "leave-notify-event" signallambda (widget event) :run-lastEmitted when the pointer leaves the GDK window of the widget. To receive this signal, the gdk-window object associated to the widget needs to enable the :leave-notify-mask mask of the gdk-event-mask flags. The signal will be sent to the grab widget if there is one.
The "map" signallambda (widget) :run-firstEmitted when the widget is going to be mapped, that is when the widget is visible, which is controlled with the gtk-widget-visible function, and all its parents up to the toplevel widget are also visible. Once the map has occurred, the "map-event" signal will be emitted. 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 the "unmap" signal.
The "map-event" signallambda (widget event) :run-lastEmitted when the GDK window of the widget is mapped. A window is mapped when it becomes visible on the screen. To receive this signal, the gdk-window object associated to the widget needs to enable the :structure-mask mask of the gdk-event-mask flags. GDK will enable this mask automatically for all new windows.
The "mnemonic-activate" signalThe default handler for this signal activates the widget if the cycling argument is false, or just makes the widget grab focus if the cycling argument is true.lambda (widget cycling) :run-last
The "motion-notify-event" signallambda (widget event) :run-lastEmitted when the pointer moves over the GDK window of the widget. To receive this signal, the gdk-window object associated to the widget needs to enable the :pointer-motion-mask mask of the gdk-event-mask flags. The signal will be sent to the grab widget if there is one.
The "move-focus" signallambda (widget direction) :action
The "parent-set" signallambda (widget parent) :run-firstEmitted when a new parent has been set on a widget.
The "popup-menu" signallambda (widget) :actionGets emitted whenever a widget should pop up a context menu. This usually happens through the standard key binding mechanism. By pressing a certain key while a widget is focused, the user can cause the widget to pop up a menu.
The "property-notify-event" signallambda (widget event) :run-lastEmitted when a property on the GDK window of the widget has been changed or deleted. To receive this signal, the gdk-window object associated to the widget needs to enable the :property-change-mask mask of the gdk-event-mask flags.
The "proximity-in-event" signallambda (widget event) :run-lastTo receive this signal the gdk-window object associated to the widget needs to enable the :proximity-in-mask mask of the gdk-event-mask flags. The signal will be sent to the grab widget if there is one.
The "proximity-out-event" signallambda (widget event) :run-lastTo receive this signal the gdk-window object associated to the widget needs to enable the :proximity-out-mask mask of the gdk-event-mask flags. The signal will be sent to the grab widget if there is one.
The "query-tooltip" signallambda (widget x y mode tooltip) :run-lastEmitted when the has-tooltip property is true and the gtk-tooltip-timeout setting has expired with the cursor hovering "above" widget, or emitted when the widget got focus in keyboard mode. Using the given coordinates, the signal handler should determine whether a tooltip should be shown for the widget. If this is the case true should be returned, false otherwise. Note that if the mode argument is true, the x and y values are undefined and should not be used. The signal handler is free to manipulate the tooltip argument with the therefore destined function calls.
The "realize" signallambda (widget) :run-firstEmitted when the widget is associated with a gdk-window object, which means that the gtk-widget-realize function has been called or the widget has been mapped, that is, it is going to be drawn.
The "screen-changed" signallambda (widget screen) :run-lastGets emitted when the screen of a widget has changed.
The "scroll-event" signallambda (widget event) :run-lastEmitted when a button in the 4 to 7 range is pressed. Wheel mice are usually configured to generate button press events for buttons 4 and 5 when the wheel is turned. To receive this signal, the gdk-window object associated to the widget needs to enable the :button-press-mask mask of the gdk-event-mask flags. This signal will be sent to the grab widget if there is one.
The "selection-clear-event" signallambda (widget event) :run-lastEmitted when the the GDK window of the widget has lost ownership of a selection.
The "selection-get" signallambda (widget data info time) :run-last
The "selection-notify-event" signallambda (widget event) :run-last
The "selection-received" signallambda (widget data time) :run-last
The "selection-request-event" signallambda (widget event) :run-lastEmitted when another client requests ownership of the selection owned by the GDK window of the widget.
The "show" signallambda (widget)Emitted when the widget is shown, for example with the gtk-widget-show function.
The "show-help" signallambda (widget help) :action
The "size-allocate" signallambda (widget allocation) :run-first
The "state-changed" signallambda (widget state) :run-firstEmitted when the widget state changes. Warning: The "state-changed" signal is deprecated since version 3.0 and should not be used in newly written code. Use the "state-flags-changed" signal instead.
The "state-flags-changed" signallambda (widget flags) :run-firstEmitted when the widget state changes.
The "style-set" signallambda (widget style) :run-firstEmitted when a new style has been set on a widget. Warning: The "style-set" signal has been deprecated since version 3.0 and should not be used in newly written code. Use the "style-updated" signal.
The "style-updated" signallambda (widget) :run-firstEmitted when the gtk-style-context object of a widget is changed. Note that style-modifying functions like the gtk-widget-override-color function also cause this signal to be emitted.
The "touch-event" signallambda (widget event) :run-last
The "unmap" signallambda (widget) :run-firstEmitted when the 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 the "unmap" signal indicates that a widget will not be shown any longer, it can be used to, for example, stop an animation on the widget.
The "unmap-event" signallambda (widget event) :run-lastEmitted when the GDK window of the widget is unmapped. A window is unmapped when it becomes invisible on the screen. To receive this signal, the gdk-window object associated to the widget needs to enable the :structure-mask mask of the gdk-event-mask flags. GDK will enable this mask automatically for all new windows.
The "unrealize" signallambda (widget) :run-lastEmitted when the gdk-window object associated with the widget is destroyed, which means that the gtk-widget-unrealize function has been called or the widget has been unmapped, that is, it is going to be hidden.
The "visibility-notify-event" signallambda (widget event) :run-lastEmitted when the GDK window of the widget is obscured or unobscured. To receive this signal the gdk-window object associated to the widget needs to enable the :visibility-notify-mask mask of the gdk-event-mask flags. Warning: The "visibility-notify-event" signal has been deprecated since version 3.12 and should not be used in newly written code. Modern composited windowing systems with pervasive transparency make it impossible to track the visibility of a window reliably, so this signal can not be guaranteed to provide useful information.
The "window-state-event" signallambda (widget event) :run-lastEmitted when the state of the toplevel window associated to the widget changes. To receive this signal the gdk-window object associated to the widget needs to enable the :structure-mask mask of the gdk-event-mask flags. GDK will enable this mask automatically for all new windows.
| Slot Access FunctionsInherited Slot Access FunctionsSee also |
2021-9-14