summaryrefslogtreecommitdiff
path: root/src/lib/efl/interfaces/efl_gfx_size_hint.eo
blob: 85905ffe257cba5cd86c09912c5771e1d0e60c21 (plain)
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
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
import efl_gfx_types;

const Efl.Gfx.Size.Hint.Expand: double = 1.0;
   [[Use with $Efl.Gfx.Size.Hint.weight.]]
const Efl.Gfx.Size.Hint.Fill: double = -1.0;
   [[Special value for $Efl.Gfx.Size.Hint.align.]]

interface Efl.Gfx.Size.Hint
{
   [[Efl graphics size hint interface]]
   event_prefix: efl_gfx;
   methods {
      @property hint_base {
         [[Base size for objects with sizing restrictions.

           This is not a size enforcement in any way, it's just a hint
           that should be used whenever appropriate.

           @.hint_base + N x @.hint_step is what is calculated for object
           sizing restrictions.

           See also @.hint_step.
         ]]
         values {
            w: int; [[The base width.]]
            h: int; [[The base height.]]
         }
      }
      @property hint_step {
         [[Step size for objects with sizing restrictions.

           This is not a size enforcement in any way, it's just a hint
           that should be used whenever appropriate.

           Set this to for an object to scale up by steps and not continuously.

           @.hint_base + N x @.hint_step is what is calculated for object
           sizing restrictions.
         ]]
         values {
            w: int; [[The stepping width (0 disables).]]
            h: int; [[The stepping height (0 disables).]]
         }
      }
      @property hint_aspect {
         [[Defines the aspect ratio to respect when scaling this object.

           The aspect ratio is defined as the width / height ratio of the
           object. Depending on the object and its container, this hint may
           or may not be fully respected.

           If any of the given aspect ratio terms are 0, the object's container
           will ignore the aspect and scale this object to occupy the whole
           available area, for any given policy.
         ]]
         /*
         @image html any-policy.png
         @image html aspect-control-none-neither.png
         @image html aspect-control-both.png
         @image html aspect-control-horizontal.png
         */
         values {
            mode: Efl.Gfx.Size.Hint.Aspect; [[Mode of interpretation.]]
            w: int; [[Width]]
            h: int; [[Height]]

            /* FIXME: do we want min/max like Edje instead??
            min: double; [[Default: 0.0 (no preference).]]
            max: double @optional; [[Default: 0.0, may be ignored.]]
            */
         }
      }
      @property hint_max {
         [[Hints on the object's maximum size.

           This is not a size enforcement in any way, it's just a hint
           that should be used whenever appropriate.

           The object container is in charge of fetching this property and
           placing the object accordingly.

           Values -1 will be treated as unset hint components, when
           queried by managers.

           Note: Smart objects (such as elementary) can have their own
           size hint policy. So calling this API may or may not affect
           the size of smart objects.
         ]]
         values {
            sz: Eina.Size2D; [[Maximum size (hint) in pixels, (-1, -1) by
               default for canvas objects).]]
         }
      }
      @property hint_min {
         [[Hints on the object's minimum size.

           This is not a size enforcement in any way, it's just a hint
           that should be used whenever appropriate. The object container
           is in charge of fetching this property and placing the object
           accordingly.

           Value 0 will be treated as unset hint components, when queried
           by managers.

           Note: This property is meant to be set by applications and not by
           EFL itself. Use this to request a specific size (treated as minimum
           size).
         ]]
         values {
            sz: Eina.Size2D; [[Minimum size (hint) in pixels.]]
         }
      }
      @property hint_restricted_min {
         [[Internal hints for an object's minimum size.

           This is not a size enforcement in any way, it's just a hint
           that should be used whenever appropriate.

           Values 0 will be treated as unset hint components, when
           queried by managers.

           Note: This property is internal and meant for widget developers to
           define the absolute minimum size of the object. EFL itself sets
           this size internally, so any change to it from an application
           might be ignored. Use @.hint_min instead.
         ]]
         set @protected {
            [[This function is protected as it is meant for widgets to indicate
              their "intrinsic" minimum size.
            ]]
         }
         get {
            [[Get the "intrinsic" minimum size of this object.]]
         }
         values {
            sz: Eina.Size2D; [[Minimum size (hint) in pixels.]]
         }
      }
      @property hint_combined_min {
         [[Read-only minimum size combining both @.hint_restricted_min and
           @.hint_min size hints.

           @.hint_restricted_min is intended for mostly internal usage
           and widget developers, and @.hint_min is intended to be
           set from application side. @.hint_combined_min combines both values
           by taking their repective maximum (in both width and height), and
           is used internally to get an object's minimum size.
         ]]
         get {}
         values {
            w: int; [[Integer to use as the minimum width hint.]]
            h: int; [[Integer to use as the minimum height hint.]]
         }
      }
      @property hint_margin {
         [[Hints for an object's margin or padding space.

           This is not a size enforcement in any way, it's just a hint
           that should be used whenever appropriate.

           The object container is in charge of fetching this property and
           placing the object accordingly.

           Note: Smart objects (such as elementary) can have their own
           size hint policy. So calling this API may or may not affect
           the size of smart objects.
         ]]
         /*
         @image html padding-hints.png
         */
         values {
            l: int; [[Integer to specify left padding.]]
            r: int; [[Integer to specify right padding.]]
            t: int; [[Integer to specify top padding.]]
            b: int; [[Integer to specify bottom padding.]]
         }
      }
      @property hint_weight {
         [[Hints for an object's weight.

           This is a hint on how a container object should resize a given
           child within its area. Containers may adhere to the simpler
           logic of just expanding the child object's dimensions to fit
           its own (see the @Efl.Gfx.Size.Hint.Expand helper weight macro) or
           the complete one of taking each child's weight hint as real
           weights to how much of its size to allocate for them in each
           axis. A container is supposed to, after normalizing the
           weights of its children (with weight  hints), distribut
           the space it has to layout them by those factors -- most
           weighted children get larger in this process than the least
           ones.

           Accepted values are zero or positive values. Some containers might
           use this hint as a boolean, but some others might consider it as a
           proportion, see documentation of each container.

           Note: Default weight hint values are 0.0, for both axis.
         ]]
         values {
            x: double; [[Non-negative double value to use as horizontal weight hint.]]
            y: double; [[Non-negative double value to use as vertical weight hint.]]
         }
      }
      @property hint_align {
         [[Hints for an object's alignment.

           These are hints on how to align an object inside the
           boundaries of a container/manager. Accepted values are in
           the 0.0 to 1.0 range, with the special value @Efl.Gfx.Size.Hint.Fill
           used to specify "justify" or "fill" by some users. In this
           case, maximum size hints should be enforced with higher
           priority, if they are set. Also, any padding hint set on
           objects should add up to the alignment space on the final
           scene composition.

           See documentation of possible users: in Evas, they are the
           \@ref Evas_Object_Box "box" and \@ref Evas_Object_Table "table"
           smart objects.

           For the horizontal component, 0.0 means to the left, 1.0
           means to the right. Analogously, for the vertical component,
           0.0 to the top, 1.0 means to the bottom.

           This is not a size enforcement in any way, it's just a hint
           that should be used whenever appropriate.

           Note: Default alignment hint values are 0.5, for both axes.
         ]]
         /*
         @image html alignment-hints.png
         */
         values {
            x: double; [[Double, ranging from 0.0 to 1.0 or with the special value
                         @Efl.Gfx.Size.Hint.Fill, to use as horizontal alignment hint.]]
            y: double; [[Double, ranging from 0.0 to 1.0 or with the special value
                         @Efl.Gfx.Size.Hint.Fill, to use as vertical alignment hint.]]
         }
      }
   }
   events {
      change,size,hints; [[Object size hints changed.]]
   }
}