Description

A layout manager using constraints to describe relations between widgets.

Gnome::Gtk4::ConstraintLayout is a layout manager that uses relations between widget attributes, expressed via Gnome::Gtk4::Constraint 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 Gnome::Gtk4::Constraint class to have a more in depth definition.

By taking multiple constraints and applying them to the children of a widget using Gnome::Gtk4::ConstraintLayout, 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 defined in Gnome::Gtk4::Constraint property of Gnome::Gtk4::Constraint to "nudge" the layout towards a solution.

GtkConstraintLayout as GtkBuildable

Gnome::Gtk4::ConstraintLayout implements the Gnome::Gtk4::R-Buildable interface and has a custom "constraints" element which allows describing constraints in a Gnome::Gtk4::Builder UI file.

An example of a UI definition fragment specifying a constraint:

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.

There can be "constant" and "multiplier" attributes.

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

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 Gnome::Gtk4::R-ConstraintTarget.

For instance:

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:

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

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

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

Class initialization

new

:native-object

Create an object using a native object from elsewhere. See also Gnome::N::TopLevelSupportClass.

multi method new ( N-Object :$native-object! )

new-constraintlayout

Creates a new Gnome::Gtk4::ConstraintLayout layout manager.

method new-constraintlayout ( --> Gnome::Gtk4::ConstraintLayout \)

Methods

add-constraint

Adds a constraint to the layout manager.

The source defined in Gnome::Gtk4::Constraint and target defined in Gnome::Gtk4::Constraint properties of constraint can be:

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

• set to the Gnome::Gtk4::Widget using layout

• set to a child of the Gnome::Gtk4::Widget using layout

• set to a Gnome::Gtk4::ConstraintGuide that is part of layout

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

method add-constraint ( Array[Int] $constraint )

• $constraint; (transfer ownership: full) a Gnome::Gtk4::Constraint.

add-constraints-from-description This function is not yet available

Creates a list of constraints from a VFL description.

This function is a convenience wrapper around .add-constraints-from-descriptionv(), using variadic arguments to populate the view/target map.

method add-constraints-from-description ( Array[Str] $lines, Int() $n-lines, Int() $hspacing, Int() $vspacing, N-Object $error, Str $first-view, … --> N-List )

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

• $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 Gnome::Glib::N-Error

• $first-view; the name of a view in the VFL description, followed by the Gnome::Gtk4::R-ConstraintTarget to which it maps.

• …; …. Note that each argument must be specified as a type followed by its value!

Return value; the list of Gnome::Gtk4::Constraints that were added to the layout.

add-constraints-from-descriptionv

Creates a list of constraints from a VFL description.

The Visual Format Language, VFL, is based on Apple's AutoLayout [VFL](https://developer.apple.com/library/content/documentation/UserExperience/Conceptual/AutolayoutPG/VisualFormatLanguage.html).

The views dictionary is used to match Gnome::Gtk4::R-ConstraintTarget instances to the symbolic view name inside the VFL.

The VFL grammar is:

**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:

method add-constraints-from-descriptionv ( Array[Str] $lines, Int() $n-lines, Int() $hspacing, Int() $vspacing, N-Object $views, CArray[N-Error] $err --> N-List )

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

• $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 Gnome::Gtk4::ConstraintLayout, or guides

• $err; Error object. When defined, an error can be returned when there is one. Use Pointer when you want to ignore the error. .

Return value; the list of Gnome::Gtk4::Constraint instances that were added to the layout.

add-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.

method add-guide ( N-Object() $guide )

• $guide; (transfer ownership: full) a Gnome::Gtk4::ConstraintGuide object.

observe-constraints

Returns a Gnome::Gio::R-ListModel to track the constraints that are part of the 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.

method observe-constraints (--> N-List )

Return value; a Gnome::Gio::R-ListModel tracking the layout's constraints.

observe-guides

Returns a Gnome::Gio::R-ListModel to track the guides that are part of the 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.

method observe-guides (--> N-List )

Return value; a Gnome::Gio::R-ListModel tracking the layout's guides.

remove-all-constraints

Removes all constraints from the layout manager.

method remove-all-constraints ( )

remove-constraint

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

method remove-constraint ( Array[Int] $constraint )

• $constraint; a Gnome::Gtk4::Constraint.

remove-guide

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

method remove-guide ( N-Object() $guide )

• $guide; a Gnome::Gtk4::ConstraintGuide object.