<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
<!ENTITY pi "&#960;">
<!ENTITY solidus "&#8260;">
]>
<refentry id="GtkConstraintLayout">
<refmeta>
<refentrytitle role="top_of_page" id="GtkConstraintLayout.top_of_page">GtkConstraintLayout</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GTK4 Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>GtkConstraintLayout</refname>
<refpurpose>A layout manager using constraints</refpurpose>
</refnamediv>

<refsect1 id="GtkConstraintLayout.functions" role="functions_proto">
<title role="functions_proto.title">Functions</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="functions_proto_type" colwidth="150px"/>
<colspec colname="functions_proto_name"/>
<tbody>
<row><entry role="function_type"><link linkend="GtkLayoutManager"><returnvalue>GtkLayoutManager</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-constraint-layout-new">gtk_constraint_layout_new</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-constraint-layout-add-constraint">gtk_constraint_layout_add_constraint</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-constraint-layout-remove-constraint">gtk_constraint_layout_remove_constraint</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-constraint-layout-remove-all-constraints">gtk_constraint_layout_remove_all_constraints</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-constraint-layout-add-guide">gtk_constraint_layout_add_guide</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-constraint-layout-remove-guide">gtk_constraint_layout_remove_guide</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="GList"><returnvalue>GList</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-constraint-layout-add-constraints-from-description">gtk_constraint_layout_add_constraints_from_description</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GList"><returnvalue>GList</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-constraint-layout-add-constraints-from-descriptionv">gtk_constraint_layout_add_constraints_from_descriptionv</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="GListModel"><returnvalue>GListModel</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-constraint-layout-observe-constraints">gtk_constraint_layout_observe_constraints</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GListModel"><returnvalue>GListModel</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-constraint-layout-observe-guides">gtk_constraint_layout_observe_guides</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<anchor id="GtkConstraintLayoutChild"/><refsect1 id="GtkConstraintLayout.other" role="other_proto">
<title role="other_proto.title">Types and Values</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="other_proto_type" colwidth="150px"/>
<colspec colname="other_proto_name"/>
<tbody>
<row><entry role="datatype_keyword"></entry><entry role="function_name"><link linkend="GtkConstraintLayout-struct">GtkConstraintLayout</link></entry></row>
<row><entry role="datatype_keyword"></entry><entry role="function_name"><link linkend="GtkConstraintLayoutChild-struct">GtkConstraintLayoutChild</link></entry></row>
<row><entry role="datatype_keyword">enum</entry><entry role="function_name"><link linkend="GtkConstraintVflParserError">GtkConstraintVflParserError</link></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkConstraintLayout.object-hierarchy" role="object_hierarchy">
<title role="object_hierarchy.title">Object Hierarchy</title>
<screen>    <link linkend="GObject">GObject</link>
    <phrase role="lineart">&#9500;&#9472;&#9472;</phrase> <link linkend="GtkLayoutChild">GtkLayoutChild</link>
    <phrase role="lineart">&#9474;</phrase>   <phrase role="lineart">&#9584;&#9472;&#9472;</phrase> GtkConstraintLayoutChild
    <phrase role="lineart">&#9584;&#9472;&#9472;</phrase> <link linkend="GtkLayoutManager">GtkLayoutManager</link>
        <phrase role="lineart">&#9584;&#9472;&#9472;</phrase> GtkConstraintLayout
</screen>
</refsect1>
<refsect1 id="GtkConstraintLayout.implemented-interfaces" role="impl_interfaces">
<title role="impl_interfaces.title">Implemented Interfaces</title>
<para>
GtkConstraintLayout implements
 <link linkend="GtkBuildable">GtkBuildable</link>.</para>

</refsect1>

<refsect1 id="GtkConstraintLayout.includes"><title>Includes</title><synopsis>#include &lt;gtk/gtk.h&gt;
</synopsis></refsect1>

<refsect1 id="GtkConstraintLayout.description" role="desc">
<title role="desc.title">Description</title>
<para>GtkConstraintLayout is a layout manager that uses relations between
widget attributes, expressed via <link linkend="GtkConstraint"><type>GtkConstraint</type></link> instances, to measure
and allocate widgets.</para>
<refsect2><title>How do constraints work</title><para>Constraints are objects defining the relationship between attributes
of a widget; you can read the description of the <link linkend="GtkConstraint"><type>GtkConstraint</type></link>
class to have a more in depth definition.</para>
<para>By taking multiple constraints and applying them to the children of
a widget using <link linkend="GtkConstraintLayout"><type>GtkConstraintLayout</type></link>, 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.</para>
<para>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.</para>
<para>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.</para>
<para>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.</para>
<para>A constraint-based layout with conflicting constraints may be unsolvable,
and lead to an unstable layout. You can use the <link linkend="GtkConstraint--strength"><type>“strength”</type></link>
property of <link linkend="GtkConstraint"><type>GtkConstraint</type></link> to "nudge" the layout towards a solution.</para>
</refsect2>
<refsect2><title>GtkConstraintLayout as GtkBuildable</title><para>GtkConstraintLayout implements the <link linkend="GtkBuildable"><type>GtkBuildable</type></link> interface and has a
custom "constraints" element which allows describing constraints in a
GtkBuilder UI file.</para>
<para>An example of a UI definition fragment specifying a constraint:</para>
<informalexample><programlisting role="example"><![CDATA[
  <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>
]]></programlisting></informalexample>
<para></para>
<para>The definition above will add two constraints to the GtkConstraintLayout:</para>
<itemizedlist>
<listitem><para>a required constraint between the leading edge of "button" and
the leading edge of the widget using the constraint layout, plus
12 pixels</para></listitem>
<listitem>
<para>a strong, constant constraint making the width of "button" greater
than, or equal to 250 pixels</para>
</listitem>
</itemizedlist>
<para>The "target" and "target-attribute" attributes are required.</para>
<para>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.</para>
<para>The "relation" attribute is optional; if not specified, the constraint
is assumed to be an equality.</para>
<para>The "strength" attribute is optional; if not specified, the constraint
is assumed to be required.</para>
<para>The "source" and "target" attributes can be set to "super" to indicate
that the constraint target is the widget using the GtkConstraintLayout.</para>
<para>Additionally, the "constraints" element can also contain a description
of the <link linkend="GtkConstraintGuides"><type>GtkConstraintGuides</type></link> used by the layout:</para>
<informalexample><programlisting role="example"><![CDATA[
  <constraints>
    <guide min-width="100" max-width="500" name="hspace"/>
    <guide min-height="64" nat-height="128" name="vspace" strength="strong"/>
  </constraints>
]]></programlisting></informalexample>
<para></para>
<para>The "guide" element has the following optional attributes:</para>
<itemizedlist>
<listitem><para>"min-width", "nat-width", and "max-width", describe the minimum,
natural, and maximum width of the guide, respectively</para></listitem>
<listitem><para>"min-height", "nat-height", and "max-height", describe the minimum,
natural, and maximum height of the guide, respectively</para></listitem>
<listitem><para>"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</para></listitem>
<listitem>
<para>"name" describes a name for the guide, useful when debugging</para>
</listitem>
</itemizedlist>
</refsect2>
<refsect2><title>Using the Visual Format Language</title><para>Complex constraints can be described using a compact syntax called VFL,
or *Visual Format Language*.</para>
<para>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 <link linkend="GtkConstraintTarget"><type>GtkConstraintTarget</type></link>.</para>
<para>For instance:</para>
<informalexample><programlisting role="example"><![CDATA[
  [button]-[textField]
]]></programlisting></informalexample>
<para></para>
<para>Describes a constraint that binds the trailing edge of "button" to the
leading edge of "textField", leaving a default space between the two.</para>
<para>Using VFL is also possible to specify predicates that describe constraints
on attributes like width and height:</para>
<informalexample><programlisting role="example"><![CDATA[
  // Width must be greater than, or equal to 50
  [button(>=50)]

  // Width of button1 must be equal to width of button2
  [button1(==button2)]
]]></programlisting></informalexample>
<para></para>
<para>The default orientation for a VFL description is horizontal, unless
otherwise specified:</para>
<informalexample><programlisting role="example"><![CDATA[
  // horizontal orientation, default attribute: width
  H:[button(>=150)]

  // vertical orientation, default attribute: height
  V:[button1(==button2)]
]]></programlisting></informalexample>
<para></para>
<para>It's also possible to specify multiple predicates, as well as their
strength:</para>
<informalexample><programlisting role="example"><![CDATA[
  // minimum width of button must be 150
  // natural width of button can be 250
  [button(>=150@required, ==250@medium)]
]]></programlisting></informalexample>
<para></para>
<para>Finally, it's also possible to use simple arithmetic operators:</para>
<informalexample><programlisting role="example"><![CDATA[
  // width of button1 must be equal to width of button2
  // divided by 2 plus 12
  [button1(button2 / 2 + 12)]
]]></programlisting></informalexample>
<para></para>
</refsect2>

</refsect1>
<refsect1 id="GtkConstraintLayout.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="gtk-constraint-layout-new" role="function">
<title>gtk_constraint_layout_new&#160;()</title>
<indexterm zone="gtk-constraint-layout-new"><primary>gtk_constraint_layout_new</primary></indexterm>
<programlisting language="C"><link linkend="GtkLayoutManager"><returnvalue>GtkLayoutManager</returnvalue></link>&#160;*
gtk_constraint_layout_new (<parameter><type>void</type></parameter>);</programlisting>
<para>Creates a new <link linkend="GtkConstraintLayout"><type>GtkConstraintLayout</type></link> layout manager.</para>
<refsect3 id="gtk-constraint-layout-new.returns" role="returns">
<title>Returns</title>
<para> the newly created <link linkend="GtkConstraintLayout"><type>GtkConstraintLayout</type></link></para>
</refsect3></refsect2>
<refsect2 id="gtk-constraint-layout-add-constraint" role="function">
<title>gtk_constraint_layout_add_constraint&#160;()</title>
<indexterm zone="gtk-constraint-layout-add-constraint"><primary>gtk_constraint_layout_add_constraint</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_constraint_layout_add_constraint (<parameter><link linkend="GtkConstraintLayout"><type>GtkConstraintLayout</type></link> *layout</parameter>,
                                      <parameter><link linkend="GtkConstraint"><type>GtkConstraint</type></link> *constraint</parameter>);</programlisting>
<para>Adds a <link linkend="GtkConstraint"><type>GtkConstraint</type></link> to the layout manager.</para>
<para>The <link linkend="GtkConstraint--source"><type>“source”</type></link> and <link linkend="GtkConstraint--target"><type>“target”</type></link>
properties of <parameter>constraint</parameter>
 can be:</para>
<itemizedlist>
<listitem><para>set to <link linkend="NULL:CAPS"><literal>NULL</literal></link> to indicate that the constraint refers to the
widget using <parameter>layout</parameter>
</para></listitem>
<listitem><para>set to the <link linkend="GtkWidget"><type>GtkWidget</type></link> using <parameter>layout</parameter>
</para></listitem>
<listitem><para>set to a child of the <link linkend="GtkWidget"><type>GtkWidget</type></link> using <parameter>layout</parameter>
</para></listitem>
<listitem>
<para>set to a guide that is part of <parameter>layout</parameter>
</para>
</listitem>
</itemizedlist>
<para>The <parameter>layout</parameter>
 acquires the ownership of <parameter>constraint</parameter>
 after calling
this function.</para>
<refsect3 id="gtk-constraint-layout-add-constraint.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>layout</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkConstraintLayout"><type>GtkConstraintLayout</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>constraint</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkConstraint"><type>GtkConstraint</type></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>transfer full</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-constraint-layout-remove-constraint" role="function">
<title>gtk_constraint_layout_remove_constraint&#160;()</title>
<indexterm zone="gtk-constraint-layout-remove-constraint"><primary>gtk_constraint_layout_remove_constraint</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_constraint_layout_remove_constraint
                               (<parameter><link linkend="GtkConstraintLayout"><type>GtkConstraintLayout</type></link> *layout</parameter>,
                                <parameter><link linkend="GtkConstraint"><type>GtkConstraint</type></link> *constraint</parameter>);</programlisting>
<para>Removes <parameter>constraint</parameter>
 from the layout manager,
so that it no longer influences the layout.</para>
<refsect3 id="gtk-constraint-layout-remove-constraint.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>layout</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkConstraintLayout"><type>GtkConstraintLayout</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>constraint</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkConstraint"><type>GtkConstraint</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-constraint-layout-remove-all-constraints" role="function">
<title>gtk_constraint_layout_remove_all_constraints&#160;()</title>
<indexterm zone="gtk-constraint-layout-remove-all-constraints"><primary>gtk_constraint_layout_remove_all_constraints</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_constraint_layout_remove_all_constraints
                               (<parameter><link linkend="GtkConstraintLayout"><type>GtkConstraintLayout</type></link> *layout</parameter>);</programlisting>
<para>Removes all constraints from the layout manager.</para>
<refsect3 id="gtk-constraint-layout-remove-all-constraints.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>layout</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkConstraintLayout"><type>GtkConstraintLayout</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-constraint-layout-add-guide" role="function">
<title>gtk_constraint_layout_add_guide&#160;()</title>
<indexterm zone="gtk-constraint-layout-add-guide"><primary>gtk_constraint_layout_add_guide</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_constraint_layout_add_guide (<parameter><link linkend="GtkConstraintLayout"><type>GtkConstraintLayout</type></link> *layout</parameter>,
                                 <parameter><link linkend="GtkConstraintGuide"><type>GtkConstraintGuide</type></link> *guide</parameter>);</programlisting>
<para>Adds a guide to <parameter>layout</parameter>
. A guide can be used as
the source or target of constraints, like a widget,
but it is not visible.</para>
<para>The <parameter>layout</parameter>
 acquires the ownership of <parameter>guide</parameter>
 after calling
this function.</para>
<refsect3 id="gtk-constraint-layout-add-guide.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>layout</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkConstraintLayout"><type>GtkConstraintLayout</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>guide</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkConstraintGuide"><type>GtkConstraintGuide</type></link> object. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>transfer full</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-constraint-layout-remove-guide" role="function">
<title>gtk_constraint_layout_remove_guide&#160;()</title>
<indexterm zone="gtk-constraint-layout-remove-guide"><primary>gtk_constraint_layout_remove_guide</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_constraint_layout_remove_guide (<parameter><link linkend="GtkConstraintLayout"><type>GtkConstraintLayout</type></link> *layout</parameter>,
                                    <parameter><link linkend="GtkConstraintGuide"><type>GtkConstraintGuide</type></link> *guide</parameter>);</programlisting>
<para>Removes <parameter>guide</parameter>
 from the layout manager,
so that it no longer influences the layout.</para>
<refsect3 id="gtk-constraint-layout-remove-guide.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>layout</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkConstraintLayout"><type>GtkConstraintLayout</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>guide</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkConstraintGuide"><type>GtkConstraintGuide</type></link> object</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-constraint-layout-add-constraints-from-description" role="function">
<title>gtk_constraint_layout_add_constraints_from_description&#160;()</title>
<indexterm zone="gtk-constraint-layout-add-constraints-from-description"><primary>gtk_constraint_layout_add_constraints_from_description</primary></indexterm>
<programlisting language="C"><link linkend="GList"><returnvalue>GList</returnvalue></link>&#160;*
gtk_constraint_layout_add_constraints_from_description
                               (<parameter><link linkend="GtkConstraintLayout"><type>GtkConstraintLayout</type></link> *layout</parameter>,
                                <parameter>const <link linkend="char"><type>char</type></link> * const lines[]</parameter>,
                                <parameter><link linkend="gsize"><type>gsize</type></link> n_lines</parameter>,
                                <parameter><link linkend="int"><type>int</type></link> hspacing</parameter>,
                                <parameter><link linkend="int"><type>int</type></link> vspacing</parameter>,
                                <parameter><link linkend="GError"><type>GError</type></link> **error</parameter>,
                                <parameter>const <link linkend="char"><type>char</type></link> *first_view</parameter>,
                                <parameter>...</parameter>);</programlisting>
<para>Creates a list of constraints they formal description using a compact
description syntax called VFL, or "Visual Format Language".</para>
<para>This function is a convenience wrapper around
<link linkend="gtk-constraint-layout-add-constraints-from-descriptionv"><function>gtk_constraint_layout_add_constraints_from_descriptionv()</function></link>, using
variadic arguments to populate the view/target map.</para>
<refsect3 id="gtk-constraint-layout-add-constraints-from-description.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>layout</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkConstraintLayout"><type>GtkConstraintLayout</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>lines</para></entry>
<entry role="parameter_description"><para>an array of Visual Format Language lines
defining a set of constraints. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>array</acronym> length=n_lines]</emphasis></entry></row>
<row><entry role="parameter_name"><para>n_lines</para></entry>
<entry role="parameter_description"><para>the number of lines</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>hspacing</para></entry>
<entry role="parameter_description"><para>default horizontal spacing value, or -1 for the fallback value</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>vspacing</para></entry>
<entry role="parameter_description"><para>default vertical spacing value, or -1 for the fallback value</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>error</para></entry>
<entry role="parameter_description"><para>return location for a <link linkend="GError"><type>GError</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>first_view</para></entry>
<entry role="parameter_description"><para>the name of a view in the VFL description, followed by the
<link linkend="GtkConstraintTarget"><type>GtkConstraintTarget</type></link> to which it maps</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>...</para></entry>
<entry role="parameter_description"><para>a <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated list of view names and <link linkend="GtkConstraintTargets"><type>GtkConstraintTargets</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-constraint-layout-add-constraints-from-description.returns" role="returns">
<title>Returns</title>
<para>the list of
<link linkend="GtkConstraints"><type>GtkConstraints</type></link> that were added to the layout. </para>
<para><emphasis role="annotation">[<acronym>transfer container</acronym>][<acronym>element-type</acronym> GtkConstraint]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="gtk-constraint-layout-add-constraints-from-descriptionv" role="function">
<title>gtk_constraint_layout_add_constraints_from_descriptionv&#160;()</title>
<indexterm zone="gtk-constraint-layout-add-constraints-from-descriptionv"><primary>gtk_constraint_layout_add_constraints_from_descriptionv</primary></indexterm>
<programlisting language="C"><link linkend="GList"><returnvalue>GList</returnvalue></link>&#160;*
gtk_constraint_layout_add_constraints_from_descriptionv
                               (<parameter><link linkend="GtkConstraintLayout"><type>GtkConstraintLayout</type></link> *layout</parameter>,
                                <parameter>const <link linkend="char"><type>char</type></link> * const lines[]</parameter>,
                                <parameter><link linkend="gsize"><type>gsize</type></link> n_lines</parameter>,
                                <parameter><link linkend="int"><type>int</type></link> hspacing</parameter>,
                                <parameter><link linkend="int"><type>int</type></link> vspacing</parameter>,
                                <parameter><link linkend="GHashTable"><type>GHashTable</type></link> *views</parameter>,
                                <parameter><link linkend="GError"><type>GError</type></link> **error</parameter>);</programlisting>
<para>Creates a list of constraints from a formal description using a compact
description syntax called VFL, or "Visual Format Language".</para>
<para>The Visual Format Language is based on Apple's AutoLayout <ulink url="https://developer.apple.com/library/content/documentation/UserExperience/Conceptual/AutolayoutPG/VisualFormatLanguage.html">VFL</ulink>.</para>
<para>The <parameter>views</parameter>
 dictionary is used to match <link linkend="GtkConstraintTargets"><type>GtkConstraintTargets</type></link> to the symbolic
view name inside the VFL.</para>
<para>The VFL grammar is:</para>
<informalexample><programlisting role="example"><![CDATA[
       <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()
]]></programlisting></informalexample>
<para></para>
<para>**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.</para>
<para>Examples of VFL descriptions are:</para>
<informalexample><programlisting role="example"><![CDATA[
  // 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)]
]]></programlisting></informalexample>
<para></para>

<para><emphasis role="annotation">[<acronym>rename-to</acronym> gtk_constraint_layout_add_constraints_from_description]</emphasis></para><refsect3 id="gtk-constraint-layout-add-constraints-from-descriptionv.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>layout</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkConstraintLayout"><type>GtkConstraintLayout</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>lines</para></entry>
<entry role="parameter_description"><para>an array of Visual Format Language lines
defining a set of constraints. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>array</acronym> length=n_lines]</emphasis></entry></row>
<row><entry role="parameter_name"><para>n_lines</para></entry>
<entry role="parameter_description"><para>the number of lines</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>hspacing</para></entry>
<entry role="parameter_description"><para>default horizontal spacing value, or -1 for the fallback value</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>vspacing</para></entry>
<entry role="parameter_description"><para>default vertical spacing value, or -1 for the fallback value</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>views</para></entry>
<entry role="parameter_description"><para>a dictionary of [ name, target ]
pairs; the <literal>name</literal> keys map to the view names in the VFL lines, while
the <literal>target</literal> values map to children of the widget using a <link linkend="GtkConstraintLayout"><type>GtkConstraintLayout</type></link>, or guides. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>element-type</acronym> utf8 Gtk.ConstraintTarget]</emphasis></entry></row>
<row><entry role="parameter_name"><para>error</para></entry>
<entry role="parameter_description"><para>return location for a <link linkend="GError"><type>GError</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-constraint-layout-add-constraints-from-descriptionv.returns" role="returns">
<title>Returns</title>
<para>the list of
<link linkend="GtkConstraints"><type>GtkConstraints</type></link> that were added to the layout. </para>
<para><emphasis role="annotation">[<acronym>transfer container</acronym>][<acronym>element-type</acronym> GtkConstraint]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="gtk-constraint-layout-observe-constraints" role="function">
<title>gtk_constraint_layout_observe_constraints&#160;()</title>
<indexterm zone="gtk-constraint-layout-observe-constraints"><primary>gtk_constraint_layout_observe_constraints</primary></indexterm>
<programlisting language="C"><link linkend="GListModel"><returnvalue>GListModel</returnvalue></link>&#160;*
gtk_constraint_layout_observe_constraints
                               (<parameter><link linkend="GtkConstraintLayout"><type>GtkConstraintLayout</type></link> *layout</parameter>);</programlisting>
<para>Returns a <link linkend="GListModel"><type>GListModel</type></link> to track the constraints that are
part of <parameter>layout</parameter>
.</para>
<para>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.</para>
<para>Applications should try hard to avoid calling this function
because of the slowdowns.</para>
<refsect3 id="gtk-constraint-layout-observe-constraints.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>layout</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkConstraintLayout"><type>GtkConstraintLayout</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-constraint-layout-observe-constraints.returns" role="returns">
<title>Returns</title>
<para>a
<link linkend="GListModel"><type>GListModel</type></link> tracking <parameter>layout</parameter>
's constraints. </para>
<para><emphasis role="annotation">[<acronym>transfer full</acronym>][<acronym>attributes</acronym> element-type=GtkConstraint]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="gtk-constraint-layout-observe-guides" role="function">
<title>gtk_constraint_layout_observe_guides&#160;()</title>
<indexterm zone="gtk-constraint-layout-observe-guides"><primary>gtk_constraint_layout_observe_guides</primary></indexterm>
<programlisting language="C"><link linkend="GListModel"><returnvalue>GListModel</returnvalue></link>&#160;*
gtk_constraint_layout_observe_guides (<parameter><link linkend="GtkConstraintLayout"><type>GtkConstraintLayout</type></link> *layout</parameter>);</programlisting>
<para>Returns a <link linkend="GListModel"><type>GListModel</type></link> to track the guides that are
part of <parameter>layout</parameter>
.</para>
<para>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.</para>
<para>Applications should try hard to avoid calling this function
because of the slowdowns.</para>
<refsect3 id="gtk-constraint-layout-observe-guides.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>layout</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkConstraintLayout"><type>GtkConstraintLayout</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-constraint-layout-observe-guides.returns" role="returns">
<title>Returns</title>
<para>a
<link linkend="GListModel"><type>GListModel</type></link> tracking <parameter>layout</parameter>
's guides. </para>
<para><emphasis role="annotation">[<acronym>transfer full</acronym>][<acronym>attributes</acronym> element-type=GtkConstraintGuide]</emphasis></para>
</refsect3></refsect2>

</refsect1>
<refsect1 id="GtkConstraintLayout.other_details" role="details">
<title role="details.title">Types and Values</title>
<refsect2 id="GtkConstraintLayout-struct" role="struct">
<title>GtkConstraintLayout</title>
<indexterm zone="GtkConstraintLayout-struct"><primary>GtkConstraintLayout</primary></indexterm>
<programlisting language="C">typedef struct _GtkConstraintLayout GtkConstraintLayout;</programlisting>
<para>A layout manager using <link linkend="GtkConstraint"><type>GtkConstraint</type></link> to describe
relations between widgets.</para>
</refsect2>
<refsect2 id="GtkConstraintLayoutChild-struct" role="struct">
<title>GtkConstraintLayoutChild</title>
<indexterm zone="GtkConstraintLayoutChild-struct"><primary>GtkConstraintLayoutChild</primary></indexterm>
<programlisting language="C">typedef struct _GtkConstraintLayoutChild GtkConstraintLayoutChild;</programlisting>
<para>A <link linkend="GtkLayoutChild"><type>GtkLayoutChild</type></link> in a <link linkend="GtkConstraintLayout"><type>GtkConstraintLayout</type></link>.</para>
</refsect2>
<refsect2 id="GtkConstraintVflParserError" role="enum">
<title>enum GtkConstraintVflParserError</title>
<indexterm zone="GtkConstraintVflParserError"><primary>GtkConstraintVflParserError</primary></indexterm>
<para>Domain for VFL parsing errors.</para>
<refsect3 id="GtkConstraintVflParserError.members" role="enum_members">
<title>Members</title>
<informaltable role="enum_members_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="enum_members_name" colwidth="300px"/>
<colspec colname="enum_members_description"/>
<colspec colname="enum_members_annotations" colwidth="200px"/>
<tbody>
<row role="constant"><entry role="enum_member_name"><para id="GTK-CONSTRAINT-VFL-PARSER-ERROR-INVALID-SYMBOL:CAPS">GTK_CONSTRAINT_VFL_PARSER_ERROR_INVALID_SYMBOL</para></entry>
<entry role="enum_member_description"><para>Invalid or unknown symbol</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="GTK-CONSTRAINT-VFL-PARSER-ERROR-INVALID-ATTRIBUTE:CAPS">GTK_CONSTRAINT_VFL_PARSER_ERROR_INVALID_ATTRIBUTE</para></entry>
<entry role="enum_member_description"><para>Invalid or unknown attribute</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="GTK-CONSTRAINT-VFL-PARSER-ERROR-INVALID-VIEW:CAPS">GTK_CONSTRAINT_VFL_PARSER_ERROR_INVALID_VIEW</para></entry>
<entry role="enum_member_description"><para>Invalid or unknown view</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="GTK-CONSTRAINT-VFL-PARSER-ERROR-INVALID-METRIC:CAPS">GTK_CONSTRAINT_VFL_PARSER_ERROR_INVALID_METRIC</para></entry>
<entry role="enum_member_description"><para>Invalid or unknown metric</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="GTK-CONSTRAINT-VFL-PARSER-ERROR-INVALID-PRIORITY:CAPS">GTK_CONSTRAINT_VFL_PARSER_ERROR_INVALID_PRIORITY</para></entry>
<entry role="enum_member_description"><para>Invalid or unknown priority</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="GTK-CONSTRAINT-VFL-PARSER-ERROR-INVALID-RELATION:CAPS">GTK_CONSTRAINT_VFL_PARSER_ERROR_INVALID_RELATION</para></entry>
<entry role="enum_member_description"><para>Invalid or unknown relation</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>

</refsect1>

</refentry>
