class Gtk::ConstraintLayout

Overview

A layout manager using constraints to describe relations between widgets.

GtkConstraintLayout is a layout manager that uses relations between widget attributes, expressed via Gtk#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 Gtk#Constraint 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 Gtk::Constraint#strength property of Gtk#Constraint to "nudge" the layout towards a solution.

GtkConstraintLayout as GtkBuildable

GtkConstraintLayout implements the Gtk#Buildable interface and has a custom "constraints" element which allows describing constraints in a Gtk#Builder UI file.

An example of a UI definition fragment specifying a constraint:

WARNING ⚠️ The following code is in xml ⚠️

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

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:

WARNING ⚠️ The following code is in xml ⚠️

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

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 Gtk#ConstraintTarget.

For instance:

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

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

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

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

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

Included Modules

Defined in:

auto/gtk-4.0/constraint_layout.cr

Constructors

Class Method Summary

Instance Method Summary

Instance methods inherited from module Gtk::Buildable

buildable_id : String? buildable_id, to_unsafe to_unsafe

Instance methods inherited from class Gtk::LayoutManager

allocate(widget : Gtk::Widget, width : Int32, height : Int32, baseline : Int32) : Nil allocate, layout_changed : Nil layout_changed, layout_child(child : Gtk::Widget) : Gtk::LayoutChild layout_child, measure(widget : Gtk::Widget, orientation : Gtk::Orientation, for_size : Int32) : Nil measure, request_mode : Gtk::SizeRequestMode request_mode, widget : Gtk::Widget? widget

Constructor methods inherited from class Gtk::LayoutManager

new new

Class methods inherited from class Gtk::LayoutManager

g_type : UInt64 g_type

Instance methods inherited from class GObject::Object

bind_property(source_property : String, target : GObject::Object, target_property : String, flags : GObject::BindingFlags) : GObject::Binding bind_property, bind_property_full(source_property : String, target : GObject::Object, target_property : String, flags : GObject::BindingFlags, transform_to : GObject::Closure, transform_from : GObject::Closure) : GObject::Binding bind_property_full, data(key : String) : Pointer(Void)? data, finalize finalize, freeze_notify : Nil freeze_notify, getv(names : Enumerable(String), values : Enumerable(_)) : Nil getv, notify(property_name : String) : Nil notify, notify_by_pspec(pspec : GObject::ParamSpec) : Nil notify_by_pspec, notify_signal notify_signal, property(property_name : String, value : _) : Nil property, qdata(quark : UInt32) : Pointer(Void)? qdata, ref_count ref_count, run_dispose : Nil run_dispose, set_data(key : String, data : Pointer(Void)?) : Nil set_data, set_property(property_name : String, value : _) : Nil set_property, steal_data(key : String) : Pointer(Void)? steal_data, steal_qdata(quark : UInt32) : Pointer(Void)? steal_qdata, thaw_notify : Nil thaw_notify, to_unsafe : Pointer(Void) to_unsafe, watch_closure(closure : GObject::Closure) : Nil watch_closure

Constructor methods inherited from class GObject::Object

cast(obj : GObject::Object) : self cast, cast?(obj : GObject::Object) : self? cast?, new new, newv(object_type : UInt64, parameters : Enumerable(GObject::Parameter)) : self newv

Class methods inherited from class GObject::Object

compat_control(what : UInt64, data : Pointer(Void)?) : UInt64 compat_control, g_type : UInt64 g_type, interface_find_property(g_iface : GObject::TypeInterface, property_name : String) : GObject::ParamSpec interface_find_property, interface_list_properties(g_iface : GObject::TypeInterface) : Enumerable(GObject::ParamSpec) interface_list_properties

Constructor Detail

def self.new #

Creates a new GtkConstraintLayout layout manager.


Class Method Detail

def self.g_type : UInt64 #

Returns the type id (GType) registered in GLib type system.


Instance Method Detail

def add_constraint(constraint : Gtk::Constraint) : Nil #

Adds a constraint to the layout manager.

The Gtk::Constraint#source and Gtk::Constraint#target properties of constraint can be:

  • set to NULL to indicate that the constraint refers to the widget using layout
  • set to the Gtk#Widget using layout
  • set to a child of the Gtk#Widget using layout
  • set to a Gtk#ConstraintGuide that is part of layout

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


def add_constraints_from_description(lines : Enumerable(String), hspacing : Int32, vspacing : Int32, views : Pointer(Void)) : GLib::List #

Creates a list of constraints from a VFL description.

This function is a convenience wrapper around Gtk::ConstraintLayout#add_constraints_from_descriptionv, using variadic arguments to populate the view/target map.


def add_guide(guide : Gtk::ConstraintGuide) : Nil #

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.


def observe_constraints : Gio::ListModel #

Returns a GListModel 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.


def observe_guides : Gio::ListModel #

Returns a GListModel 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.


def remove_all_constraints : Nil #

Removes all constraints from the layout manager.


def remove_constraint(constraint : Gtk::Constraint) : Nil #

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


def remove_guide(guide : Gtk::ConstraintGuide) : Nil #

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