#[repr(transparent)]
pub struct Container { /* private fields */ }
Expand description

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 Window containing a Frame containing a Label. If you wanted an image instead of a textual label inside the frame, you might replace the Label widget with a Image widget.

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

The first type of container widget has a single child widget and derives from Bin. These containers are decorators, which add some kind of functionality to the child. For example, a Button makes its child into a clickable button; a Frame draws a frame around its child and a 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 GtkHBox arranges its children in a horizontal row, and a Grid arranges the widgets it contains in a two-dimensional grid.

For implementations of Container the virtual method GtkContainerClass.forall() is always required, since it’s used for drawing and other internal operations on the children. If the Container implementation expect to have non internal children it’s needed to implement both GtkContainerClass.add() and GtkContainerClass.remove(). If the GtkContainer implementation has internal children, they should be added with WidgetExt::set_parent() on init() and removed with WidgetExt::unparent() in the GtkWidgetClass.destroy() implementation. See more about implementing custom widgets at https://wiki.gnome.org/HowDoI/CustomWidgets

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’s 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 SizeRequestMode that is SizeRequestMode::HeightForWidth or SizeRequestMode::WidthForHeight. 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 WidgetExt::preferred_width() and then through WidgetExt::preferred_height_for_width(). When handling requests in the opposite SizeRequestMode it is important that every widget request at least enough space to display all of its content at all times.

When WidgetExt::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:

⚠️ The following code is in C ⚠️

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 WidgetExt::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:

⚠️ The following code is in C ⚠️

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 WidgetExt::preferred_width() for each of its children.

For each potential group of children that are lined up horizontally, the values returned by WidgetExt::preferred_width() should be collected in an array of GtkRequestedSize 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 WidgetExt::preferred_height_for_width() and using the sizes stored in the GtkRequestedSize array.

To allocate a height-for-width container, it’s 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 GtkRequestedSize array and 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 GtkRequestedSize 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 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 [GtkWidget’s geometry management section][geometry-management] to learn more about implementing height-for-width geometry management for widgets.

Child properties

GtkContainer 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 Box.

Use gtk_container_class_install_child_property() to install child properties for a container class and 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 ContainerExtManual::child_set_property(), gtk_container_child_set() or gtk_container_child_set_valist(). To obtain the value of a child property, use [ContainerExtManual::child_get_property()][crate::prelude::ContainerExtManual::child_get_property()], gtk_container_child_get() or gtk_container_child_get_valist(). To emit notification about child property changes, use WidgetExt::child_notify().

GtkContainer as GtkBuildable

The GtkContainer implementation of the GtkBuildable 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:

⚠️ The following code is in xml ⚠️

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

This is an Abstract Base Class, you cannot instantiate it.

Implements

ContainerExt, WidgetExt, glib::ObjectExt, BuildableExt, ContainerExtManual, WidgetExtManual, BuildableExtManual

Implementations

Trait Implementations

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Formats the value using the given formatter. Read more

Feeds this value into the given Hasher. Read more

Feeds a slice of this type into the given Hasher. Read more

Override the virtual methods of this class for the given subclass and do other class initialization. Read more

Instance specific initialization. Read more

This method returns an Ordering between self and other. Read more

Compares and returns the maximum of two values. Read more

Compares and returns the minimum of two values. Read more

Restrict a value to a certain interval. Read more

This method tests for self and other values to be equal, and is used by ==. Read more

This method tests for !=.

This method returns an ordering between self and other values if one exists. Read more

This method tests less than (for self and other) and is used by the < operator. Read more

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more

This method tests greater than (for self and other) and is used by the > operator. Read more

This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more

Returns the type identifier of Self.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Upcasts an object to a superclass or interface T. Read more

Upcasts an object to a reference of its superclass or interface T. Read more

Tries to downcast to a subclass or interface implementor T. Read more

Tries to downcast to a reference of its subclass or interface implementor T. Read more

Tries to cast to an object of type T. This handles upcasting, downcasting and casting between interface and interface implementors. All checks are performed at runtime, while downcast and upcast will do many checks at compile-time already. Read more

Tries to cast to reference to an object of type T. This handles upcasting, downcasting and casting between interface and interface implementors. All checks are performed at runtime, while downcast and upcast will do many checks at compile-time already. Read more

Casts to T unconditionally. Read more

Casts to &T unconditionally. Read more

Performs the conversion.

Performs the conversion.

Returns true if the object is an instance of (can be cast to) T.

Returns the type of the object.

Returns the ObjectClass of the object. Read more

Returns the class of the object.

Returns the class of the object in the given type T. Read more

Returns the interface T of the object. Read more

Similar to Self::set_property but fails instead of panicking.

Sets the property property_name of the object to value value. Read more

Similar to Self::set_property but fails instead of panicking.

Sets the property property_name of the object to value value. Read more

Similar to Self::set_properties but fails instead of panicking.

Sets multiple properties of the object at once. Read more

Similar to Self::set_properties_from_value but fails instead of panicking.

Sets multiple properties of the object at once. Read more

Similar to Self::property but fails instead of panicking.

Gets the property property_name of the object and cast it to the type V. Read more

Similar to Self::property_value but fails instead of panicking.

Gets the property property_name of the object. Read more

Check if the object has a property property_name of the given type_. Read more

Get the type of the property property_name of this object. Read more

Get the ParamSpec of the property property_name of this object.

Return all ParamSpec of the properties of this object.

Freeze all property notifications until the return guard object is dropped. Read more

Set arbitrary data on this object with the given key. Read more

Return previously set arbitrary data of this object with the given key. Read more

Retrieve previously set arbitrary data of this object with the given key. Read more

Set arbitrary data on this object with the given key. Read more

Return previously set arbitrary data of this object with the given key. Read more

Retrieve previously set arbitrary data of this object with the given key. Read more

Block a given signal handler. Read more

Unblock a given signal handler.

Stop emission of the currently emitted signal.

Stop emission of the currently emitted signal by the (possibly detailed) signal name.

Similar to Self::connect but fails instead of panicking.

Connect to the signal signal_name on this object. Read more

Similar to Self::connect_id but fails instead of panicking.

Connect to the signal signal_id on this object. Read more

Similar to Self::connect_local but fails instead of panicking.

Connect to the signal signal_name on this object. Read more

Similar to Self::connect_local_id but fails instead of panicking.

Connect to the signal signal_id on this object. Read more

Similar to Self::connect_unsafe but fails instead of panicking.

Connect to the signal signal_name on this object. Read more

Similar to Self::connect_unsafe_id but fails instead of panicking.

Similar to Self::connect_closure but fails instead of panicking.

Connect a closure to the signal signal_name on this object. Read more

Similar to Self::connect_closure_id but fails instead of panicking.

Connect a closure to the signal signal_id on this object. Read more

Limits the lifetime of closure to the lifetime of the object. When the object’s reference count drops to zero, the closure will be invalidated. An invalidated closure will ignore any calls to Closure::invoke. Read more

Connect to the signal signal_id on this object. Read more

Similar to Self::emit but fails instead of panicking.

Emit signal by signal id. Read more

Similar to Self::emit_with_values but fails instead of panicking.

Same as Self::emit but takes Value for the arguments.

Similar to Self::emit_by_name but fails instead of panicking.

Emit signal by its name. Read more

Similar to Self::emit_by_name_with_values but fails instead of panicking.

Emit signal by its name. Read more

Similar to Self::emit_with_details but fails instead of panicking.

Emit signal by signal id with details. Read more

Similar to Self::emit_with_details_and_values but fails instead of panicking.

Emit signal by signal id with details. Read more

Disconnect a previously connected signal handler.

Connect to the notify signal of the object. Read more

Connect to the notify signal of the object. Read more

Connect to the notify signal of the object. Read more

Notify that the given property has changed its value. Read more

Notify that the given property has changed its value. Read more

Downgrade this object to a weak reference.

Bind property source_property on this object to the target_property on the target object. Read more

Returns the strong reference count of this object.

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

Uses borrowed data to replace owned data, usually by cloning. Read more

Returns a SendValue clone of self.

Converts the given value to a String. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.