gtk-widget, gtk-buildable, g-object, common-lisp:standard-object, common-lisp:t

gtk-bin, gtk-box, gtk-fixed, gtk-flow-box, gtk-grid, gtk-header-bar, gtk-icon-view, gtk-layout, gtk-list-box, gtk-list-box-row, gtk-menu-shell, gtk-notebook, gtk-paned, gtk-socket, gtk-stack, gtk-table, gtk-text-view, gtk-tool-item-group, gtk-tool-palette, gtk-toolbar, gtk-tree-view

Base class for widgets which contain other widgets.

A GTK user interface is constructed by nesting widgets inside widgets. Container widgets are the inner nodes in the resulting tree of widgets: they contain other widgets. So, for example, you might have a gtk-window widget containing a gtk-frame widget containing a gtk-label widget. If you wanted an image instead of a textual label inside the frame, you might replace the gtk-label widget with a gtk-image widget.

There are two major kinds of container widgets in GTK. Both are subclasses of the abstract gtk-container base class.

The first type of container widget has a single child widget and derives from the gtk-bin class. These containers are decorators, which add some kind of functionality to the child. For example, a gtk-button widget makes its child into a clickable button. A gtk-frame widget draws a frame around its child and a gtk-window widget places its child widget inside a toplevel window.

The second type of container can have more than one child. Its purpose is to manage layout. This means that these containers assign sizes and positions to their children. For example, a gtk-grid widget arranges the widgets it contains in a two-dimensional grid.

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.

There are some things to keep in mind when implementing container widgets that make use of the height for width geometry management system. First, it is important to note that a container must prioritize one of its dimensions, that is to say that a widget or container can only have a gtk-size-request-mode mode that is :height-for-width or :width-for-height. However, every widget and container must be able to respond to the APIs for both dimensions, i.e. even if a widget has a request mode that is height-for-width, it is possible that its parent will request its sizes using the width-for-height APIs.

Child properties

The gtk-container widget introduces child properties. These are object properties that are not specific to either the container or the contained widget, but rather to their relation. Typical examples of child properties are the position or pack-type of a widget which is contained in a gtk-box widget.

Use the gtk-container-class-find-child-property or gtk-container-class-list-child-properties functions to get information about existing child properties.

To obtain or to set the value of a child property, use the gtk-container-child-property, gtk-container-child-get, or gtk-container-child-set functions. To emit notification about child property changes, use the gtk-widget-child-notify function. The gtk-container implementation of the gtk-buildable interface supports a <packing> element for children, which can contain multiple <property> elements that specify child properties for the child.

Child properties can also be marked as translatable using the same "translatable", "comments" and "context" attributes that are used for regular properties.

Containers can have a <focus-chain> element containing multiple <widget> elements, one for each child that should be added to the focus chain. The "name" attribute gives the ID of the widget.

Example: Child properties in UI definitions

<object class="GtkBox">
  <child>
    <object class="GtkEntry" id="entry1"/>
    <packing>
      <property name="pack-type">start</property>
    </packing>
  </child>
  <child>
    <object class="GtkEntry" id="entry2"/>
  </child>
  <focus-chain>
    <widget name="entry1"/>
    <widget name="entry2"/>
  </focus-chain>
</object>    

The "add" signal

 lambda (container widget)    :run-first      

The "check-resize" signal

 lambda (container)    :run-last      

The "remove" signal

 lambda (container widget)    :run-first      

The "set-focus-child" signal

 lambda (container widget)    :run-first