gobject:initially-unowned, gtk:accessible, gtk:buildable, gtk:constraint-target, gobject:object, common-lisp:standard-object, common-lisp:t

gtk:action-bar, gtk:app-chooser-button, gtk:app-chooser-widget, gtk:aspect-frame, gtk:box, gtk:button, gtk:calendar, gtk:cell-view, gtk:center-box, gtk:check-button, gtk:color-button, gtk:color-chooser-widget, gtk:color-dialog-button, gtk:column-view, gtk:combo-box, gtk:drag-icon, gtk:drawing-area, gtk:drop-down, gtk:editable-label, gtk:entry, gtk:expander, gtk:file-chooser-widget, gtk:fixed, gtk:flow-box, gtk:flow-box-child, gtk:font-button, gtk:font-chooser-widget, gtk:font-dialog-button, gtk:frame, gtk:gl-area, gtk:graphics-offload, gtk:grid, gtk:header-bar, gtk:icon-view, gtk:image, gtk:info-bar, gtk:inscription, gtk:label, gtk:level-bar, gtk:list-base, gtk:list-box, gtk:list-box-row, gtk:media-controls, gtk:menu-button, gtk:notebook, gtk:overlay, gtk:paned, gtk:password-entry, gtk:picture, gtk:popover, gtk:popover-menu-bar, gtk:progress-bar, gtk:range, gtk:revealer, gtk:scale-button, gtk:scrollbar, gtk:scrolled-window, gtk:search-bar, gtk:search-entry, gtk:separator, gtk:shortcut-label, gtk:shortcuts-shortcut, gtk:spin-button, gtk:spinner, gtk:stack, gtk:stack-sidebar, gtk:stack-switcher, gtk:statusbar, gtk:switch, gtk:text, gtk:text-view, gtk:tree-expander, gtk:tree-view, gtk:video, gtk:viewport, gtk:window, gtk:window-controls, gtk:window-handle

The gtk:widget class is the base class all widgets in GTK derive from. It manages the widget life cycle, 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.

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.

GtkWidget as GtkBuildable

The gtk:widget implementation of the gtk:buildable interface supports various custom elements to specify additional aspects of widgets that are not directly expressed as properties.

If the widget uses a gtk:layout-manager object, the gtk:widget implementation supports a custom <layout> element, used to define layout properties:

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

The gtk:widget implementation allows style information such as style classes to be associated with widgets, using the custom <style> element:

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

The gtk:widget implementation allows defining accessibility information, such as properties, relations, and states, using the custom <accessibility> element:

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

Building composite widgets from template XML

The gtk:widget implementation exposes some facilities to automate the proceedure of creating composite widgets using templates.

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 can be used by UI design tools to introspect what kind of properties and internal children exist for a given type when the actual type does not exist.

The XML which is contained inside the <template> tag behaves as if it were added to the <object> tag defining the widget itself. You may set properties on 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 gtk: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>    

The "destroy" signal

lambda (widget)    :no-hooks      

widget

The gtk:widget object which received the signal.

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.

The "direction-changed" signal

lambda (widget direction)    :run-first      

widget

The gtk:widget object on which the signal is emitted.

direction

The previous gtk:text-direction value with the text direction of the widget.

Emitted when the text direction of a widget changes.

The "hide" signal

lambda (widget)    :run-first      

widget

The gtk:widget object which received the signal.

Emitted when the widget is hidden, for example with the gtk:widget-hide function.

The "keynav-failed" signal

lambda (widget direction)    :run-last      

widget

The gtk:widget object which received the signal.

direction

The gtk:direction-type value with the direction of 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).

Gets emitted if keyboard navigation fails.

The "map" signal

lambda (widget)    :run-first      

widget

The gtk:widget object which received the signal.

Emitted 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 "mnemonic-activate" signal

lambda (widget cycling)    :run-last      

widget

The gtk:widget object which received the signal.

cycling

True if there are other widgets with the same mnemonic.

Returns

True to stop other handlers from being invoked for the event, false to propagate the event further.

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

The "move-focus" signal

lambda (widget direction)    :action      

widget

The gtk:widget object which received the signal.

direction

The gtk:direction-type value with the direction.

The "query-tooltip" signal

lambda (widget x y mode tooltip)    :run-last      

widget

The gtk:widget object which received the signal.

x

The integer with the x coordinate of the cursor position where the request has been emitted, relative to the left side of the widget.

y

The integer with the y coordinate of the cursor position where the request has been emitted, relative to the top of the widget.

mode

True if the tooltip was trigged using the keyboard.

tooltip

The gtk:tooltip object.

Returns

True if the tooltip should be shown right now, false otherwise.

Emitted when the tooltip of the widget is about to be shown. This happens when the has-tooltip property is true and the hover timeout has expired with the cursor hovering "above" the 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" signal

lambda (widget)    :run-first      

widget

The gtk:widget object which received the signal.

Emitted when the widget is associated with a gdk:surface 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 "show" signal

lambda (widget)      

widget

The gtk:widget object which received the signal.

Emitted when the widget is shown, for example with the gtk:widget-show function.

The "state-flags-changed" signal

lambda (widget flags)    :run-first      

widget

The gtk:widget object which received the signal.

flags

The previous gtk:state-flags value with the state flags.

Emitted when the widget state changes.

The "unmap" signal

lambda (widget)    :run-first      

widget

The gtk:widget object which received the signal.

Emitted 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 "unrealize" signal

lambda (widget)    :run-last      

widget

The gtk:widget object which received the signal.

Emitted when the gdk:surface 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.