gtk4/
constraint_layout.rs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
// Take a look at the license at the top of the repository in the LICENSE file.

use glib::translate::*;

use crate::{ffi, prelude::*, Constraint, ConstraintLayout, Widget};

impl ConstraintLayout {
    /// 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 [`ConstraintTarget`][crate::ConstraintTarget]
    /// instances to the symbolic view name inside the VFL.
    ///
    /// The VFL grammar is:
    ///
    /// ```text
    ///        <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:
    ///
    /// ```text
    ///   // 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`][crate::ConstraintLayout],
    ///   or guides
    ///
    /// # Returns
    ///
    /// the list of
    ///   [`Constraint`][crate::Constraint] instances that were added to the layout
    #[doc(alias = "gtk_constraint_layout_add_constraints_from_descriptionv")]
    #[doc(alias = "gtk_constraint_layout_add_constraints_from_description")]
    #[doc(alias = "add_constraints_from_descriptionv")]
    pub fn add_constraints_from_description<'a, W: IsA<Widget>>(
        &self,
        lines: impl IntoStrV,
        hspacing: i32,
        vspacing: i32,
        views: impl IntoIterator<Item = (&'a str, &'a W)>,
    ) -> Result<Vec<Constraint>, glib::Error> {
        unsafe {
            let mut err = std::ptr::null_mut();
            let hash_table = glib::ffi::g_hash_table_new_full(
                Some(glib::ffi::g_str_hash),
                Some(glib::ffi::g_str_equal),
                Some(glib::ffi::g_free),
                Some(glib::ffi::g_free),
            );

            for (key, widget) in views {
                let key_ptr: *mut libc::c_char = key.to_glib_full();
                glib::ffi::g_hash_table_insert(
                    hash_table,
                    key_ptr as *mut _,
                    widget.to_glib_full() as *mut _,
                );
            }

            lines.run_with_strv(|lines| {
                let out = ffi::gtk_constraint_layout_add_constraints_from_descriptionv(
                    self.to_glib_none().0,
                    lines.as_ptr() as *const _,
                    lines.len() as _,
                    hspacing,
                    vspacing,
                    hash_table,
                    &mut err,
                );
                if !err.is_null() {
                    Err(from_glib_full(err))
                } else {
                    Ok(FromGlibPtrContainer::from_glib_container(out))
                }
            })
        }
    }
}