Struct gtk4::ConstraintLayout

source ·
#[repr(transparent)]
pub struct ConstraintLayout { /* private fields */ }
Expand description

A layout manager using constraints to describe relations between widgets.

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

By taking multiple constraints and applying them to the children of a widget using 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 property::Constraint::strength property of Constraint to “nudge” the layout towards a solution.

GtkConstraintLayout as GtkBuildable

ConstraintLayout implements the Buildable interface and has a custom “constraints” element which allows describing constraints in a Builder UI file.

An example of a UI definition fragment specifying a constraint:

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

There can be “constant” and “multiplier” attributes.

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

  <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 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)]

Implements

LayoutManagerExt, glib::ObjectExt, BuildableExt

Implementations§

Creates a new ConstraintLayout layout manager.

Returns

the newly created ConstraintLayout

Adds a constraint to the layout manager.

The property::Constraint::source and property::Constraint::target properties of constraint can be:

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

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

constraint

a Constraint

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.

guide

a ConstraintGuide object

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.

Returns

a GListModel tracking the layout’s constraints

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.

Returns

a GListModel tracking the layout’s guides

Removes all constraints from the layout manager.

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

constraint

a Constraint

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

guide

a ConstraintGuide object

Creates a list of constraints from a VFL description.

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

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

The VFL grammar is:

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

  // 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)]
lines

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

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 ConstraintLayout, or guides

Returns

the list of Constraint instances that were added to the layout

Trait Implementations§

Returns a copy of the value. Read more
Performs copy-assignment from source. Read more
Formats the value using the given formatter. Read more
Returns the “default value” for a type. Read more
Formats the value using the given formatter. Read more
Feeds this value into the given Hasher. Read more
Feeds a slice of this type into the given Hasher. Read more
This method returns an Ordering between self and other. Read more
Compares and returns the maximum of two values. Read more
Compares and returns the minimum of two values. Read more
Restrict a value to a certain interval. Read more
This method tests for self and other values to be equal, and is used by ==. Read more
This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason. Read more
This method returns an ordering between self and other values if one exists. Read more
This method tests less than (for self and other) and is used by the < operator. Read more
This method tests less than or equal to (for self and other) and is used by the <= operator. Read more
This method tests greater than (for self and other) and is used by the > operator. Read more
This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more
Returns the type identifier of Self.

Auto Trait Implementations§

Blanket Implementations§

Gets the TypeId of self. Read more
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more
Upcasts an object to a superclass or interface T. Read more
Upcasts an object to a reference of its superclass or interface T. Read more
Tries to downcast to a subclass or interface implementor T. Read more
Tries to downcast to a reference of its subclass or interface implementor T. Read more
Tries to cast to an object of type T. This handles upcasting, downcasting and casting between interface and interface implementors. All checks are performed at runtime, while downcast and upcast will do many checks at compile-time already. Read more
Tries to cast to reference to an object of type T. This handles upcasting, downcasting and casting between interface and interface implementors. All checks are performed at runtime, while downcast and upcast will do many checks at compile-time already. Read more
Casts to T unconditionally. Read more
Casts to &T unconditionally. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Returns true if the object is an instance of (can be cast to) T.
Returns the type of the object.
Returns the ObjectClass of the object. Read more
Returns the class of the object.
Returns the class of the object in the given type T. Read more
Returns the interface T of the object. Read more
Sets the property property_name of the object to value value. Read more
Sets the property property_name of the object to value value. Read more
Sets multiple properties of the object at once. Read more
Sets multiple properties of the object at once. Read more
Gets the property property_name of the object and cast it to the type V. Read more
Gets the property property_name of the object. Read more
Check if the object has a property property_name of the given type_. Read more
Get the type of the property property_name of this object. Read more
Get the ParamSpec of the property property_name of this object.
Return all ParamSpec of the properties of this object.
Freeze all property notifications until the return guard object is dropped. Read more
Set arbitrary data on this object with the given key. Read more
Return previously set arbitrary data of this object with the given key. Read more
Retrieve previously set arbitrary data of this object with the given key. Read more
Set arbitrary data on this object with the given key. Read more
Return previously set arbitrary data of this object with the given key. Read more
Retrieve previously set arbitrary data of this object with the given key. Read more
Block a given signal handler. Read more
Unblock a given signal handler.
Stop emission of the currently emitted signal.
Stop emission of the currently emitted signal by the (possibly detailed) signal name.
Connect to the signal signal_name on this object. Read more
Connect to the signal signal_id on this object. Read more
Connect to the signal signal_name on this object. Read more
Connect to the signal signal_id on this object. Read more
Connect to the signal signal_name on this object. Read more
Connect to the signal signal_id on this object. Read more
Connect a closure to the signal signal_name on this object. Read more
Connect a closure to the signal signal_id on this object. Read more
Limits the lifetime of closure to the lifetime of the object. When the object’s reference count drops to zero, the closure will be invalidated. An invalidated closure will ignore any calls to invoke_with_values, or invoke when using Rust closures. Read more
Emit signal by signal id. Read more
Same as Self::emit but takes Value for the arguments.
Emit signal by its name. Read more
Emit signal by its name. Read more
Emit signal by its name with details. Read more
Emit signal by its name with details. Read more
Emit signal by signal id with details. Read more
Emit signal by signal id with details. Read more
Disconnect a previously connected signal handler.
Connect to the notify signal of the object. Read more
Connect to the notify signal of the object. Read more
Connect to the notify signal of the object. Read more
Notify that the given property has changed its value. Read more
Notify that the given property has changed its value. Read more
Downgrade this object to a weak reference.
Add a callback to be notified when the Object is disposed.
Add a callback to be notified when the Object is disposed. Read more
Bind property source_property on this object to the target_property on the target object. Read more
Returns the strong reference count of this object.
Runs the dispose mechanism of the object. Read more
Ensures that the type has been registered with the type system.
The resulting type after obtaining ownership.
Creates owned data from borrowed data, usually by cloning. Read more
Uses borrowed data to replace owned data, usually by cloning. Read more
Converts the given value to a String. Read more
The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.