diff --git a/gtk/gtksizerequest.c b/gtk/gtksizerequest.c index f24140be5d..a30b2418e0 100644 --- a/gtk/gtksizerequest.c +++ b/gtk/gtksizerequest.c @@ -21,104 +21,6 @@ * Boston, MA 02111-1307, USA. */ - -/** - * SECTION:gtksizerequest - * @Short_Description: Height-for-width geometry management - * @Title: GtkWidget - * - * The GtkWidget interface is GTK+'s 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). - * The most common example is a label that reflows to fill up the available - * width, wraps to fewer lines, and therefore needs less height. - * - * GTK+'s traditional two-pass size-allocation - * algorithm does not allow this flexibility. #GtkWidget provides a default - * implementation of the #GtkWidget interface for existing widgets, - * which always requests the same height, regardless of the available width. - * - * - * Implementing GtkWidget - * - * Some important things to keep in mind when implementing - * the GtkWidget interface and when using it in container - * implementations. - * - * The geometry management system will query a logical hierarchy in - * only one orientation at a time. When widgets are initially queried - * for their minimum sizes it is generally done in a dual pass - * in the direction chosen by the toplevel. - * - * For instance when queried in the normal height-for-width mode: - * First the default minimum and natural width for each widget - * in the interface will computed and collectively returned to - * the toplevel by way of gtk_widget_get_preferred_width(). - * Next, the toplevel will use the minimum width to query for the - * minimum height contextual to that width using - * gtk_widget_get_preferred_height_for_width(), which will also - * be a highly recursive operation. This minimum-for-minimum size can - * be used to set the minimum size constraint on the toplevel. - * - * When allocating, each container can use the minimum and natural - * sizes reported by their children to allocate natural sizes and - * expose as much content as possible with the given allocation. - * - * That means that the request operation at allocation time will - * usually fire again in contexts of different allocated sizes than - * the ones originally queried for. #GtkWidget caches a - * small number of results to avoid re-querying for the same - * allocated size in one allocation cycle. - * - * A widget that does not actually do height-for-width - * or width-for-height size negotiations only has to implement - * get_preferred_width() and get_preferred_height(). - * - * If a widget does move content around to smartly use up the - * allocated size, then it must support the request properly in - * both orientations; even if the request only makes sense in - * one orientation. - * - * For instance, a GtkLabel that does height-for-width word wrapping - * will not expect to have get_preferred_height() called because that - * call is specific to a width-for-height request, in this case the - * label must return the heights contextual to its minimum possible - * width. By following this rule any widget that handles height-for-width - * or width-for-height requests will always be allocated at least - * enough space to fit its own content. - * - * Often a widget needs to get its own request during size request or - * allocation, for example when computing height it may need to also - * compute width, or when deciding how to use an allocation the widget may - * need to know its natural size. In these cases, the widget should be - * careful to call its virtual methods directly, like this: - * - * Widget calling its own size request method. - * - * GTK_WIDGET_GET_CLASS(widget)->get_preferred_width (widget), &min, &natural); - * - * - * - * It will not work to use the wrapper functions, such as - * gtk_widget_get_preferred_width(), inside your own size request - * implementation. These return a request adjusted by #GtkSizeGroup - * and by the GtkWidgetClass::adjust_size_request virtual method. If a - * widget used the wrappers inside its virtual method implementations, - * then the adjustments (such as widget margins) would be applied - * twice. GTK+ therefore does not allow this and will warn if you try - * to do it. - * - * Of course if you are getting the size request for - * another widget, such as a child of a - * container, you must use the wrapper APIs; - * otherwise, you would not properly consider widget margins, - * #GtkSizeGroup, and so forth. - * - * - */ - - #include #include "gtksizerequest.h" #include "gtksizegroup.h" @@ -579,7 +481,14 @@ gtk_widget_get_preferred_height_for_width (GtkWidget *widget, * into account the widget's preference for height-for-width management. * * This is used to retrieve a suitable size by container widgets which do - * not impose any restrictions on the child placement. + * not impose any restrictions on the child placement. It can be used + * to deduce toplevel window and menu sizes as well as child widgets in + * free form containers such as GtkLayout. + * + * Handle with care, note that the natural height of a height-for-width + * widget will generally be a smaller size than the minimum height, since the required + * height for the natural width is generally smaller than the required height for + * the minimum width. * * Since: 3.0 */ diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c index 0acf8eae4b..dc3c1a3828 100644 --- a/gtk/gtkwidget.c +++ b/gtk/gtkwidget.c @@ -68,6 +68,94 @@ * 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. + * 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). The most common example is a label that reflows to fill up the + * available width, wraps to fewer lines, and therefore needs less height. + * + * GTK+'s traditional two-pass size-allocation + * algorithm does not allow this flexibility. #GtkWidget provides a default + * implementation of the height-for-width methods for existing widgets, + * which always requests the same height, regardless of the available width. + * + * Some important things to keep in mind when implementing + * height-for-width and when using it in container + * implementations. + * + * The geometry management system will query a logical hierarchy in + * only one orientation at a time. When widgets are initially queried + * for their minimum sizes it is generally done in a dual pass + * in the direction chosen by the toplevel. + * + * For instance when queried in the normal height-for-width mode: + * First the default minimum and natural width for each widget + * in the interface will computed and collectively returned to + * the toplevel by way of gtk_widget_get_preferred_width(). + * Next, the toplevel will use the minimum width to query for the + * minimum height contextual to that width using + * gtk_widget_get_preferred_height_for_width(), which will also + * be a highly recursive operation. This minimum-for-minimum size can + * be used to set the minimum size constraint on the toplevel. + * + * When allocating, each container can use the minimum and natural + * sizes reported by their children to allocate natural sizes and + * expose as much content as possible with the given allocation. + * + * That means that the request operation at allocation time will + * usually fire again in contexts of different allocated sizes than + * the ones originally queried for. #GtkWidget caches a + * small number of results to avoid re-querying for the same + * allocated size in one allocation cycle. + * + * A widget that does not actually do height-for-width + * or width-for-height size negotiations only has to implement + * get_preferred_width() and get_preferred_height(). + * + * If a widget does move content around to smartly use up the + * allocated size, then it must support the request properly in + * both orientations; even if the request only makes sense in + * one orientation. + * + * For instance, a GtkLabel that does height-for-width word wrapping + * will not expect to have get_preferred_height() called because that + * call is specific to a width-for-height request. In this case the + * label must return the heights contextual to its minimum possible + * width. By following this rule any widget that handles height-for-width + * or width-for-height requests will always be allocated at least + * enough space to fit its own content. + * + * Often a widget needs to get its own request during size request or + * allocation, for example when computing height it may need to also + * compute width, or when deciding how to use an allocation the widget may + * need to know its natural size. In these cases, the widget should be + * careful to call its virtual methods directly, like this: + * + * Widget calling its own size request method. + * + * GTK_WIDGET_GET_CLASS(widget)->get_preferred_width (widget), &min, &natural); + * + * + * + * It will not work to use the wrapper functions, such as + * gtk_widget_get_preferred_width(), inside your own size request + * implementation. These return a request adjusted by #GtkSizeGroup + * and by the GtkWidgetClass::adjust_size_request virtual method. If a + * widget used the wrappers inside its virtual method implementations, + * then the adjustments (such as widget margins) would be applied + * twice. GTK+ therefore does not allow this and will warn if you try + * to do it. + * + * Of course if you are getting the size request for + * another widget, such as a child of a + * container, you must use the wrapper APIs; + * otherwise, you would not properly consider widget margins, + * #GtkSizeGroup, and so forth. + * + * * * * GtkWidget introduces style