Remove a (now) misleading comment.

[~andy/gtk] / docs / reference / gtk / tmpl / gtkbox.sgml

<!-- ##### SECTION Title ##### -->
GtkBox

<!-- ##### SECTION Short_Description ##### -->
a base class for box containers

<!-- ##### SECTION Long_Description ##### -->
<para>\r
GtkBox is an abstract widget which encapsulates functionallity for a\r
particular kind of container, one that organizes a variable number of\r
widgets into a rectangular area.  GtkBox currently has two derived\r
classes, #GtkHBox and #GtkVBox.\r
</para>\r
<para>\r
The rectangular area of a GtkBox is organized into either a single row\r
or a single column of child widgets depending upon whether the box is\r
of type #GtkHBox or #GtkVBox, respectively.  Thus, all children of a\r
GtkBox are allocated one dimension in common, which is the height of a\r
row, or the width of a column.\r
</para>\r
<para>\r
GtkBox uses a notion of <emphasis>packing</emphasis>.  Packing refers to\r
adding widgets with reference to a particular position in a\r
#GtkContainer.  For a GtkBox, there are two reference positions: the\r
<emphasis>start</emphasis> and the <emphasis>end</emphasis> of the box.  For a\r
#GtkVBox, the start is defined as the top of the box and the end is\r
defined as the bottom.  For a #GtkHBox the start is defined as the\r
left side and the end is defined as the right side.\r
</para>\r
<para>\r
Use repeated calls to gtk_box_pack_start() to pack widgets into a\r
GtkBox from start to end.  Use gtk_box_pack_end() to add widgets from\r
end to start.  You may intersperse these calls and add widgets from\r
both ends of the same GtkBox.\r
</para>\r
<para>\r
Use gtk_box_pack_start_defaults() or gtk_box_pack_end_defaults()\r
to pack widgets into a GtkBox if you do not need to specify the\r
<structfield>expand</structfield>, <structfield>fill</structfield>, or\r
<structfield>padding</structfield> attributes of the child to be\r
added.\r
</para>\r
<para>\r
Because GtkBox is a #GtkContainer, you may also use\r
gtk_container_add() to insert widgets into the box, and they will be\r
packed as if with gtk_box_pack_start_defaults().  Use\r
gtk_container_remove() to remove widgets from the GtkBox.\r
</para>\r
<para>\r
Use gtk_box_set_homogeneous() to specify whether or not all children\r
of the GtkBox are forced to get the same amount of space.\r
</para>\r
<para>\r
Use gtk_box_set_spacing() to determine how much space will be\r
minimally placed between all children in the GtkBox.\r
</para>\r
<para>\r
Use gtk_box_reorder_child() to move a GtkBox child to a different\r
place in the box.\r
</para>\r
<para>\r
Use gtk_box_set_child_packing() to reset the\r
<structfield>expand</structfield>, <structfield>fill</structfield>,\r
and <structfield>padding</structfield> attributes of any GtkBox child.\r
Use gtk_box_query_child_packing() to query these fields.\r
</para>

<!-- ##### SECTION See_Also ##### -->
<para>\r
<variablelist>\r
\r
<varlistentry>\r
<term>#GtkHBox</term>\r
<listitem><para>a derived class that organizes widgets into a row.</para></listitem>\r
</varlistentry>\r
\r
<varlistentry>\r
<term>#GtkVBox</term>\r
<listitem><para>a derived class that organizes widgets into a column.</para></listitem>\r
</varlistentry>\r
\r
<varlistentry>\r
<term>#GtkFrame</term>\r
<listitem><para>a #GtkWidget useful for drawing a border around a GtkBox.</para></listitem>\r
</varlistentry>\r
\r
<varlistentry>\r
<term>#GtkTable</term>\r
<listitem><para>a #GtkContainer for organizing widgets into a grid,\r
rather than independent rows or columns.</para></listitem>\r
</varlistentry>\r
\r
<varlistentry>\r
<term>#GtkLayout</term>\r
<listitem><para>a #GtkContainer for organizing widgets into arbitrary\r
layouts.</para></listitem>\r
</varlistentry>\r
\r
</variablelist>\r
\r
</para>

<!-- ##### STRUCT GtkBox ##### -->
<para>\r
The #GtkBox-struct describes an instance of GtkBox and contains the following fields.\r
(These fields should be considered read-only. They should never be set by\r
an application.)\r
\r
<informaltable pgwide=1 frame="none" role="struct">\r
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">\r
<tbody>\r
\r
<row>\r
<entry>#GList * <structfield>children</structfield>;</entry>\r
<entry>a list of children belonging the GtkBox.  The data is a list of\r
structures of type #GtkBoxChild-struct.</entry>\r
</row>\r
\r
<row>\r
<entry>#gint16 <structfield>spacing</structfield>;</entry>\r
<entry>the number of pixels to put between children of the GtkBox, zero\r
by default.  Use gtk_box_set_spacing() to set this field.</entry>\r
</row>\r
\r
<row>\r
<entry>#guint <structfield>homogeneous</structfield>;</entry>\r
<entry>a flag that if %TRUE forces all children to get equal space in\r
the GtkBox; %FALSE by default.  Use gtk_box_set_homogeneous() to set this\r
field.</entry>\r
</row>\r
</tbody></tgroup></informaltable>
</para>


<!-- ##### STRUCT GtkBoxChild ##### -->
<para>\r
The #GtkBoxChild-struct holds a child widget of GtkBox and describes\r
how the child is to be packed into the GtkBox.  Use\r
gtk_box_query_child_packing() and gtk_box_set_child_packing() to query\r
and reset the <structfield>padding</structfield>,\r
<structfield>expand</structfield>, <structfield>fill</structfield>,\r
and <structfield>pack</structfield> fields.\r
</para>\r
<para>\r
#GtkBoxChild-struct contains the following fields.  (These fields\r
should be considered read-only. They should never be directly set by an\r
application.)\r
\r
<informaltable pgwide=1 frame="none" role="struct">\r
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">\r
<tbody>\r
\r
<row>\r
<entry>#GtkWidget * <structfield>widget</structfield>;</entry>\r
<entry>the child widget, packed into the GtkBox.</entry>\r
</row>\r
\r
<row>\r
<entry>#guint16 <structfield>padding</structfield>;</entry>\r
<entry>the number of extra pixels to put between this child and its\r
neighbors, set when packed, zero by default.</entry>\r
</row>\r
\r
<row>\r
<entry>#guint <structfield>expand</structfield>;</entry>\r
<entry>flag indicates whether extra space should be given to this\r
child.  Any extra space given to the parent GtkBox is divided up among\r
all children with this attribute set to %TRUE; set when packed, %TRUE by\r
default.</entry>\r
</row>\r
\r
<row>\r
<entry>#guint <structfield>fill</structfield>;</entry>\r
<entry>flag indicates whether any extra space given to this child due to its\r
<structfield>expand</structfield> attribute being set is actually\r
allocated to the child, rather than being used as padding\r
around the widget; set when packed, %TRUE by default.</entry>\r
</row>\r
\r
<row>\r
<entry>#guint <structfield>pack</structfield>;</entry> <entry>one of\r
#GtkPackType indicating whether the child is packed with reference to\r
the start (top/left) or end (bottom/right) of the GtkBox.</entry>\r
</row>\r
</tbody></tgroup></informaltable>\r
</para>

@widget: 
@padding: 
@expand: 
@fill: 
@pack: 
@is_secondary: 

<!-- ##### FUNCTION gtk_box_pack_start ##### -->
<para>\r
Adds @child to @box, packed with reference to the start of @box.  The\r
@child is packed after any other child packed with reference to the\r
start of @box.\r
</para>

@box: a #GtkBox.
@child: the #GtkWidget to be added to @box.
@expand: %TRUE if the new child is to be given extra space allocated to\r
@box.  The extra space will be divided evenly between all children of\r
@box that use this option.
@fill: %TRUE if space given to @child by the @expand option is\r
actually allocated to @child, rather than just padding it.  This\r
parameter has no effect if @expand is set to %FALSE.  A child is\r
always allocated the full height of a #GtkHBox and the full width of a\r
#GtkVBox.  This option affects the other dimension.
@padding: extra space in pixels to put between this child and its\r
neighbors, over and above the global amount specified by\r
<structfield>spacing</structfield> in #GtkBox-struct.  If @child is a\r
widget at one of the reference ends of @box, then @padding pixels are also put\r
between @child and the reference edge of @box.


<!-- ##### FUNCTION gtk_box_pack_end ##### -->
<para>\r
Adds @child to @box, packed with reference to the end of @box.  The\r
@child is packed after (away from end of) any other child packed with reference to the\r
end of @box.\r
</para>

@box: a #GtkBox.
@child: the #GtkWidget to be added to @box.
@expand: %TRUE if the new child is to be given extra space allocated to\r
@box.  The extra space will be divided evenly between all children of\r
@box that use this option.
@fill: %TRUE if space given to @child by the @expand option is\r
actually allocated to @child, rather than just padding it.  This\r
parameter has no effect if @expand is set to %FALSE.  A child is\r
always allocated the full height of a #GtkHBox and the full width of a\r
#GtkVBox.  This option affects the other dimension.
@padding: extra space in pixels to put between this child and its\r
neighbors, over and above the global amount specified by\r
<structfield>spacing</structfield> in #GtkBox-struct.  If @child is a\r
widget at one of the reference ends of @box, then @padding pixels are also put\r
between @child and the reference edge of @box.


<!-- ##### FUNCTION gtk_box_pack_start_defaults ##### -->
<para>\r
Adds @widget to @box, packed with reference to the start of @box.  The\r
child is packed after any other child packed with reference to the\r
start of @box.\r
</para>\r
<para>\r
Parameters for how to pack the child @widget,\r
<structfield>expand</structfield>, <structfield>fill</structfield>,\r
and <structfield>padding</structfield> in #GtkBoxChild-struct, are given their default\r
values, %TRUE, %TRUE, and 0, respectively.\r
</para>

@box: a #GtkBox.
@widget: the #GtkWidget to be added to @box.


<!-- ##### FUNCTION gtk_box_pack_end_defaults ##### -->
<para>\r
Adds @widget to @box, packed with reference to the end of @box.  The\r
child is packed after (away from end of) any other child packed with\r
reference to the end of @box.\r
</para>\r
<para>\r
Parameters for how to pack the child @widget,\r
<structfield>expand</structfield>, <structfield>fill</structfield>,\r
and <structfield>padding</structfield> in #GtkBoxChild-struct, are given their default\r
values, %TRUE, %TRUE, and 0, respectively.\r
</para>

@box: a #GtkBox.
@widget: the #GtkWidget to be added to @box.


<!-- ##### FUNCTION gtk_box_get_homogeneous ##### -->
<para>

</para>

@box: 
@Returns: 


<!-- ##### FUNCTION gtk_box_set_homogeneous ##### -->
<para>\r
Sets the <structfield>homogeneous</structfield> field of\r
#GtkBox-struct, controlling whether or not all children of @box are\r
given equal space in the box.\r
</para>

@box: a #GtkBox.
@homogeneous: a boolean value, %TRUE to create equal allotments,\r
%FALSE for variable allotments.


<!-- ##### FUNCTION gtk_box_get_spacing ##### -->
<para>

</para>

@box: 
@Returns: 


<!-- ##### FUNCTION gtk_box_set_spacing ##### -->
<para>\r
Sets the <structfield>spacing</structfield> field of #GtkBox-struct,\r
which is the number of pixels to place between children of @box.\r
</para>

@box: a #GtkBox.
@spacing: the number of pixels to put between children.


<!-- ##### FUNCTION gtk_box_reorder_child ##### -->
<para>\r
Moves @child to a new @position in the list of @box children.  The\r
list is the <structfield>children</structfield> field of\r
#GtkBox-struct, and contains both widgets packed #GTK_PACK_START as\r
well as widgets packed #GTK_PACK_END, in the order that these widgets\r
were added to @box.\r
</para>\r
<para>\r
A widget's position in the @box children list determines where the\r
widget is packed into @box.  A child widget at some position in the\r
list will be packed just after all other widgets of the same packing\r
type that appear earlier in the list.  A negative value of @position is\r
interpreted as position 0.\r
</para>

@box: a #GtkBox.
@child: the #GtkWidget to move.
@position: the new position for @child in the\r
<structfield>children</structfield> list of #GtkBox-struct, starting\r
from 0.


<!-- ##### FUNCTION gtk_box_query_child_packing ##### -->
<para>\r
Returns information about how @child is packed into @box.\r
</para>

@box: a #GtkBox.
@child: the #GtkWidget of the child to query.
@expand: the returned value of the <structfield>expand</structfield>\r
field in #GtkBoxChild-struct.
@fill: the returned value of the <structfield>fill</structfield> field\r
in #GtkBoxChild-struct.
@padding: the returned value of the <structfield>padding</structfield>\r
field in #GtkBoxChild-struct.
@pack_type: the returned value of the <structfield>pack</structfield>\r
field in #GtkBoxChild-struct.


<!-- ##### FUNCTION gtk_box_set_child_packing ##### -->
<para>\r
Sets the way @child is packed into @box.\r
</para>

@box: a #GtkBox.
@child: the #GtkWidget of the child to set.
@expand: the new value of the <structfield>expand</structfield> field\r
in #GtkBoxChild-struct.
@fill: the new value of the <structfield>fill</structfield> field in\r
#GtkBoxChild-struct.
@padding: the new value of the <structfield>padding</structfield>\r
field in #GtkBoxChild-struct.
@pack_type: the new value of the <structfield>pack</structfield> field\r
in #GtkBoxChild-struct.


<!-- ##### ARG GtkBox:spacing ##### -->
<para>\r
the minimum amount of space to put between children.  Refers to the\r
<structfield>spacing</structfield> field of #GtkBox-struct.\r
</para>

<!-- ##### ARG GtkBox:homogeneous ##### -->
<para>\r
how to allocate space for children, equally or variably.  Refers to\r
the <structfield>homogeneous</structfield> field of #GtkBox-struct.\r
</para>