Commit 5a7cfa7f authored by Tristan Van Berkom's avatar Tristan Van Berkom

Migrated old GtkSizeRequestIface documentation to GtkWidget and added notes to...

Migrated old GtkSizeRequestIface documentation to GtkWidget and added notes to gtk_widget_get_preferred_size().
parent e9a7a210
......@@ -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 <link linkend="size-allocation">size-allocation</link>
* 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.
*
* <refsect2>
* <title>Implementing GtkWidget</title>
* <para>
* 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:
* <example>
* <title>Widget calling its own size request method.</title>
* <programlisting>
* GTK_WIDGET_GET_CLASS(widget)-&gt;get_preferred_width (widget), &min, &natural);
* </programlisting>
* </example>
*
* 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
* <emphasis>another</emphasis> widget, such as a child of a
* container, you <emphasis>must</emphasis> use the wrapper APIs;
* otherwise, you would not properly consider widget margins,
* #GtkSizeGroup, and so forth.
* </para>
* </refsect2>
*/
#include <config.h>
#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.
*
* <note><para>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.</para></note>
*
* Since: 3.0
*/
......
......@@ -68,6 +68,94 @@
* GtkWidget is the base class all widgets in GTK+ derive from. It manages the
* widget lifecycle, states and style.
*
* <refsect2>
* <title>Height-for-width Geometry Management</title>
* <para>
* 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 <link linkend="size-allocation">size-allocation</link>
* 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:
* <example>
* <title>Widget calling its own size request method.</title>
* <programlisting>
* GTK_WIDGET_GET_CLASS(widget)-&gt;get_preferred_width (widget), &min, &natural);
* </programlisting>
* </example>
*
* 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
* <emphasis>another</emphasis> widget, such as a child of a
* container, you <emphasis>must</emphasis> use the wrapper APIs;
* otherwise, you would not properly consider widget margins,
* #GtkSizeGroup, and so forth.
* </para>
* </refsect2>
* <refsect2 id="style-properties">
* <para>
* <structname>GtkWidget</structname> introduces <firstterm>style
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment