GtkConstraintLayout

GtkConstraintLayout — A layout manager using constraints

Object Hierarchy

    GObject
    ├── GtkLayoutChild
       ╰── GtkConstraintLayoutChild
    ╰── GtkLayoutManager
        ╰── GtkConstraintLayout

Implemented Interfaces

GtkConstraintLayout implements GtkBuildable.

Includes

#include <gtk/gtk.h>

Description

GtkConstraintLayout is a layout manager that uses relations between widget attributes, expressed via GtkConstraint instances, to measure and allocate widgets.

How do constraints work

Constraints are objects defining the relationship between attributes of a widget; you can read the description of the GtkConstraint class to have a more in depth definition.

By taking multiple constraints and applying them to the children of a widget using GtkConstraintLayout, it's possible to describe complex layout policies; each constraint applied to a child or to the parent widgets contributes to the full description of the layout, in terms of parameters for resolving the value of each attribute.

It is important to note that a layout is defined by the totality of constraints; removing a child, or a constraint, from an existing layout without changing the remaining constraints may result in an unstable or unsolvable layout.

Constraints have an implicit "reading order"; you should start describing each edge of each child, as well as their relationship with the parent container, from the top left (or top right, in RTL languages), horizontally first, and then vertically.

A constraint-based layout with too few constraints can become "unstable", that is: have more than one solution. The behavior of an unstable layout is undefined.

A constraint-based layout with conflicting constraints may be unsolvable, and lead to an unstable layout. You can use the “strength” property of GtkConstraint to "nudge" the layout towards a solution.


GtkConstraintLayout as GtkBuildable

GtkConstraintLayout implements the GtkBuildable interface and has a custom "constraints" element which allows describing constraints in a GtkBuilder UI file.

An example of a UI definition fragment specifying a constraint:

1
2
3
4
5
6
7
8
9
10
11
12
13
<object class="GtkConstraintLayout">
  <constraints>
    <constraint target="button" target-attribute="start"
                relation="eq"
                source="super" source-attribute="start"
                constant="12"
                strength="required" />
    <constraint target="button" target-attribute="width"
                relation="ge"
                constant="250"
                strength="strong" />
  </constraints>
</object>

The definition above will add two constraints to the GtkConstraintLayout:

  • a required constraint between the leading edge of "button" and the leading edge of the widget using the constraint layout, plus 12 pixels

  • a strong, constant constraint making the width of "button" greater than, or equal to 250 pixels

The "target" and "target-attribute" attributes are required.

The "source" and "source-attribute" attributes of the "constraint" element are optional; if they are not specified, the constraint is assumed to be a constant.

The "relation" attribute is optional; if not specified, the constraint is assumed to be an equality.

The "strength" attribute is optional; if not specified, the constraint is assumed to be required.

The "source" and "target" attributes can be set to "super" to indicate that the constraint target is the widget using the GtkConstraintLayout.

Additionally, the "constraints" element can also contain a description of the GtkConstraintGuides used by the layout:

1
2
3
4
<constraints>
  <guide min-width="100" max-width="500" name="hspace"/>
  <guide min-height="64" nat-height="128" name="vspace" strength="strong"/>
</constraints>

The "guide" element has the following optional attributes:

  • "min-width", "nat-width", and "max-width", describe the minimum, natural, and maximum width of the guide, respectively

  • "min-height", "nat-height", and "max-height", describe the minimum, natural, and maximum height of the guide, respectively

  • "strength" describes the strength of the constraint on the natural size of the guide; if not specified, the constraint is assumed to have a medium strength

  • "name" describes a name for the guide, useful when debugging


Using the Visual Format Language

Complex constraints can be described using a compact syntax called VFL, or *Visual Format Language*.

The Visual Format Language describes all the constraints on a row or column, typically starting from the leading edge towards the trailing one. Each element of the layout is composed by "views", which identify a GtkConstraintTarget.

For instance:

1
[button]-[textField]

Describes a constraint that binds the trailing edge of "button" to the leading edge of "textField", leaving a default space between the two.

Using VFL is also possible to specify predicates that describe constraints on attributes like width and height:

1
2
3
4
5
// Width must be greater than, or equal to 50
[button(>=50)]

// Width of button1 must be equal to width of button2
[button1(==button2)]

The default orientation for a VFL description is horizontal, unless otherwise specified:

1
2
3
4
5
// horizontal orientation, default attribute: width
H:[button(>=150)]

// vertical orientation, default attribute: height
V:[button1(==button2)]

It's also possible to specify multiple predicates, as well as their strength:

1
2
3
// minimum width of button must be 150
// natural width of button can be 250
[button(>=150@required, ==250@medium)]

Finally, it's also possible to use simple arithmetic operators:

1
2
3
// width of button1 must be equal to width of button2
// divided by 2 plus 12
[button1(button2 / 2 + 12)]

Functions

gtk_constraint_layout_new ()

GtkLayoutManager *
gtk_constraint_layout_new (void);

Creates a new GtkConstraintLayout layout manager.

Returns

the newly created GtkConstraintLayout


gtk_constraint_layout_add_constraint ()

void
gtk_constraint_layout_add_constraint (GtkConstraintLayout *layout,
                                      GtkConstraint *constraint);

Adds a GtkConstraint to the layout manager.

The “source” and “target” properties of constraint can be:

  • set to NULL to indicate that the constraint refers to the widget using layout

  • set to the GtkWidget using layout

  • set to a child of the GtkWidget using layout

  • set to a guide that is part of layout

The layout acquires the ownership of constraint after calling this function.

Parameters

layout

a GtkConstraintLayout

 

constraint

a GtkConstraint.

[transfer full]

gtk_constraint_layout_remove_constraint ()

void
gtk_constraint_layout_remove_constraint
                               (GtkConstraintLayout *layout,
                                GtkConstraint *constraint);

Removes constraint from the layout manager, so that it no longer influences the layout.

Parameters

layout

a GtkConstraintLayout

 

constraint

a GtkConstraint

 

gtk_constraint_layout_remove_all_constraints ()

void
gtk_constraint_layout_remove_all_constraints
                               (GtkConstraintLayout *layout);

Removes all constraints from the layout manager.

Parameters

layout

a GtkConstraintLayout

 

gtk_constraint_layout_add_guide ()

void
gtk_constraint_layout_add_guide (GtkConstraintLayout *layout,
                                 GtkConstraintGuide *guide);

Adds a guide to layout . A guide can be used as the source or target of constraints, like a widget, but it is not visible.

The layout acquires the ownership of guide after calling this function.

Parameters

layout

a GtkConstraintLayout

 

guide

a GtkConstraintGuide object.

[transfer full]

gtk_constraint_layout_remove_guide ()

void
gtk_constraint_layout_remove_guide (GtkConstraintLayout *layout,
                                    GtkConstraintGuide *guide);

Removes guide from the layout manager, so that it no longer influences the layout.

Parameters

layout

a GtkConstraintLayout

 

guide

a GtkConstraintGuide object

 

gtk_constraint_layout_add_constraints_from_description ()

GList *
gtk_constraint_layout_add_constraints_from_description
                               (GtkConstraintLayout *layout,
                                const char * const lines[],
                                gsize n_lines,
                                int hspacing,
                                int vspacing,
                                GError **error,
                                const char *first_view,
                                ...);

Creates a list of constraints they formal description using a compact description syntax called VFL, or "Visual Format Language".

This function is a convenience wrapper around gtk_constraint_layout_add_constraints_from_descriptionv(), using variadic arguments to populate the view/target map.

Parameters

layout

a GtkConstraintLayout

 

lines

an array of Visual Format Language lines defining a set of constraints.

[array length=n_lines]

n_lines

the number of lines

 

hspacing

default horizontal spacing value, or -1 for the fallback value

 

vspacing

default vertical spacing value, or -1 for the fallback value

 

error

return location for a GError

 

first_view

the name of a view in the VFL description, followed by the GtkConstraintTarget to which it maps

 

...

a NULL-terminated list of view names and GtkConstraintTargets

 

Returns

the list of GtkConstraints that were added to the layout.

[transfer container][element-type GtkConstraint]


gtk_constraint_layout_add_constraints_from_descriptionv ()

GList *
gtk_constraint_layout_add_constraints_from_descriptionv
                               (GtkConstraintLayout *layout,
                                const char * const lines[],
                                gsize n_lines,
                                int hspacing,
                                int vspacing,
                                GHashTable *views,
                                GError **error);

Creates a list of constraints from a formal description using a compact description syntax called VFL, or "Visual Format Language".

The Visual Format Language is based on Apple's AutoLayout VFL.

The views dictionary is used to match GtkConstraintTargets to the symbolic view name inside the VFL.

The VFL grammar is:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
<visualFormatString> = (<orientation>)?
                       (<superview><connection>)?
                       <view>(<connection><view>)*
                       (<connection><superview>)?
       <orientation> = 'H' | 'V'
         <superview> = '|'
        <connection> = '' | '-' <predicateList> '-' | '-'
     <predicateList> = <simplePredicate> | <predicateListWithParens>
   <simplePredicate> = <metricName> | <positiveNumber>
  <predicateListWithParens> = '(' <predicate> (',' <predicate>)* ')'
         <predicate> = (<relation>)? <objectOfPredicate> (<operatorList>)? ('@' <priority>)?
          <relation> = '==' | '<=' | '>='
 <objectOfPredicate> = <constant> | <viewName> | ('.' <attributeName>)?
          <priority> = <positiveNumber> | 'required' | 'strong' | 'medium' | 'weak'
          <constant> = <number>
      <operatorList> = (<multiplyOperator>)? (<addOperator>)?
  <multiplyOperator> = [ '*' | '/' ] <positiveNumber>
       <addOperator> = [ '+' | '-' ] <positiveNumber>
          <viewName> = [A-Za-z_]([A-Za-z0-9_]*) // A C identifier
        <metricName> = [A-Za-z_]([A-Za-z0-9_]*) // A C identifier
     <attributeName> = 'top' | 'bottom' | 'left' | 'right' | 'width' | 'height' |
                       'start' | 'end' | 'centerX' | 'centerY' | 'baseline'
    <positiveNumber> // A positive real number parseable by g_ascii_strtod()
            <number> // A real number parseable by g_ascii_strtod()

**Note**: The VFL grammar used by GTK is slightly different than the one defined by Apple, as it can use symbolic values for the constraint's strength instead of numeric values; additionally, GTK allows adding simple arithmetic operations inside predicates.

Examples of VFL descriptions are:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
// Default spacing
[button]-[textField]

// Width constraint
[button(>=50)]

// Connection to super view
|-50-[purpleBox]-50-|

// Vertical layout
V:[topField]-10-[bottomField]

// Flush views
[maroonView][blueView]

// Priority
[button(100@strong)]

// Equal widths
[button1(==button2)]

// Multiple predicates
[flexibleButton(>=70,<=100)]

// A complete line of layout
|-[find]-[findNext]-[findField(>=20)]-|

// Operators
[button1(button2 / 3 + 50)]

// Named attributes
[button1(==button2.height)]

[rename-to gtk_constraint_layout_add_constraints_from_description]

Parameters

layout

a GtkConstraintLayout

 

lines

an array of Visual Format Language lines defining a set of constraints.

[array length=n_lines]

n_lines

the number of lines

 

hspacing

default horizontal spacing value, or -1 for the fallback value

 

vspacing

default vertical spacing value, or -1 for the fallback value

 

views

a dictionary of [ name, target ] pairs; the name keys map to the view names in the VFL lines, while the target values map to children of the widget using a GtkConstraintLayout, or guides.

[element-type utf8 Gtk.ConstraintTarget]

error

return location for a GError

 

Returns

the list of GtkConstraints that were added to the layout.

[transfer container][element-type GtkConstraint]


gtk_constraint_layout_observe_constraints ()

GListModel *
gtk_constraint_layout_observe_constraints
                               (GtkConstraintLayout *layout);

Returns a GListModel to track the constraints that are part of layout .

Calling this function will enable extra internal bookkeeping to track constraints and emit signals on the returned listmodel. It may slow down operations a lot.

Applications should try hard to avoid calling this function because of the slowdowns.

Parameters

layout

a GtkConstraintLayout

 

Returns

a GListModel tracking layout 's constraints.

[transfer full][attributes element-type=GtkConstraint]


gtk_constraint_layout_observe_guides ()

GListModel *
gtk_constraint_layout_observe_guides (GtkConstraintLayout *layout);

Returns a GListModel to track the guides that are part of layout .

Calling this function will enable extra internal bookkeeping to track guides and emit signals on the returned listmodel. It may slow down operations a lot.

Applications should try hard to avoid calling this function because of the slowdowns.

Parameters

layout

a GtkConstraintLayout

 

Returns

a GListModel tracking layout 's guides.

[transfer full][attributes element-type=GtkConstraintGuide]

Types and Values

GtkConstraintLayout

typedef struct _GtkConstraintLayout GtkConstraintLayout;

A layout manager using GtkConstraint to describe relations between widgets.


GtkConstraintLayoutChild

typedef struct _GtkConstraintLayoutChild GtkConstraintLayoutChild;

A GtkLayoutChild in a GtkConstraintLayout.


enum GtkConstraintVflParserError

Domain for VFL parsing errors.

Members

GTK_CONSTRAINT_VFL_PARSER_ERROR_INVALID_SYMBOL

Invalid or unknown symbol

 

GTK_CONSTRAINT_VFL_PARSER_ERROR_INVALID_ATTRIBUTE

Invalid or unknown attribute

 

GTK_CONSTRAINT_VFL_PARSER_ERROR_INVALID_VIEW

Invalid or unknown view

 

GTK_CONSTRAINT_VFL_PARSER_ERROR_INVALID_METRIC

Invalid or unknown metric

 

GTK_CONSTRAINT_VFL_PARSER_ERROR_INVALID_PRIORITY

Invalid or unknown priority

 

GTK_CONSTRAINT_VFL_PARSER_ERROR_INVALID_RELATION

Invalid or unknown relation