AuroraMiddleware/gtk2
1
0
Fork 0
forked from AuroraMiddleware/gtk
Code Issues Pull Requests Projects Releases Wiki Activity

Move documentation to inline comments: GtkBox

Browse Source 
Fixes https://bugzilla.gnome.org/show_bug.cgi?id=611742

Signed-off-by: Javier Jardón <jjardon@gnome.org>
This commit is contained in:
Tadej Borovšak 2010-03-09 23:51:03 +01:00 committed by Javier Jardón
parent fa3bb041eb
commit ef4e7b2473
4 changed files with 77 additions and 291 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/reference/gtk/tmpl/.gitignore vendored
View File

@ -1,3 +1,4 @@
gtkbox.sgml
gtkhbox.sgml
gtkmessagedialog.sgml
gtktesting.sgml

291
docs/reference/gtk/tmpl/gtkbox.sgml
View File

@ -1,291 +0,0 @@
<!-- ##### SECTION Title ##### -->
GtkBox
<!-- ##### SECTION Short_Description ##### -->
Base class for box containers
<!-- ##### SECTION Long_Description ##### -->
<para>
GtkBox is an abstract widget which encapsulates functionality for a
particular kind of container, one that organizes a variable number of
widgets into a rectangular area. GtkBox has a number of derived
classes, e.g. #GtkHBox and #GtkVBox.
</para>
<para>
The rectangular area of a GtkBox is organized into either a single row
or a single column of child widgets depending upon whether the box is
of type #GtkHBox or #GtkVBox, respectively. Thus, all children of a
GtkBox are allocated one dimension in common, which is the height of a
row, or the width of a column.
</para>
<para>
GtkBox uses a notion of <emphasis>packing</emphasis>. Packing refers to
adding widgets with reference to a particular position in a
#GtkContainer. For a GtkBox, there are two reference positions: the
<emphasis>start</emphasis> and the <emphasis>end</emphasis> of the box.
For a #GtkVBox, the start is defined as the top of the box and the end is
defined as the bottom. For a #GtkHBox the start is defined as the
left side and the end is defined as the right side.
</para>
<para>
Use repeated calls to gtk_box_pack_start() to pack widgets into a
GtkBox from start to end. Use gtk_box_pack_end() to add widgets from
end to start. You may intersperse these calls and add widgets from
both ends of the same GtkBox.
</para>
<para>
Use gtk_box_pack_start_defaults() or gtk_box_pack_end_defaults()
to pack widgets into a GtkBox if you do not need to specify the
#GtkBox:expand, #GtkBox:fill, or #GtkBox:padding child properties
for the child to be added.
</para>
<para>
Because GtkBox is a #GtkContainer, you may also use
gtk_container_add() to insert widgets into the box, and they will be
packed as if with gtk_box_pack_start_defaults(). Use
gtk_container_remove() to remove widgets from the GtkBox.
</para>
<para>
Use gtk_box_set_homogeneous() to specify whether or not all children
of the GtkBox are forced to get the same amount of space.
</para>
<para>
Use gtk_box_set_spacing() to determine how much space will be
minimally placed between all children in the GtkBox.
</para>
<para>
Use gtk_box_reorder_child() to move a GtkBox child to a different
place in the box.
</para>
<para>
Use gtk_box_set_child_packing() to reset the #GtkBox:expand,
#GtkBox:fill and #GtkBox:padding child properties.
Use gtk_box_query_child_packing() to query these fields.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
<variablelist>
<varlistentry>
<term>#GtkHBox</term>
<listitem><para>a derived class that organizes widgets into a row.</para></listitem>
</varlistentry>
<varlistentry>
<term>#GtkVBox</term>
<listitem><para>a derived class that organizes widgets into a column.</para></listitem>
</varlistentry>
<varlistentry>
<term>#GtkFrame</term>
<listitem><para>a #GtkWidget useful for drawing a border around a GtkBox.</para></listitem>
</varlistentry>
<varlistentry>
<term>#GtkTable</term>
<listitem><para>a #GtkContainer for organizing widgets into a grid,
rather than independent rows or columns.</para></listitem>
</varlistentry>
<varlistentry>
<term>#GtkLayout</term>
<listitem><para>a #GtkContainer for organizing widgets into arbitrary
layouts.</para></listitem>
</varlistentry>
</variablelist>
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### STRUCT GtkBox ##### -->
<para>
The #GtkBox-struct describes an instance of GtkBox and contains the
following fields. (These fields should be considered read-only.
They should never be set by an application.)
</para>
<!-- ##### ARG GtkBox:homogeneous ##### -->
<para>
</para>
<!-- ##### ARG GtkBox:spacing ##### -->
<para>
</para>
<!-- ##### ARG GtkBox:expand ##### -->
<para>
</para>
<!-- ##### ARG GtkBox:fill ##### -->
<para>
</para>
<!-- ##### ARG GtkBox:pack-type ##### -->
<para>
</para>
<!-- ##### ARG GtkBox:padding ##### -->
<para>
</para>
<!-- ##### ARG GtkBox:position ##### -->
<para>
</para>
<!-- ##### STRUCT GtkBoxChild ##### -->
<para>
The #GtkBoxChild-struct holds a child widget of GtkBox and describes
how the child is to be packed into the GtkBox. Use
gtk_box_query_child_packing() and gtk_box_set_child_packing() to query
and reset the <structfield>padding</structfield>,
<structfield>expand</structfield>, <structfield>fill</structfield>,
and <structfield>pack</structfield> fields.
</para>
<para>
#GtkBoxChild-struct contains the following fields. (These fields
should be considered read-only. They should never be directly set by an
application.)
</para>
@widget: the child widget, packed into the GtkBox.
@padding: the number of extra pixels to put between this child and its
neighbors, set when packed, zero by default.
@expand: flag indicates whether extra space should be given to this
child. Any extra space given to the parent GtkBox is divided up
among all children with this attribute set to %TRUE; set when packed,
%TRUE by default.
@fill: flag indicates whether any extra space given to this child due
to its @expand attribute being set is actually allocated to the child,
rather than being used as padding around the widget; set when packed,
%TRUE by default.
@pack: one of #GtkPackType indicating whether the child is packed with
reference to the start (top/left) or end (bottom/right) of the GtkBox.
@is_secondary: %TRUE if the child is secondary
<!-- ##### FUNCTION gtk_box_pack_start ##### -->
<para>
</para>
@box:
@child:
@expand:
@box
@fill:
@padding:
<!-- ##### FUNCTION gtk_box_pack_end ##### -->
<para>
</para>
@box:
@child:
@expand:
@fill:
@padding:
<!-- ##### FUNCTION gtk_box_pack_start_defaults ##### -->
<para>
</para>
@box:
@widget:
<!-- ##### FUNCTION gtk_box_pack_end_defaults ##### -->
<para>
</para>
@box:
@widget:
<!-- ##### FUNCTION gtk_box_get_homogeneous ##### -->
<para>
</para>
@box:
@Returns:
<!-- ##### FUNCTION gtk_box_set_homogeneous ##### -->
<para>
</para>
@box:
@homogeneous:
<!-- ##### FUNCTION gtk_box_get_spacing ##### -->
<para>
</para>
@box:
@Returns:
<!-- ##### FUNCTION gtk_box_set_spacing ##### -->
<para>
</para>
@box:
@spacing:
<!-- ##### FUNCTION gtk_box_reorder_child ##### -->
<para>
</para>
@box:
@child:
@position:
<!-- ##### FUNCTION gtk_box_query_child_packing ##### -->
<para>
</para>
@box:
@child:
@expand:
@fill:
@padding:
@pack_type:
<!-- ##### FUNCTION gtk_box_set_child_packing ##### -->
<para>
</para>
@box:
@child:
@expand:
@fill:
@padding:
@pack_type:

54
gtk/gtkbox.c
View File

@ -24,6 +24,60 @@
* GTK+ at ftp://ftp.gtk.org/pub/gtk/.
*/
/**
* SECTION:gtkbox
* @Short_description: Base class for box containers
* @Title: GtkBox
* @See_also:i #GtkHBox, #GtkVBox, #GtkFrame, #GtkTable, #GtkLayout
*
* GtkBox is an abstract widget which encapsulates functionality for a
* particular kind of container, one that organizes a variable number of
* widgets into a rectangular area. GtkBox has a number of derived
* classes, e.g. #GtkHBox and #GtkVBox.
*
* The rectangular area of a GtkBox is organized into either a single row
* or a single column of child widgets depending upon whether the box is
* of type #GtkHBox or #GtkVBox, respectively. Thus, all children of a
* GtkBox are allocated one dimension in common, which is the height of a
* row, or the width of a column.
*
* GtkBox uses a notion of <emphasis>packing</emphasis>. Packing refers to
* adding widgets with reference to a particular position in a
* #GtkContainer. For a GtkBox, there are two reference positions: the
* <emphasis>start</emphasis> and the <emphasis>end</emphasis> of the box.
* For a #GtkVBox, the start is defined as the top of the box and the end is
* defined as the bottom. For a #GtkHBox the start is defined as the
* left side and the end is defined as the right side.
*
* Use repeated calls to gtk_box_pack_start() to pack widgets into a
* GtkBox from start to end. Use gtk_box_pack_end() to add widgets from
* end to start. You may intersperse these calls and add widgets from
* both ends of the same GtkBox.
*
* Use gtk_box_pack_start_defaults() or gtk_box_pack_end_defaults()
* to pack widgets into a GtkBox if you do not need to specify the
* #GtkBox:expand, #GtkBox:fill, or #GtkBox:padding child properties
* for the child to be added.
*
* Because GtkBox is a #GtkContainer, you may also use
* gtk_container_add() to insert widgets into the box, and they will be
* packed as if with gtk_box_pack_start_defaults(). Use
* gtk_container_remove() to remove widgets from the GtkBox.
*
* Use gtk_box_set_homogeneous() to specify whether or not all children
* of the GtkBox are forced to get the same amount of space.
*
* Use gtk_box_set_spacing() to determine how much space will be
* minimally placed between all children in the GtkBox.
*
* Use gtk_box_reorder_child() to move a GtkBox child to a different
* place in the box.
*
* Use gtk_box_set_child_packing() to reset the #GtkBox:expand,
* #GtkBox:fill and #GtkBox:padding child properties.
* Use gtk_box_query_child_packing() to query these fields.
*/
#include "config.h"
#include "gtkbox.h"

22
gtk/gtkbox.h
View File

@ -65,6 +65,28 @@ struct _GtkBoxClass
GtkContainerClass parent_class;
};
/**
* GtkBoxChild:
* @widget: the child widget, packed into the GtkBox.
* @padding: the number of extra pixels to put between this child and its
* neighbors, set when packed, zero by default.
* @expand: flag indicates whether extra space should be given to this child.
* Any extra space given to the parent GtkBox is divided up among all children
* with this attribute set to %TRUE; set when packed, %TRUE by default.
* @fill: flag indicates whether any extra space given to this child due to its
* @expand attribute being set is actually allocated to the child, rather than
* being used as padding around the widget; set when packed, %TRUE by default.
* @pack: one of #GtkPackType indicating whether the child is packed with
* reference to the start (top/left) or end (bottom/right) of the GtkBox.
* @is_secondary: %TRUE if the child is secondary
*
* The #GtkBoxChild holds a child widget of #GtkBox and describes how the child
* is to be packed into the #GtkBox. All fields of this #GtkBoxChild should be
* considered read-only and they should never be set directly by an application.
* Use gtk_box_query_child_packing() and gtk_box_set_child_packing() to query
* and set the #GtkBoxChild.padding, #GtkBoxChild.expand, #GtkBoxChild.fill and
* #GtkBoxChild.pack fields.
*/
struct _GtkBoxChild
{
GtkWidget *widget;