forked from AuroraMiddleware/gtk
553 lines
11 KiB
Plaintext
553 lines
11 KiB
Plaintext
<!-- ##### 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_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 ##### -->
|
|
|
|
|
|
<!-- ##### 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
|
|
|
|
|
|
<!-- ##### MACRO gtk_container_border_width ##### -->
|
|
<para>
|
|
Does the same as gtk_container_set_border_width().
|
|
</para>
|
|
|
|
@Deprecated: Use gtk_container_set_border_width() instead.
|
|
|
|
|
|
<!-- ##### 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:
|
|
|
|
|
|
<!-- ##### MACRO gtk_container_children ##### -->
|
|
<para>
|
|
Does the same as gtk_container_get_children().
|
|
</para>
|
|
|
|
@Deprecated: Use gtk_container_get_children() instead.
|
|
|
|
|
|
<!-- ##### 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:
|
|
|
|
|