GtkExtendedLayout

GtkExtendedLayout — Height-for-width geometry management

Synopsis

#include <gtk/gtk.h>

                    GtkExtendedLayout;
                    GtkExtendedLayoutIface;
void                gtk_extended_layout_get_desired_height
                                                        (GtkExtendedLayout *layout,
                                                         gint *minimum_height,
                                                         gint *natural_height);
void                gtk_extended_layout_get_desired_size
                                                        (GtkExtendedLayout *layout,
                                                         gboolean request_natural,
                                                         GtkRequisition *minimum_size,
                                                         GtkRequisition *natural_size);
void                gtk_extended_layout_get_desired_width
                                                        (GtkExtendedLayout *layout,
                                                         gint *minimum_width,
                                                         gint *natural_width);
void                gtk_extended_layout_get_height_for_width
                                                        (GtkExtendedLayout *layout,
                                                         gint width,
                                                         gint *minimum_height,
                                                         gint *natural_height);
void                gtk_extended_layout_get_width_for_height
                                                        (GtkExtendedLayout *layout,
                                                         gint height,
                                                         gint *minimum_width,
                                                         gint *natural_width);
gboolean            gtk_extended_layout_is_height_for_width
                                                        (GtkExtendedLayout *layout);

Object Hierarchy

  GInterface
   +----GtkExtendedLayout

Prerequisites

GtkExtendedLayout requires GtkWidget.

Known Implementations

GtkExtendedLayout is implemented by GtkAboutDialog, GtkAccelLabel, GtkAlignment, GtkArrow, GtkAspectFrame, GtkAssistant, GtkBin, GtkBox, GtkButton, GtkButtonBox, GtkCalendar, GtkCellView, GtkCheckButton, GtkCheckMenuItem, GtkColorButton, GtkColorSelection, GtkColorSelectionDialog, GtkComboBox, GtkComboBoxEntry, GtkContainer, GtkDialog, GtkDrawingArea, GtkEntry, GtkEventBox, GtkExpander, GtkFileChooserButton, GtkFileChooserDialog, GtkFileChooserWidget, GtkFixed, GtkFontButton, GtkFontSelection, GtkFontSelectionDialog, GtkFrame, GtkHBox, GtkHButtonBox, GtkHPaned, GtkHRuler, GtkHSV, GtkHScale, GtkHScrollbar, GtkHSeparator, GtkHandleBox, GtkIconView, GtkImage, GtkImageMenuItem, GtkInfoBar, GtkInvisible, GtkItem, GtkLabel, GtkLayout, GtkLinkButton, GtkMenu, GtkMenuBar, GtkMenuItem, GtkMenuShell, GtkMenuToolButton, GtkMessageDialog, GtkMisc, GtkNotebook, GtkOffscreenWindow, GtkPageSetupUnixDialog, GtkPaned, GtkPlug, GtkPrintUnixDialog, GtkProgressBar, GtkRadioButton, GtkRadioMenuItem, GtkRadioToolButton, GtkRange, GtkRecentChooserDialog, GtkRecentChooserMenu, GtkRecentChooserWidget, GtkRuler, GtkScale, GtkScaleButton, GtkScrollbar, GtkScrolledWindow, GtkSeparator, GtkSeparatorMenuItem, GtkSeparatorToolItem, GtkSocket, GtkSpinButton, GtkSpinner, GtkStatusbar, GtkTable, GtkTearoffMenuItem, GtkTextView, GtkToggleButton, GtkToggleToolButton, GtkToolButton, GtkToolItem, GtkToolItemGroup, GtkToolPalette, GtkToolbar, GtkTreeView, GtkVBox, GtkVButtonBox, GtkVPaned, GtkVRuler, GtkVScale, GtkVScrollbar, GtkVSeparator, GtkViewport, GtkVolumeButton, GtkWidget and GtkWindow.

Description

The extended layout 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 GtkExtendedLayout interface for existing widgets, which always requests the same height, regardless of the available width.

Implementing GtkExtendedLayout

Some important things to keep in mind when implementing or using the extended layout.

The Extended Layout 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_extended_layout_get_desired_width(). Next, the toplevel will use the minimum width to query for the minimum height contextual to that width using gtk_extended_layout_get_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. GtkExtendedLayout 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_desired_width() and get_desired_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_desired_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.

Details

GtkExtendedLayout

typedef struct _GtkExtendedLayout GtkExtendedLayout;


GtkExtendedLayoutIface

typedef struct {
  GTypeInterface g_iface;

  /* virtual table */
  gboolean  (* is_height_for_width)  (GtkExtendedLayout  *layout);

  void      (* get_desired_width)    (GtkExtendedLayout  *layout,
                                      gint               *minimum_width,
                                      gint               *natural_width);
  void      (* get_desired_height)   (GtkExtendedLayout  *layout,
                                      gint               *minimum_height,
                                      gint               *natural_height);
  void      (* get_width_for_height) (GtkExtendedLayout  *layout,
                                      gint                height,
                                      gint               *minimum_width,
                                      gint               *natural_width);
  void      (* get_height_for_width) (GtkExtendedLayout  *layout,
                                      gint                width,
                                      gint               *minimum_height,
                                      gint               *natural_height);
} GtkExtendedLayoutIface;


gtk_extended_layout_get_desired_height ()

void                gtk_extended_layout_get_desired_height
                                                        (GtkExtendedLayout *layout,
                                                         gint *minimum_height,
                                                         gint *natural_height);

Retrieves a widget's initial minimum and natural height.

Note

This call is specific to width-for-height requests.

layout :

a GtkExtendedLayout instance

minimum_height :

location to store the minimum height, or NULL. [out][allow-none]

natural_height :

location to store the natural height, or NULL. [out][allow-none]

Since 3.0


gtk_extended_layout_get_desired_size ()

void                gtk_extended_layout_get_desired_size
                                                        (GtkExtendedLayout *layout,
                                                         gboolean request_natural,
                                                         GtkRequisition *minimum_size,
                                                         GtkRequisition *natural_size);

Retrieves the minimum and natural size of a widget taking into account the widget's preference for height-for-width management.

If request_natural is specified, the non-contextual natural value will be used to make the contextual request; otherwise the minimum will be used.

This is used to retrieve a suitable size by container widgets which do not impose any restrictions on the child placement.

layout :

a GtkExtendedLayout instance

request_natural :

Whether to base the contextual request off of the base natural or the base minimum

minimum_size :

location for storing the minimum size, or NULL. [out][allow-none]

natural_size :

location for storing the natural size, or NULL. [out][allow-none]

Since 3.0


gtk_extended_layout_get_desired_width ()

void                gtk_extended_layout_get_desired_width
                                                        (GtkExtendedLayout *layout,
                                                         gint *minimum_width,
                                                         gint *natural_width);

Retrieves a widget's initial minimum and natural width.

Note

This call is specific to height-for-width requests.

layout :

a GtkExtendedLayout instance

minimum_width :

location to store the minimum width, or NULL. [out][allow-none]

natural_width :

location to store the natural width, or NULL. [out][allow-none]

Since 3.0


gtk_extended_layout_get_height_for_width ()

void                gtk_extended_layout_get_height_for_width
                                                        (GtkExtendedLayout *layout,
                                                         gint width,
                                                         gint *minimum_height,
                                                         gint *natural_height);

Retrieves a widget's desired height if it would be given the specified width.

layout :

a GtkExtendedLayout instance

width :

the width which is available for allocation

minimum_height :

location for storing the minimum height, or NULL. [out][allow-none]

natural_height :

location for storing the natural height, or NULL. [out][allow-none]

Since 3.0


gtk_extended_layout_get_width_for_height ()

void                gtk_extended_layout_get_width_for_height
                                                        (GtkExtendedLayout *layout,
                                                         gint height,
                                                         gint *minimum_width,
                                                         gint *natural_width);

Retrieves a widget's desired width if it would be given the specified height.

layout :

a GtkExtendedLayout instance

height :

the height which is available for allocation

minimum_width :

location for storing the minimum width, or NULL. [out][allow-none]

natural_width :

location for storing the natural width, or NULL. [out][allow-none]

Since 3.0


gtk_extended_layout_is_height_for_width ()

gboolean            gtk_extended_layout_is_height_for_width
                                                        (GtkExtendedLayout *layout);

Gets whether the widget prefers a height-for-width layout or a width-for-height layout.

Note

GtkBin widgets generally propagate the preference of their child, container widgets need to request something either in context of their children or in context of their allocation capabilities.

layout :

a GtkExtendedLayout instance

Returns :

TRUE if the widget prefers height-for-width, FALSE if the widget should be treated with a width-for-height preference.

Since 3.0