diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 4a4f0099d5..c53d003501 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,9 @@ +2003-06-30 Matthias Clasen + + * gtk/tmpl/gtkcontainer.sgml: Write a bit about size negotiation. + + * gtk/tmpl/gtkwidget.sgml: Some additions. + 2003-06-24 Matthias Clasen * gtk/gtk-docs.sgml: Move GtkIMContext to "Abstract Base Classes", since its abstract. diff --git a/docs/reference/gtk/tmpl/gtkcontainer.sgml b/docs/reference/gtk/tmpl/gtkcontainer.sgml index 78cafc9323..d8c13bf31a 100644 --- a/docs/reference/gtk/tmpl/gtkcontainer.sgml +++ b/docs/reference/gtk/tmpl/gtkcontainer.sgml @@ -5,7 +5,71 @@ 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. +This negotiation is carried out in two phases, size requisition and +size allocation. + +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_size_request(). 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. @@ -25,6 +89,7 @@ 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(). + diff --git a/docs/reference/gtk/tmpl/gtkwidget.sgml b/docs/reference/gtk/tmpl/gtkwidget.sgml index 2ffc19a178..32095a417b 100644 --- a/docs/reference/gtk/tmpl/gtkwidget.sgml +++ b/docs/reference/gtk/tmpl/gtkwidget.sgml @@ -313,7 +313,7 @@ Evaluates to %TRUE if the #GTK_APP_PAINTABLE flag has been set on the widget. Evaluates to %TRUE if the #GTK_DOUBLE_BUFFERED flag has been set on the widget. -@wid: +@wid: a #GtkWidget. @@ -336,30 +336,34 @@ Turns off certain widget flags. - +The type of the callback functions used for e.g. iterating over +the children of a container, see gtk_container_foreach(). -@widget: -@data: +@widget: the widget to operate on +@data: user-supplied data - +A GtkRequisition represents the desired size of a widget. See + for more information. -@width: -@height: +@width: the widget's desired width +@height: the widget's desired height - +A GtkAllocation of a widget represents region which has been allocated to the +widget by its parent. It is a subregion of its parents allocation. See + for more information. -@x: -@y: -@width: -@height: +@x: the X position of the widgets area relative to its parents allocation. +@y: the Y position of the widgets area relative to its parents allocation. +@width: the width of the widgets allocated area. +@height: the height of the widgets allocated area.