forked from AuroraMiddleware/gtk
Refer to GtkExtendedLayout from the container docs
This commit is contained in:
Matthias Clasen
parent
f285ed1348
commit
36c3eaea81
@ -6,100 +6,107 @@ 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
|
||||
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
|
||||
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
|
||||
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.
|
||||
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>.
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
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
|
||||
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
|
||||
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.
|
||||
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
|
||||
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
|
||||
<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
|
||||
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
|
||||
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
|
||||
gtk_container_child_get_valist(). To emit notification about child property
|
||||
changes, use gtk_widget_child_notify().
|
||||
</para>
|
||||
</refsect2>
|
||||
@ -107,7 +114,7 @@ changes, use gtk_widget_child_notify().
|
||||
<refsect2 id="GtkContainer-BUILDER-UI">
|
||||
<title>GtkContainer as GtkBuildable</title>
|
||||
<para>
|
||||
The GtkContainer implementation of the GtkBuildable interface
|
||||
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.
|
||||
@ -152,7 +159,7 @@ for regular properties.
|
||||
</para>
|
||||
|
||||
@container: the object which received the signal.
|
||||
@widget:
|
||||
@widget:
|
||||
|
||||
<!-- ##### SIGNAL GtkContainer::check-resize ##### -->
|
||||
<para>
|
||||
@ -167,7 +174,7 @@ for regular properties.
|
||||
</para>
|
||||
|
||||
@container: the object which received the signal.
|
||||
@widget:
|
||||
@widget:
|
||||
|
||||
<!-- ##### SIGNAL GtkContainer::set-focus-child ##### -->
|
||||
<para>
|
||||
@ -175,7 +182,7 @@ for regular properties.
|
||||
</para>
|
||||
|
||||
@container: the object which received the signal.
|
||||
@widget:
|
||||
@widget:
|
||||
|
||||
<!-- ##### ARG GtkContainer:border-width ##### -->
|
||||
<para>
|
||||
@ -197,7 +204,7 @@ for regular properties.
|
||||
|
||||
</para>
|
||||
|
||||
@widget:
|
||||
@widget:
|
||||
|
||||
|
||||
<!-- ##### MACRO GTK_CONTAINER_WARN_INVALID_CHILD_PROPERTY_ID ##### -->
|
||||
@ -206,7 +213,7 @@ 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()
|
||||
@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
|
||||
@ -225,8 +232,8 @@ Does the same as gtk_container_set_border_width().
|
||||
|
||||
</para>
|
||||
|
||||
@container:
|
||||
@widget:
|
||||
@container:
|
||||
@widget:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_container_remove ##### -->
|
||||
@ -234,8 +241,8 @@ Does the same as gtk_container_set_border_width().
|
||||
|
||||
</para>
|
||||
|
||||
@container:
|
||||
@widget:
|
||||
@container:
|
||||
@widget:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_container_add_with_properties ##### -->
|
||||
@ -243,10 +250,10 @@ Does the same as gtk_container_set_border_width().
|
||||
|
||||
</para>
|
||||
|
||||
@container:
|
||||
@widget:
|
||||
@first_prop_name:
|
||||
@Varargs:
|
||||
@container:
|
||||
@widget:
|
||||
@first_prop_name:
|
||||
@Varargs:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_container_get_resize_mode ##### -->
|
||||
@ -254,8 +261,8 @@ Does the same as gtk_container_set_border_width().
|
||||
|
||||
</para>
|
||||
|
||||
@container:
|
||||
@Returns:
|
||||
@container:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_container_set_resize_mode ##### -->
|
||||
@ -263,8 +270,8 @@ Does the same as gtk_container_set_border_width().
|
||||
|
||||
</para>
|
||||
|
||||
@container:
|
||||
@resize_mode:
|
||||
@container:
|
||||
@resize_mode:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_container_check_resize ##### -->
|
||||
@ -272,7 +279,7 @@ Does the same as gtk_container_set_border_width().
|
||||
|
||||
</para>
|
||||
|
||||
@container:
|
||||
@container:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_container_foreach ##### -->
|
||||
@ -280,9 +287,9 @@ Does the same as gtk_container_set_border_width().
|
||||
|
||||
</para>
|
||||
|
||||
@container:
|
||||
@callback:
|
||||
@callback_data:
|
||||
@container:
|
||||
@callback:
|
||||
@callback_data:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_container_foreach_full ##### -->
|
||||
@ -290,11 +297,11 @@ Does the same as gtk_container_set_border_width().
|
||||
|
||||
</para>
|
||||
|
||||
@container:
|
||||
@callback:
|
||||
@marshal:
|
||||
@callback_data:
|
||||
@notify:
|
||||
@container:
|
||||
@callback:
|
||||
@marshal:
|
||||
@callback_data:
|
||||
@notify:
|
||||
@Deprecated: Use gtk_container_foreach() instead.
|
||||
|
||||
|
||||
@ -311,8 +318,8 @@ Does the same as gtk_container_get_children().
|
||||
|
||||
</para>
|
||||
|
||||
@container:
|
||||
@Returns:
|
||||
@container:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_container_set_reallocate_redraws ##### -->
|
||||
@ -320,8 +327,8 @@ Does the same as gtk_container_get_children().
|
||||
|
||||
</para>
|
||||
|
||||
@container:
|
||||
@needs_redraws:
|
||||
@container:
|
||||
@needs_redraws:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_container_get_focus_child ##### -->
|
||||
@ -329,8 +336,8 @@ Does the same as gtk_container_get_children().
|
||||
|
||||
</para>
|
||||
|
||||
@container:
|
||||
@Returns:
|
||||
@container:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_container_set_focus_child ##### -->
|
||||
@ -338,8 +345,8 @@ Does the same as gtk_container_get_children().
|
||||
|
||||
</para>
|
||||
|
||||
@container:
|
||||
@child:
|
||||
@container:
|
||||
@child:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_container_get_focus_vadjustment ##### -->
|
||||
@ -347,8 +354,8 @@ Does the same as gtk_container_get_children().
|
||||
|
||||
</para>
|
||||
|
||||
@container:
|
||||
@Returns:
|
||||
@container:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_container_set_focus_vadjustment ##### -->
|
||||
@ -356,8 +363,8 @@ Does the same as gtk_container_get_children().
|
||||
|
||||
</para>
|
||||
|
||||
@container:
|
||||
@adjustment:
|
||||
@container:
|
||||
@adjustment:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_container_get_focus_hadjustment ##### -->
|
||||
@ -365,8 +372,8 @@ Does the same as gtk_container_get_children().
|
||||
|
||||
</para>
|
||||
|
||||
@container:
|
||||
@Returns:
|
||||
@container:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_container_set_focus_hadjustment ##### -->
|
||||
@ -374,8 +381,8 @@ Does the same as gtk_container_get_children().
|
||||
|
||||
</para>
|
||||
|
||||
@container:
|
||||
@adjustment:
|
||||
@container:
|
||||
@adjustment:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_container_resize_children ##### -->
|
||||
@ -383,7 +390,7 @@ Does the same as gtk_container_get_children().
|
||||
|
||||
</para>
|
||||
|
||||
@container:
|
||||
@container:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_container_child_type ##### -->
|
||||
@ -391,8 +398,8 @@ Does the same as gtk_container_get_children().
|
||||
|
||||
</para>
|
||||
|
||||
@container:
|
||||
@Returns:
|
||||
@container:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_container_child_get ##### -->
|
||||
@ -400,10 +407,10 @@ Does the same as gtk_container_get_children().
|
||||
|
||||
</para>
|
||||
|
||||
@container:
|
||||
@child:
|
||||
@first_prop_name:
|
||||
@Varargs:
|
||||
@container:
|
||||
@child:
|
||||
@first_prop_name:
|
||||
@Varargs:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_container_child_set ##### -->
|
||||
@ -411,10 +418,10 @@ Does the same as gtk_container_get_children().
|
||||
|
||||
</para>
|
||||
|
||||
@container:
|
||||
@child:
|
||||
@first_prop_name:
|
||||
@Varargs:
|
||||
@container:
|
||||
@child:
|
||||
@first_prop_name:
|
||||
@Varargs:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_container_child_get_property ##### -->
|
||||
@ -422,10 +429,10 @@ Does the same as gtk_container_get_children().
|
||||
|
||||
</para>
|
||||
|
||||
@container:
|
||||
@child:
|
||||
@property_name:
|
||||
@value:
|
||||
@container:
|
||||
@child:
|
||||
@property_name:
|
||||
@value:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_container_child_set_property ##### -->
|
||||
@ -433,10 +440,10 @@ Does the same as gtk_container_get_children().
|
||||
|
||||
</para>
|
||||
|
||||
@container:
|
||||
@child:
|
||||
@property_name:
|
||||
@value:
|
||||
@container:
|
||||
@child:
|
||||
@property_name:
|
||||
@value:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_container_child_get_valist ##### -->
|
||||
@ -444,10 +451,10 @@ Does the same as gtk_container_get_children().
|
||||
|
||||
</para>
|
||||
|
||||
@container:
|
||||
@child:
|
||||
@first_property_name:
|
||||
@var_args:
|
||||
@container:
|
||||
@child:
|
||||
@first_property_name:
|
||||
@var_args:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_container_child_set_valist ##### -->
|
||||
@ -455,10 +462,10 @@ Does the same as gtk_container_get_children().
|
||||
|
||||
</para>
|
||||
|
||||
@container:
|
||||
@child:
|
||||
@first_property_name:
|
||||
@var_args:
|
||||
@container:
|
||||
@child:
|
||||
@first_property_name:
|
||||
@var_args:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_container_forall ##### -->
|
||||
@ -466,9 +473,9 @@ Does the same as gtk_container_get_children().
|
||||
|
||||
</para>
|
||||
|
||||
@container:
|
||||
@callback:
|
||||
@callback_data:
|
||||
@container:
|
||||
@callback:
|
||||
@callback_data:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_container_get_border_width ##### -->
|
||||
@ -476,8 +483,8 @@ Does the same as gtk_container_get_children().
|
||||
|
||||
</para>
|
||||
|
||||
@container:
|
||||
@Returns:
|
||||
@container:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_container_set_border_width ##### -->
|
||||
@ -485,8 +492,8 @@ Does the same as gtk_container_get_children().
|
||||
|
||||
</para>
|
||||
|
||||
@container:
|
||||
@border_width:
|
||||
@container:
|
||||
@border_width:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_container_propagate_expose ##### -->
|
||||
@ -494,9 +501,9 @@ Does the same as gtk_container_get_children().
|
||||
|
||||
</para>
|
||||
|
||||
@container:
|
||||
@child:
|
||||
@event:
|
||||
@container:
|
||||
@child:
|
||||
@event:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_container_get_focus_chain ##### -->
|
||||
@ -504,9 +511,9 @@ Does the same as gtk_container_get_children().
|
||||
|
||||
</para>
|
||||
|
||||
@container:
|
||||
@focusable_widgets:
|
||||
@Returns:
|
||||
@container:
|
||||
@focusable_widgets:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_container_set_focus_chain ##### -->
|
||||
@ -514,8 +521,8 @@ Does the same as gtk_container_get_children().
|
||||
|
||||
</para>
|
||||
|
||||
@container:
|
||||
@focusable_widgets:
|
||||
@container:
|
||||
@focusable_widgets:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_container_unset_focus_chain ##### -->
|
||||
@ -523,7 +530,7 @@ Does the same as gtk_container_get_children().
|
||||
|
||||
</para>
|
||||
|
||||
@container:
|
||||
@container:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_container_class_find_child_property ##### -->
|
||||
@ -531,9 +538,9 @@ Does the same as gtk_container_get_children().
|
||||
|
||||
</para>
|
||||
|
||||
@cclass:
|
||||
@property_name:
|
||||
@Returns:
|
||||
@cclass:
|
||||
@property_name:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_container_class_install_child_property ##### -->
|
||||
@ -541,9 +548,9 @@ Does the same as gtk_container_get_children().
|
||||
|
||||
</para>
|
||||
|
||||
@cclass:
|
||||
@property_id:
|
||||
@pspec:
|
||||
@cclass:
|
||||
@property_id:
|
||||
@pspec:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_container_class_list_child_properties ##### -->
|
||||
@ -551,8 +558,8 @@ Does the same as gtk_container_get_children().
|
||||
|
||||
</para>
|
||||
|
||||
@cclass:
|
||||
@n_properties:
|
||||
@Returns:
|
||||
@cclass:
|
||||
@n_properties:
|
||||
@Returns:
|
||||
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user