+++ /dev/null
-<!-- ##### SECTION Title ##### -->
-GtkContainer
-
-<!-- ##### SECTION Short_Description ##### -->
-Base class for widgets which contain other widgets
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-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.
-</para>
-<para>
-There are two major kinds of container widgets in GTK+. Both are subclasses
-of the abstract #GtkContainer base class.
-</para>
-<para>
-The first type of container widget has a single child widget and derives
-from #GtkBin. These containers are <firstterm>decorators</firstterm>, 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.
-</para>
-<para>
-The second type of container can have more than one child; its purpose is to
-manage <firstterm>layout</firstterm>. 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 #GtkTable arranges the widgets it contains
-in a two-dimensional grid.
-</para>
-<para>
-To fulfill its task, a layout container must negotiate the size requirements
-with its parent and its children. The basic form of this negotiation is
-carried out in two phases, <firstterm>size requisition</firstterm> and
-<firstterm>size allocation</firstterm>, which are implemented by the
-size_request() and size_allocate() virtual functions in #GtkWidget.
-</para>
-<para>
-GTK+ also supports a more complicated form of size negotiation called
-<firstterm>width-for-height</firstterm> (and its dual
-<firstterm>height-for-width</firstterm>). See #GtkExtendedLayout
-to learn more about width-for-height geometry management.
-</para>
-<refsect2 id="size-requisition"><title>Size Requisition</title>
-<para>
-The size requisition of a widget is it's desired width and height.
-This is represented by a #GtkRequisition.
-</para>
-<para>
-How a widget determines its desired size depends on the widget.
-A #GtkLabel, for example, requests enough space to display all its text.
-Container widgets generally base their size request on the requisitions
-of their children.
-</para>
-<para>
-The size requisition phase of the widget layout process operates top-down.
-It starts at a top-level widget, typically a #GtkWindow. The top-level widget
-asks its child for its size requisition by calling gtk_widget_get_preferred_size().
-To determine its requisition, the child asks its own children for their
-requisitions and so on. Finally, the top-level widget will get a requisition
-back from its child.
-</para>
-</refsect2>
-<refsect2 id="size-allocation"><title>Size Allocation</title>
-<para>
-When the top-level widget has determined how much space its child would like
-to have, the second phase of the size negotiation, size allocation, begins.
-Depending on its configuration (see gtk_window_set_resizable()), the top-level
-widget may be able to expand in order to satisfy the size request or it may
-have to ignore the size request and keep its fixed size. It then tells its
-child widget how much space it gets by calling gtk_widget_size_allocate().
-The child widget divides the space among its children and tells each child
-how much space it got, and so on. Under normal circumstances, a #GtkWindow
-will always give its child the amount of space the child requested.
-</para>
-<para>
-A child's size allocation is represented by a #GtkAllocation. This struct
-contains not only a width and height, but also a position (i.e. X and Y
-coordinates), so that containers can tell their children not only how much
-space they have gotten, but also where they are positioned inside the space
-available to the container.
-</para>
-<para>
-Widgets are required to honor the size allocation they receive; a size
-request is only a request, and widgets must be able to cope with any size.
-</para>
-</refsect2>
-<refsect2 id="child-properties"><title>Child properties</title>
-<para>
-<structname>GtkContainer</structname> introduces <firstterm>child
-properties</firstterm> - 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 #GtkBox.</para>
-<para>
-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.
-</para>
-<para>
-To set the value of a child property, use gtk_container_child_set_property(),
-gtk_container_child_set() or gtk_container_child_set_valist().
-To obtain the value of a child property, use
-gtk_container_child_get_property(), gtk_container_child_get() or
-gtk_container_child_get_valist(). To emit notification about child property
-changes, use gtk_widget_child_notify().
-</para>
-</refsect2>
-
-<refsect2 id="GtkContainer-BUILDER-UI">
-<title>GtkContainer as GtkBuildable</title>
-<para>
-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.
-</para>
-<example>
-<title>Child properties in UI definitions</title>
-<programlisting><![CDATA[
-<object class="GtkVBox">
- <child>
- <object class="GtkLabel"/>
- <packing>
- <property name="pack-type">start</property>
- </packing>
- </child>
-</object>
-]]></programlisting>
-</example>
-<para>
-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.
-</para>
-</refsect2>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### SECTION Image ##### -->
-
-
-<!-- ##### STRUCT GtkContainer ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SIGNAL GtkContainer::add ##### -->
-<para>
-
-</para>
-
-@container: the object which received the signal.
-@widget:
-
-<!-- ##### SIGNAL GtkContainer::check-resize ##### -->
-<para>
-
-</para>
-
-@container: the object which received the signal.
-
-<!-- ##### SIGNAL GtkContainer::remove ##### -->
-<para>
-
-</para>
-
-@container: the object which received the signal.
-@widget:
-
-<!-- ##### SIGNAL GtkContainer::set-focus-child ##### -->
-<para>
-
-</para>
-
-@container: the object which received the signal.
-@widget:
-
-<!-- ##### ARG GtkContainer:border-width ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkContainer:child ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkContainer:resize-mode ##### -->
-<para>
-
-</para>
-
-<!-- ##### MACRO GTK_IS_RESIZE_CONTAINER ##### -->
-<para>
-
-</para>
-
-@widget:
-
-
-<!-- ##### MACRO GTK_CONTAINER_WARN_INVALID_CHILD_PROPERTY_ID ##### -->
-<para>
-This macro should be used to emit a standard warning about unexpected
-properties in set_child_property() and get_child_property() implementations.
-</para>
-
-@object: the #GObject on which set_child_property() or get_child_property()
- was called
-@property_id: the numeric id of the property
-@pspec: the #GParamSpec of the property
-
-
-<!-- ##### FUNCTION gtk_container_add ##### -->
-<para>
-
-</para>
-
-@container:
-@widget:
-
-
-<!-- ##### FUNCTION gtk_container_remove ##### -->
-<para>
-
-</para>
-
-@container:
-@widget:
-
-
-<!-- ##### FUNCTION gtk_container_add_with_properties ##### -->
-<para>
-
-</para>
-
-@container:
-@widget:
-@first_prop_name:
-@Varargs:
-
-
-<!-- ##### FUNCTION gtk_container_get_resize_mode ##### -->
-<para>
-
-</para>
-
-@container:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_container_set_resize_mode ##### -->
-<para>
-
-</para>
-
-@container:
-@resize_mode:
-
-
-<!-- ##### FUNCTION gtk_container_check_resize ##### -->
-<para>
-
-</para>
-
-@container:
-
-
-<!-- ##### FUNCTION gtk_container_foreach ##### -->
-<para>
-
-</para>
-
-@container:
-@callback:
-@callback_data:
-
-
-<!-- ##### FUNCTION gtk_container_get_children ##### -->
-<para>
-
-</para>
-
-@container:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_container_set_reallocate_redraws ##### -->
-<para>
-
-</para>
-
-@container:
-@needs_redraws:
-
-
-<!-- ##### FUNCTION gtk_container_get_focus_child ##### -->
-<para>
-
-</para>
-
-@container:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_container_set_focus_child ##### -->
-<para>
-
-</para>
-
-@container:
-@child:
-
-
-<!-- ##### FUNCTION gtk_container_get_focus_vadjustment ##### -->
-<para>
-
-</para>
-
-@container:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_container_set_focus_vadjustment ##### -->
-<para>
-
-</para>
-
-@container:
-@adjustment:
-
-
-<!-- ##### FUNCTION gtk_container_get_focus_hadjustment ##### -->
-<para>
-
-</para>
-
-@container:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_container_set_focus_hadjustment ##### -->
-<para>
-
-</para>
-
-@container:
-@adjustment:
-
-
-<!-- ##### FUNCTION gtk_container_resize_children ##### -->
-<para>
-
-</para>
-
-@container:
-
-
-<!-- ##### FUNCTION gtk_container_child_type ##### -->
-<para>
-
-</para>
-
-@container:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_container_child_get ##### -->
-<para>
-
-</para>
-
-@container:
-@child:
-@first_prop_name:
-@Varargs:
-
-
-<!-- ##### FUNCTION gtk_container_child_set ##### -->
-<para>
-
-</para>
-
-@container:
-@child:
-@first_prop_name:
-@Varargs:
-
-
-<!-- ##### FUNCTION gtk_container_child_get_property ##### -->
-<para>
-
-</para>
-
-@container:
-@child:
-@property_name:
-@value:
-
-
-<!-- ##### FUNCTION gtk_container_child_set_property ##### -->
-<para>
-
-</para>
-
-@container:
-@child:
-@property_name:
-@value:
-
-
-<!-- ##### FUNCTION gtk_container_child_get_valist ##### -->
-<para>
-
-</para>
-
-@container:
-@child:
-@first_property_name:
-@var_args:
-
-
-<!-- ##### FUNCTION gtk_container_child_set_valist ##### -->
-<para>
-
-</para>
-
-@container:
-@child:
-@first_property_name:
-@var_args:
-
-
-<!-- ##### FUNCTION gtk_container_forall ##### -->
-<para>
-
-</para>
-
-@container:
-@callback:
-@callback_data:
-
-
-<!-- ##### FUNCTION gtk_container_get_border_width ##### -->
-<para>
-
-</para>
-
-@container:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_container_set_border_width ##### -->
-<para>
-
-</para>
-
-@container:
-@border_width:
-
-
-<!-- ##### FUNCTION gtk_container_propagate_expose ##### -->
-<para>
-
-</para>
-
-@container:
-@child:
-@event:
-
-
-<!-- ##### FUNCTION gtk_container_get_focus_chain ##### -->
-<para>
-
-</para>
-
-@container:
-@focusable_widgets:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_container_set_focus_chain ##### -->
-<para>
-
-</para>
-
-@container:
-@focusable_widgets:
-
-
-<!-- ##### FUNCTION gtk_container_unset_focus_chain ##### -->
-<para>
-
-</para>
-
-@container:
-
-
-<!-- ##### FUNCTION gtk_container_class_find_child_property ##### -->
-<para>
-
-</para>
-
-@cclass:
-@property_name:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_container_class_install_child_property ##### -->
-<para>
-
-</para>
-
-@cclass:
-@property_id:
-@pspec:
-
-
-<!-- ##### FUNCTION gtk_container_class_list_child_properties ##### -->
-<para>
-
-</para>
-
-@cclass:
-@n_properties:
-@Returns:
-
-
#include <gobject/gobjectnotifyqueue.c>
#include <gobject/gvaluecollector.h>
+
+/**
+ * SECTION:gtkcontainer
+ * @Short_description: Base class for widgets which contain other widgets
+ * @Title: GtkContainer
+ *
+ * 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 <emphasis>decorators</emphasis>, 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 <emphasis>layout</emphasis>. 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 #GtkTable arranges the widgets it contains
+ * in a two-dimensional grid.
+ *
+ * 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).
+ * See <link linkend="geometry-management">GtkWidget's geometry management section</link>
+ * to learn more about height-for-width geometry management.
+ * <refsect2 id="child-properties">
+ * <title>Child properties</title>
+ * <para>
+ * GtkContainer introduces <emphasis>child properties</emphasis>.
+ * 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 #GtkBox.
+ *
+ * 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 gtk_container_child_set_property(),
+ * gtk_container_child_set() or gtk_container_child_set_valist().
+ * To obtain the value of a child property, use
+ * gtk_container_child_get_property(), gtk_container_child_get() or
+ * gtk_container_child_get_valist(). To emit notification about child property
+ * changes, use gtk_widget_child_notify().
+ * </para>
+ * </refsect2>
+ * <refsect2 id="GtkContainer-BUILDER-UI">
+ * <title>GtkContainer as GtkBuildable</title>
+ * <para>
+ * 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.
+ * <example>
+ * <title>Child properties in UI definitions</title>
+ * <programlisting><![CDATA[
+ * <object class="GtkVBox">
+ * <child>
+ * <object class="GtkLabel"/>
+ * <packing>
+ * <property name="pack-type">start</property>
+ * </packing>
+ * </child>
+ * </object>
+ * ]]></programlisting>
+ * </example>
+ * 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.
+ * </para>
+ * </refsect2>
+ */
+
+
struct _GtkContainerPrivate
{
GtkWidget *focus_child;
projects / ~andy / gtk / commitdiff