Package: gtk

Class gtk-container

Superclasses

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

Documented Subclasses

Direct Slots

border-width
The border-width property of type :uint (Read / Write)
The width of the empty border outside the containers children.
Allowed values: <= 65535
Default value: 0
child
The child property of type gtk-widget (Write)
Can be used to add a new child to the container.
resize-mode
The resize-mode property of type gtk-resize-mode (Read / Write)
Specify how resize events are handled.
Default value: :parent

Details

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 containing a gtk-frame containing a gtk-label. 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 gtk-bin. These containers are decorators, which add some kind of functionality to the child. For example, a gtk-button makes its child into a clickable button; a gtk-frame draws a frame around its child and a gtk-window places its child widget inside a top-level 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 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 GTK+'s 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 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.

To ensure that everything works properly, here are some guidelines to follow when implementing height-for-width (or width-for-height) containers.

Each request mode involves 2 virtual methods. Height-for-width apis run through the function gtk-widget-get-preferred-width and then through the function gtk-widget-get-preferred-height-for-width. When handling requests in the opposite gtk-size-request-mode it is important that every widget request at least enough space to display all of its content at all times.

When the function gtk-widget-get-preferred-height is called on a container that is height-for-width, the container must return the height for its minimum width. This is easily achieved by simply calling the reverse apis implemented for itself as follows:
  static void
  foo_container_get_preferred_height (GtkWidget *widget,
                                      gint *min_height, gint *nat_height)
  {
     if (i_am_in_height_for_width_mode)
       {
         gint min_width;

GTK_WIDGET_GET_CLASS (widget)-> get_preferred_width (widget, &min_width, NULL); GTK_WIDGET_GET_CLASS (widget)-> get_preferred_height_for_width (widget, min_width, min_height, nat_height); } else { ... many containers support both request modes, execute the real width-for-height request here by returning the collective heights of all widgets that are stacked vertically (or whatever is appropriate for this container) ... } }
Similarly, when the function gtk-widget-get-preferred-width-for-height is called for a container or widget that is height-for-width, it then only needs to return the base minimum width like so:
  static void
  foo_container_get_preferred_width_for_height (GtkWidget *widget,
                                                gint for_height,
                                                gint *min_width,
                                                gint *nat_width)
  {
     if (i_am_in_height_for_width_mode)
       {
         GTK_WIDGET_GET_CLASS (widget)->
                    get_preferred_width (widget, min_width, nat_width);
       }
     else
       {
         ... execute the real width-for-height request here based on the
         required width of the children collectively if the container were to
         be allocated the said height ...
       }
  }    
Height for width requests are generally implemented in terms of a virtual allocation of widgets in the input orientation. Assuming an height-for-width request mode, a container would implement the get_preferred_height_for_width() virtual function by first calling the function gtk-widget-get-preferred-width for each of its children.

For each potential group of children that are lined up horizontally, the values returned by the function gtk-widget-get-preferred-width should be collected in an array of gtk-requested-size structures. Any child spacing should be removed from the input for_width and then the collective size should be allocated using the gtk-distribute-natural-allocation convenience function.

The container will then move on to request the preferred height for each child by using the function gtk-widget-get-preferred-height-for-width and using the sizes stored in the gtk-requested-size array.

To allocate a height-for-width container, it is again important to consider that a container must prioritize one dimension over the other. So if a container is a height-for-width container it must first allocate all widgets horizontally using a gtk-requested-size array and the function gtk-distribute-natural-allocation and then add any extra space, if and where appropriate, for the widget to expand.

After adding all the expand space, the container assumes it was allocated sufficient height to fit all of its content. At this time, the container must use the total horizontal sizes of each widget to request the height-for-width of each of its children and store the requests in a gtk-requested-size array for any widgets that stack vertically, for tabular containers this can be generalized into the heights and widths of rows and columns. The vertical space must then again be distributed using the function gtk-distribute-natural-allocation while this time considering the allocated height of the widget minus any vertical spacing that the container adds. Then vertical expand space should be added where appropriate and available and the container should go on to actually allocating the child widgets.

See gtk-widget's geometry management section to learn more about implementing height-for-width geometry management for widgets.

Child properties
gtk-container 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.

Use the function gtk-container-class-install-child-property to install child properties for a container class and the functions gtk-container-class-find-child-property or gtk-container-class-list-child-properties to get information about existing child properties.

To set the value of a child property, use the functions gtk-container-child-set-property or gtk-container-child-set. To obtain the value of a child property, use the functions gtk-container-child-get-property or gtk-container-child-get. To emit notification about child property changes, use the function gtk-widget-child-notify.

GtkContainer as GtkBuildable
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.

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

Since 3.16, 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.

An example of these properties in UI definitions: 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>  

Signal Details

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      
 

Slot Access Functions

Inherited Slot Access Functions

See also

2013-8-1