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_size_request().
+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>
-<!-- ##### MACRO GTK_IS_RESIZE_CONTAINER ##### -->
+<!-- ##### SIGNAL GtkContainer::add ##### -->
<para>
</para>
+@container: the object which received the signal.
@widget:
+<!-- ##### SIGNAL GtkContainer::check-resize ##### -->
+<para>
-<!-- ##### MACRO GTK_CONTAINER_WARN_INVALID_CHILD_PROPERTY_ID ##### -->
+</para>
+
+@container: the object which received the signal.
+
+<!-- ##### SIGNAL GtkContainer::remove ##### -->
<para>
</para>
-@object:
-@property_id:
-@pspec:
+@container: the object which received the signal.
+@widget:
+
+<!-- ##### SIGNAL GtkContainer::set-focus-child ##### -->
+<para>
+
+</para>
+@container: the object which received the signal.
+@widget:
-<!-- ##### MACRO GTK_HAVE_CONTAINER_FOCUS_ADJUSTMENTS ##### -->
+<!-- ##### ARG GtkContainer:border-width ##### -->
<para>
</para>
+<!-- ##### ARG GtkContainer:child ##### -->
+<para>
+</para>
-<!-- ##### MACRO gtk_container_border_width ##### -->
+<!-- ##### 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 ##### -->
@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>
@callback_data:
-<!-- ##### FUNCTION gtk_container_foreach_full ##### -->
+<!-- ##### FUNCTION gtk_container_get_children ##### -->
<para>
</para>
@container:
-@callback:
-@marshal:
-@callback_data:
-@notify:
+@Returns:
-<!-- ##### MACRO gtk_container_children ##### -->
+<!-- ##### FUNCTION gtk_container_set_reallocate_redraws ##### -->
<para>
</para>
-@Returns:
-<!-- # Unused Parameters # -->
@container:
+@needs_redraws:
-<!-- ##### FUNCTION gtk_container_set_reallocate_redraws ##### -->
+<!-- ##### FUNCTION gtk_container_get_focus_child ##### -->
<para>
</para>
@container:
-@needs_redraws:
+@Returns:
<!-- ##### FUNCTION gtk_container_set_focus_child ##### -->
@child:
+<!-- ##### FUNCTION gtk_container_get_focus_vadjustment ##### -->
+<para>
+
+</para>
+
+@container:
+@Returns:
+
+
<!-- ##### FUNCTION gtk_container_set_focus_vadjustment ##### -->
<para>
@adjustment:
+<!-- ##### FUNCTION gtk_container_get_focus_hadjustment ##### -->
+<para>
+
+</para>
+
+@container:
+@Returns:
+
+
<!-- ##### FUNCTION gtk_container_set_focus_hadjustment ##### -->
<para>
@Returns:
+<!-- ##### FUNCTION gtk_container_child_get ##### -->
+<para>
+
+</para>
+
+@container:
+@child:
+@first_prop_name:
+@Varargs:
+
+
<!-- ##### FUNCTION gtk_container_child_set ##### -->
<para>
@child:
@first_prop_name:
@Varargs:
-<!-- # Unused Parameters # -->
-@first_arg_name:
-<!-- ##### FUNCTION gtk_container_queue_resize ##### -->
+<!-- ##### FUNCTION gtk_container_child_get_property ##### -->
<para>
</para>
@container:
+@child:
+@property_name:
+@value:
-<!-- ##### FUNCTION gtk_container_clear_resize_widgets ##### -->
+<!-- ##### 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 ##### -->
@callback_data:
-<!-- ##### FUNCTION gtk_container_child_composite_name ##### -->
+<!-- ##### FUNCTION gtk_container_get_border_width ##### -->
<para>
</para>
@container:
-@child:
@Returns:
@event:
-<!-- ##### FUNCTION gtk_container_set_focus_chain ##### -->
+<!-- ##### FUNCTION gtk_container_get_focus_chain ##### -->
<para>
</para>
@container:
@focusable_widgets:
+@Returns:
-<!-- ##### FUNCTION gtk_container_unset_focus_chain ##### -->
+<!-- ##### FUNCTION gtk_container_set_focus_chain ##### -->
<para>
</para>
@container:
+@focusable_widgets:
-<!-- ##### SIGNAL GtkContainer::add ##### -->
+<!-- ##### FUNCTION gtk_container_unset_focus_chain ##### -->
<para>
</para>
-@container: the object which received the signal.
-@widget:
-
-<!-- ##### SIGNAL GtkContainer::check-resize ##### -->
-<para>
-
-</para>
+@container:
-@container: the object which received the signal.
-<!-- ##### SIGNAL GtkContainer::remove ##### -->
+<!-- ##### FUNCTION gtk_container_class_find_child_property ##### -->
<para>
</para>
-@container: the object which received the signal.
-@widget:
+@cclass:
+@property_name:
+@Returns:
-<!-- ##### SIGNAL GtkContainer::set-focus-child ##### -->
+
+<!-- ##### FUNCTION gtk_container_class_install_child_property ##### -->
<para>
</para>
-@container: the object which received the signal.
-@widget:
-
-<!-- ##### ARG GtkContainer:border-width ##### -->
-<para>
+@cclass:
+@property_id:
+@pspec:
-</para>
-<!-- ##### ARG GtkContainer:resize-mode ##### -->
+<!-- ##### FUNCTION gtk_container_class_list_child_properties ##### -->
<para>
</para>
-<!-- ##### ARG GtkContainer:child ##### -->
-<para>
+@cclass:
+@n_properties:
+@Returns:
-</para>
projects / ~andy / gtk / blobdiff