forked from AuroraMiddleware/gtk
docs: Move documentation do inline comments: GtkContainer
This commit is contained in:
parent
cabc386252
commit
c2ab54a31f
1
docs/reference/gtk/tmpl/.gitignore
vendored
1
docs/reference/gtk/tmpl/.gitignore
vendored
@ -9,6 +9,7 @@ gtkcalendar.sgml
|
||||
gtkcelleditable.sgml
|
||||
gtkcombobox.sgml
|
||||
gtkcomboboxentry.sgml
|
||||
gtkcontainer.sgml
|
||||
gtkeditable.sgml
|
||||
gtkentrybuffer.sgml
|
||||
gtkhbox.sgml
|
||||
|
@ -1,539 +0,0 @@
|
||||
<!-- ##### 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:
|
||||
|
||||
|
@ -44,6 +44,90 @@
|
||||
#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;
|
||||
|
@ -188,6 +188,16 @@ void gtk_container_child_get_property (GtkContainer *container,
|
||||
const gchar *property_name,
|
||||
GValue *value);
|
||||
|
||||
/**
|
||||
* GTK_CONTAINER_WARN_INVALID_CHILD_PROPERTY_ID:
|
||||
* @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
|
||||
*
|
||||
* This macro should be used to emit a standard warning about unexpected
|
||||
* properties in set_child_property() and get_child_property() implementations.
|
||||
*/
|
||||
#define GTK_CONTAINER_WARN_INVALID_CHILD_PROPERTY_ID(object, property_id, pspec) \
|
||||
G_OBJECT_WARN_INVALID_PSPEC ((object), "child property id", (property_id), (pspec))
|
||||
|
||||
|
@ -68,7 +68,7 @@
|
||||
* GtkWidget is the base class all widgets in GTK+ derive from. It manages the
|
||||
* widget lifecycle, states and style.
|
||||
*
|
||||
* <refsect2>
|
||||
* <refsect2 id="geometry-management">
|
||||
* <title>Height-for-width Geometry Management</title>
|
||||
* <para>
|
||||
* GTK+ uses a height-for-width (and width-for-height) geometry management system.
|
||||
|
Loading…
Reference in New Issue
Block a user