diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore index a9378ad349..14c568ae72 100644 --- a/docs/reference/gtk/tmpl/.gitignore +++ b/docs/reference/gtk/tmpl/.gitignore @@ -1,3 +1,4 @@ +gtkbox.sgml gtkhbox.sgml gtkmessagedialog.sgml gtktesting.sgml diff --git a/docs/reference/gtk/tmpl/gtkbox.sgml b/docs/reference/gtk/tmpl/gtkbox.sgml deleted file mode 100644 index eb42208d3a..0000000000 --- a/docs/reference/gtk/tmpl/gtkbox.sgml +++ /dev/null @@ -1,291 +0,0 @@ - -GtkBox - - -Base class for box containers - - - -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 packing. Packing refers to -adding widgets with reference to a particular position in a -#GtkContainer. For a GtkBox, there are two reference positions: the -start and the end 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. - - - - - - - -#GtkHBox -a derived class that organizes widgets into a row. - - - -#GtkVBox -a derived class that organizes widgets into a column. - - - -#GtkFrame -a #GtkWidget useful for drawing a border around a GtkBox. - - - -#GtkTable -a #GtkContainer for organizing widgets into a grid, -rather than independent rows or columns. - - - -#GtkLayout -a #GtkContainer for organizing widgets into arbitrary -layouts. - - - - - - - - - - - -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.) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -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 padding, -expand, fill, -and pack fields. - - -#GtkBoxChild-struct contains the following fields. (These fields -should be considered read-only. They should never be directly set by an -application.) - - -@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 - - - - - - -@box: -@child: -@expand: -@box -@fill: -@padding: - - - - - - - -@box: -@child: -@expand: -@fill: -@padding: - - - - - - - -@box: -@widget: - - - - - - - -@box: -@widget: - - - - - - - -@box: -@Returns: - - - - - - - -@box: -@homogeneous: - - - - - - - -@box: -@Returns: - - - - - - - -@box: -@spacing: - - - - - - - -@box: -@child: -@position: - - - - - - - -@box: -@child: -@expand: -@fill: -@padding: -@pack_type: - - - - - - - -@box: -@child: -@expand: -@fill: -@padding: -@pack_type: - - diff --git a/gtk/gtkbox.c b/gtk/gtkbox.c index 1ebcbcf8e4..d9356f53e7 100644 --- a/gtk/gtkbox.c +++ b/gtk/gtkbox.c @@ -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 packing. Packing refers to + * adding widgets with reference to a particular position in a + * #GtkContainer. For a GtkBox, there are two reference positions: the + * start and the end 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" diff --git a/gtk/gtkbox.h b/gtk/gtkbox.h index 914683b48e..038c3b1c3a 100644 --- a/gtk/gtkbox.h +++ b/gtk/gtkbox.h @@ -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;