forked from AuroraMiddleware/gtk
1a48dcb14f
Tue Feb 24 14:45:03 2004 Owen Taylor <otaylor@redhat.com>
* === Released 2.3.3 ===
* configure.in: Version 2.3.3, interface age 0.
* NEWS: Finish updates for 2.3.3.
513 lines
10 KiB
Plaintext
513 lines
10 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.
|
|
This negotiation is carried out in two phases, <firstterm>size requisition</firstterm> and
|
|
<firstterm>size allocation</firstterm>.
|
|
</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>
|
|
|
|
<!-- ##### SECTION See_Also ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### 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>
|
|
|
|
</para>
|
|
|
|
@object:
|
|
@property_id:
|
|
@pspec:
|
|
|
|
|
|
<!-- ##### MACRO gtk_container_border_width ##### -->
|
|
<para>
|
|
Does the same as gtk_container_get_border_width().
|
|
</para>
|
|
|
|
@Deprecated: Use gtk_container_get_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:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_container_foreach_full ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@container:
|
|
@callback:
|
|
@marshal:
|
|
@callback_data:
|
|
@notify:
|
|
@Deprecated: Use gtk_container_foreach() instead.
|
|
|
|
|
|
<!-- ##### MACRO gtk_container_children ##### -->
|
|
<para>
|
|
Does the same as gtk_container_get_children().
|
|
</para>
|
|
|
|
@Returns:
|
|
@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_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:
|
|
<!-- # Unused Parameters # -->
|
|
@first_arg_name:
|
|
|
|
|
|
<!-- ##### 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:
|
|
<!-- # Unused Parameters # -->
|
|
@class:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_container_class_install_child_property ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@cclass:
|
|
@property_id:
|
|
@pspec:
|
|
<!-- # Unused Parameters # -->
|
|
@class:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_container_class_list_child_properties ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@cclass:
|
|
@n_properties:
|
|
@Returns:
|
|
<!-- # Unused Parameters # -->
|
|
@class:
|
|
|
|
|