Method

GtkConstraintLayoutadd_constraints_from_descriptionv

Declaration [src]

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
)

Description [src]

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

This method is renamed to gtk_constraint_layout_add_constraints_from_description() in language bindings.

Parameters

lines

Type: An array of char*

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

The length of the array is specified in the n_lines argument.

The data is owned by the caller of the method.

Each element is a NUL terminated UTF-8 string.

n_lines

Type: gsize

The number of lines.

hspacing

Type: int

Default horizontal spacing value, or -1 for the fallback value.

vspacing

Type: int

Default vertical spacing value, or -1 for the fallback value.

views

Type: GHashTable

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.

The data is owned by the caller of the method.

error

Type: GError **

The return location for a recoverable error.

The argument can be NULL.

If the return location is not NULL, then you must initialize it to a NULL GError*.

The argument will be left initialized to NULL by the method if there are no errors.

In case of error, the argument will be set to a newly allocated GError; the caller will take ownership of the data, and be responsible for freeing it.

Return value

Type: A list of GtkConstraint*

The list of GtkConstraint instances that were added to the layout.

The caller of the method takes ownership of the returned data container, but not the data inside it.