diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore index f08a09ebef..3856389438 100644 --- a/docs/reference/gtk/tmpl/.gitignore +++ b/docs/reference/gtk/tmpl/.gitignore @@ -9,6 +9,7 @@ gtkcalendar.sgml gtkcelleditable.sgml gtkcombobox.sgml gtkcomboboxentry.sgml +gtkcontainer.sgml gtkeditable.sgml gtkentrybuffer.sgml gtkhbox.sgml diff --git a/docs/reference/gtk/tmpl/gtkcontainer.sgml b/docs/reference/gtk/tmpl/gtkcontainer.sgml deleted file mode 100644 index 69c5f6fca0..0000000000 --- a/docs/reference/gtk/tmpl/gtkcontainer.sgml +++ /dev/null @@ -1,539 +0,0 @@ - -GtkContainer - - -Base class for widgets which contain other widgets - - - -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 decorators, 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 layout. 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. - - -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, size requisition and -size allocation, which are implemented by the -size_request() and size_allocate() virtual functions in #GtkWidget. - - -GTK+ also supports a more complicated form of size negotiation called -width-for-height (and its dual -height-for-width). See #GtkExtendedLayout -to learn more about width-for-height geometry management. - -Size Requisition - -The size requisition of a widget is it's desired width and height. -This is represented by a #GtkRequisition. - - -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. - - -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. - - -Size Allocation - -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. - - -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. - - -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. - - -Child properties - -GtkContainer introduces child -properties - 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(). - - - - -GtkContainer as GtkBuildable - -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. - - -Child properties in UI definitions - - - - - start - - - -]]> - - -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. - - - - - - - - - - - - - - - - - - - - - - - - - -@container: the object which received the signal. -@widget: - - - - - - -@container: the object which received the signal. - - - - - - -@container: the object which received the signal. -@widget: - - - - - - -@container: the object which received the signal. -@widget: - - - - - - - - - - - - - - - - - - - - - -@widget: - - - - -This macro should be used to emit a standard warning about unexpected -properties in set_child_property() and get_child_property() implementations. - - -@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 - - - - - - - -@container: -@widget: - - - - - - - -@container: -@widget: - - - - - - - -@container: -@widget: -@first_prop_name: -@Varargs: - - - - - - - -@container: -@Returns: - - - - - - - -@container: -@resize_mode: - - - - - - - -@container: - - - - - - - -@container: -@callback: -@callback_data: - - - - - - - -@container: -@Returns: - - - - - - - -@container: -@needs_redraws: - - - - - - - -@container: -@Returns: - - - - - - - -@container: -@child: - - - - - - - -@container: -@Returns: - - - - - - - -@container: -@adjustment: - - - - - - - -@container: -@Returns: - - - - - - - -@container: -@adjustment: - - - - - - - -@container: - - - - - - - -@container: -@Returns: - - - - - - - -@container: -@child: -@first_prop_name: -@Varargs: - - - - - - - -@container: -@child: -@first_prop_name: -@Varargs: - - - - - - - -@container: -@child: -@property_name: -@value: - - - - - - - -@container: -@child: -@property_name: -@value: - - - - - - - -@container: -@child: -@first_property_name: -@var_args: - - - - - - - -@container: -@child: -@first_property_name: -@var_args: - - - - - - - -@container: -@callback: -@callback_data: - - - - - - - -@container: -@Returns: - - - - - - - -@container: -@border_width: - - - - - - - -@container: -@child: -@event: - - - - - - - -@container: -@focusable_widgets: -@Returns: - - - - - - - -@container: -@focusable_widgets: - - - - - - - -@container: - - - - - - - -@cclass: -@property_name: -@Returns: - - - - - - - -@cclass: -@property_id: -@pspec: - - - - - - - -@cclass: -@n_properties: -@Returns: - - diff --git a/gtk/gtkcontainer.c b/gtk/gtkcontainer.c index 055a2eaf38..845de34721 100644 --- a/gtk/gtkcontainer.c +++ b/gtk/gtkcontainer.c @@ -44,6 +44,90 @@ #include #include + +/** + * 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 decorators, 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 layout. 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 GtkWidget's geometry management section + * to learn more about height-for-width geometry management. + * + * Child properties + * + * GtkContainer introduces child properties. + * 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(). + * + * + * + * GtkContainer as GtkBuildable + * + * 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. + * + * Child properties in UI definitions + * + * + * + * + * start + * + * + * + * ]]> + * + * 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. + * + * + */ + + struct _GtkContainerPrivate { GtkWidget *focus_child; diff --git a/gtk/gtkcontainer.h b/gtk/gtkcontainer.h index 87429114e1..607baf6f7d 100644 --- a/gtk/gtkcontainer.h +++ b/gtk/gtkcontainer.h @@ -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)) diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c index 4ca6c4e2aa..e3acd78266 100644 --- a/gtk/gtkwidget.c +++ b/gtk/gtkwidget.c @@ -68,7 +68,7 @@ * GtkWidget is the base class all widgets in GTK+ derive from. It manages the * widget lifecycle, states and style. * - * + * * Height-for-width Geometry Management * * GTK+ uses a height-for-width (and width-for-height) geometry management system.