mirror of
https://gitlab.gnome.org/GNOME/gtk.git
synced 2024-10-01 03:27:36 +00:00
Migrated old GtkSizeRequestIface documentation to GtkWidget and added notes to gtk_widget_get_preferred_size().
This commit is contained in:
Tristan Van Berkom
parent
e9a7a2104b
commit
5a7cfa7fb9
@ -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)->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)->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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user