GtkContainer

GtkContainer — Base class for widgets which contain other widgets

Functions

Signals

void add Run First
void remove Run First

Types and Values

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkWidget
            ╰── GtkContainer
                ├── GtkBin
                ├── GtkActionBar
                ├── GtkBox
                ├── GtkDragIcon
                ├── GtkExpander
                ├── GtkFixed
                ├── GtkFlowBox
                ├── GtkGrid
                ├── GtkHeaderBar
                ├── GtkIconView
                ├── GtkInfoBar
                ├── GtkListBox
                ├── GtkNotebook
                ├── GtkPaned
                ├── GtkStack
                ├── GtkTextView
                ╰── GtkTreeView

Implemented Interfaces

GtkContainer implements AtkImplementorIface, GtkBuildable and GtkConstraintTarget.

Includes

#include <gtk/gtk.h>

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 GtkWindow containing a GtkFrame containing a GtkLabel. If you wanted an image instead of a textual label inside the frame, you might replace the GtkLabel widget with a GtkImage 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 GtkBin. These containers are decorators, which add some kind of functionality to the child. For example, a GtkButton makes its child into a clickable button; a GtkFrame draws a frame around its child and a GtkWindow 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 horizontal GtkBox arranges its children in a horizontal row, and a GtkGrid arranges the widgets it contains in a two-dimensional grid.

For implementations of GtkContainer the virtual method GtkContainerClass.forall() is always required, since it's used for drawing and other internal operations on the children. If the GtkContainer 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 gtk_widget_set_parent() on init() and removed with gtk_widget_unparent() in the GtkWidgetClass.destroy() implementation.

See more about implementing custom widgets at https://wiki.gnome.org/HowDoI/CustomWidgets

Functions

gtk_container_add ()

void
gtk_container_add (GtkContainer *container,
                   GtkWidget *widget);

Adds widget to container . Typically used for simple containers such as GtkWindow, GtkFrame, or GtkButton; for more complicated layout containers such GtkGrid, this function will pick default packing parameters that may not be correct. So consider functions such as gtk_grid_attach() as an alternative to gtk_container_add() in those cases. A widget may be added to only one container at a time; you can’t place the same widget inside two different containers.

Note that some containers, such as GtkScrolledWindow or GtkListBox, may add intermediate children between the added widget and the container.

Parameters

container

a GtkContainer

 

widget

a widget to be placed inside container

 

gtk_container_remove ()

void
gtk_container_remove (GtkContainer *container,
                      GtkWidget *widget);

Removes widget from container . widget must be inside container . Note that container will own a reference to widget , and that this may be the last reference held; so removing a widget from its container can destroy that widget. If you want to use widget again, you need to add a reference to it before removing it from a container, using g_object_ref(). If you don’t want to use widget again it’s usually more efficient to simply destroy it directly using gtk_widget_destroy() since this will remove it from the container and help break any circular reference count cycles.

Parameters

container

a GtkContainer

 

widget

a current child of container

 

gtk_container_foreach ()

void
gtk_container_foreach (GtkContainer *container,
                       GtkCallback callback,
                       gpointer callback_data);

Invokes callback on each non-internal child of container . See gtk_container_forall() for details on what constitutes an “internal” child. For all practical purposes, this function should iterate over precisely those child widgets that were added to the container by the application with explicit add() calls.

It is permissible to remove the child from the callback handler.

Most applications should use gtk_container_foreach(), rather than gtk_container_forall().

Parameters

container

a GtkContainer

 

callback

a callback.

[scope call]

callback_data

callback user data

 

gtk_container_get_children ()

GList *
gtk_container_get_children (GtkContainer *container);

Returns the container’s non-internal children. See gtk_container_forall() for details on what constitutes an "internal" child.

Parameters

container

a GtkContainer

 

Returns

a newly-allocated list of the container’s non-internal children.

[element-type GtkWidget][transfer container]


gtk_container_get_focus_vadjustment ()

GtkAdjustment *
gtk_container_get_focus_vadjustment (GtkContainer *container);

Retrieves the vertical focus adjustment for the container. See gtk_container_set_focus_vadjustment().

Parameters

container

a GtkContainer

 

Returns

the vertical focus adjustment, or NULL if none has been set.

[nullable][transfer none]


gtk_container_set_focus_vadjustment ()

void
gtk_container_set_focus_vadjustment (GtkContainer *container,
                                     GtkAdjustment *adjustment);

Hooks up an adjustment to focus handling in a container, so when a child of the container is focused, the adjustment is scrolled to show that widget. This function sets the vertical alignment. See gtk_scrolled_window_get_vadjustment() for a typical way of obtaining the adjustment and gtk_container_set_focus_hadjustment() for setting the horizontal adjustment.

The adjustments have to be in pixel units and in the same coordinate system as the allocation for immediate children of the container.

Parameters

container

a GtkContainer

 

adjustment

an adjustment which should be adjusted when the focus is moved among the descendents of container

 

gtk_container_get_focus_hadjustment ()

GtkAdjustment *
gtk_container_get_focus_hadjustment (GtkContainer *container);

Retrieves the horizontal focus adjustment for the container. See gtk_container_set_focus_hadjustment().

Parameters

container

a GtkContainer

 

Returns

the horizontal focus adjustment, or NULL if none has been set.

[nullable][transfer none]


gtk_container_set_focus_hadjustment ()

void
gtk_container_set_focus_hadjustment (GtkContainer *container,
                                     GtkAdjustment *adjustment);

Hooks up an adjustment to focus handling in a container, so when a child of the container is focused, the adjustment is scrolled to show that widget. This function sets the horizontal alignment. See gtk_scrolled_window_get_hadjustment() for a typical way of obtaining the adjustment and gtk_container_set_focus_vadjustment() for setting the vertical adjustment.

The adjustments have to be in pixel units and in the same coordinate system as the allocation for immediate children of the container.

Parameters

container

a GtkContainer

 

adjustment

an adjustment which should be adjusted when the focus is moved among the descendents of container

 

gtk_container_child_type ()

GType
gtk_container_child_type (GtkContainer *container);

Returns the type of the children supported by the container.

Note that this may return G_TYPE_NONE to indicate that no more children can be added, e.g. for a GtkPaned which already has two children.

Parameters

container

a GtkContainer

 

Returns

a GType


gtk_container_forall ()

void
gtk_container_forall (GtkContainer *container,
                      GtkCallback callback,
                      gpointer callback_data);

Invokes callback on each direct child of container , including children that are considered “internal” (implementation details of the container). “Internal” children generally weren’t added by the user of the container, but were added by the container implementation itself.

Most applications should use gtk_container_foreach(), rather than gtk_container_forall().

[virtual forall]

Parameters

container

a GtkContainer

 

callback

a callback.

[scope call]

callback_data

callback user data.

[closure]

Signal Details

The “add” signal

void
user_function (GtkContainer *container,
               GtkWidget    *widget,
               gpointer      user_data)

Flags: Run First


The “remove” signal

void
user_function (GtkContainer *container,
               GtkWidget    *widget,
               gpointer      user_data)

Flags: Run First