summaryrefslogtreecommitdiff
path: root/src/lib/elementary/elm_widget.eo
blob: a3bf4f1ca6c33eade2768a4c486f5feff2cd63d7 (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
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
function Efl.Ui.Scrollable_On_Show_Region {
   [[Function pointer for on show region hook]]
   params {
      @in obj: Efl.Canvas.Object; [[Canvas object]]
      @in region: Eina.Rect; [[Showed region]]
   }
};

struct Efl.Ui.Widget.Focus_State {
   [[All relevant fields needed for the current state of focus registeration]]
   manager : Efl.Ui.Focus.Manager; [[The manager where the widget is registered in]]
   parent : Efl.Ui.Focus.User; [[The parent the widget is using as logical parent]]
   logical : bool; [[$true if this is registered as logical currently]]
}

/* ATTENTION: Rename to Efl.Ui.Widget is imminent. */
abstract Elm.Widget (Efl.Canvas.Group, Efl.Access,
                     Efl.Access.Component, Efl.Ui.Focus.User, Efl.Part,
                     Efl.Ui.Focus.Object, Efl.Ui.Base, Efl.Ui.Cursor,
                     Efl.Ui.Translatable)
{
   [[Elementary widget abstract class]]
   legacy_prefix: elm_widget;
   eo_prefix: efl_ui_widget;
   event_prefix: efl_ui_widget;
   data: Efl_Ui_Widget_Data;
   methods {
      @property resize_object @protected {
         [[This is the internal canvas object managed by a widget.

           This property is protected as it is meant for widget implementations
           only, to set and access the internal canvas object. Do use this
           function unless you're implementing a widget.
         ]]
         set {
            [[Sets the new resize object for this widget.]]
         }
         values {
            sobj: Efl.Canvas.Object @nullable;
               [[A canvas object (often a @Efl.Canvas.Layout object).]]
         }
      }
      @property disabled {
         [[Whether the widget is enabled (accepts and reacts to user inputs).

           Each widget may handle the disabled state differently, but overall
           disabled widgets shall not respond to any input events. This is
           $false by default, meaning the widget is enabled.
         ]]
         set {
            [[Enables or disables this widget.

              Disabling a widget will disable all its children recursively,
              but only this widget will be marked as disabled internally.
            ]]
         }
         get {
            [[Returns whether the widget is disabled.

              This will return $true if any widget in the parent hierarchy
              is disabled. Re-enabling that parent may in turn change the
              disabled state of this widget.
            ]]
         }
         values {
            disabled: bool(false); [[$true if the widget is disabled.]]
         }
      }
      @property style {
         [[The widget style to use.

           Styles define different look and feel for widgets, and may provide
           different parts for layout-based widgets. Styles vary from widget
           to widget and may be defined by other themes by means of extensions
           and overlays.

           The style can only be set before @Efl.Object.finalize, which means
           at construction time of the object (inside $efl_add in C).
         ]]
         set @protected {
            [[Can only be called during construction, before finalize.]]
            return: Efl.Ui.Theme.Apply(0);
               [[Whether the style was successfully applied or not, see
                 the values of @Efl.Ui.Theme.Apply for more information.]]
         }
         get {
            [[Returns the current style of a widget.]]
         }
         values {
            style: string;
               [[Name of the style to use. Refer to each widget's documentation
                 for the available style names, or to the themes in use.]]
         }
      }
      widget_event @protected {
         [[Virtual function handling input events on the widget.

           This method should return $true if the event has been processed.
           Only key down, key up and pointer wheel events will be propagated
           through this function.

           It is common for the event to be also marked as processed as in
           @Efl.Input.Event.processed, if this operation was successful. This
           makes sure other widgets will not also process this input event.
         ]]
         params {
            @cref eo_event: Efl.Event;
               [[EO event struct with an Efl.Input.Event as info.]]
            @in source: Efl.Canvas.Object;
               [[Source object where the event originated. Often same as this.]]
         }
         return: bool; [[$true on success, $false otherwise]]
         legacy: null;
      }
      @property orientation_mode_disabled {
         [[Whether the widget's automatic orientation is disabled or not.

           Orientation mode is used for widgets to change their style or send
           signals based on the canvas rotation (i.e. the window orientation).
           If the orientation mode is enabled, the widget will emit signals
           such as "elm,state,orient,N" where $N is one of 0, 90, 180, 270,
           depending on the window orientation. Such signals may be handled by
           the theme in order to provide a different look for the widget based
           on the canvas orientation.

           By default orientation mode is enabled, which means this property
           is $false.
         ]]
         values {
            disabled: bool(false); [[$true if the orientation mode is disabled.]]
         }
      }
      // FIXME: focus_allow? can_focus? focusable?
      @property focus_allow {
         [[The ability for a widget to be focused.

           Unfocusable objects do nothing when programmatically focused. The
           nearest focusable parent object the one really getting focus. Also,
           when they receive mouse input, they will get the event, but not take
           away the focus from where it was previously.

           Note: Objects which are meant to be interacted with by input events
           are created able to be focused, by default. All the others are not.

           This property's default value depends on the widget (eg. a box is
           not focusable, but a button is).
         ]]
         set {
            legacy: elm_widget_can_focus_set;
         }
         get {
            legacy: elm_widget_can_focus_get;
         }
         values {
            can_focus: bool; [[Whether the object is focusable.]]
         }
      }
      @property widget_parent @protected {
         [[The internal parent of this widget.

           @Elm.Widget objects have a parent hierarchy that may differ slightly
           from their @Efl.Object or @Efl.Canvas.Object hierarchy. This is
           meant for internal handling.

           See also @.widget_top.
         ]]
         set {}
         get {
            legacy: elm_widget_parent_get; /* internal in legacy */
         }
         values {
            parent: Elm.Widget @nullable; [[Widget parent object]]
         }
      }
      @property widget_top {
         [[Root widget in the widget hierarchy.

           This returns the top widget, in terms of widget hierarchy. This is
           usually a window (@Efl.Ui.Win). This function walks the list of
           @.widget_parent.

           If this widget has no parent (in terms of widget hierarchy) this
           will return $null.

           Note: This may not be a display manager window in case of nested
           canvases. If a "real" window is required, then you might want to
           verify that the returned object is a $Efl.Ui.Win_Inlined, and then
           get $Efl.Ui.Win_Inlined.inlined_parent to find an object in the
           master window.

           See also @.widget_parent.
         ]]
         get {
            legacy: elm_widget_top_get; /* internal in legacy */
         }
         values {
            top: Elm.Widget; [[Top widget, usually a window.]]
         }
      }

      /* Accessibility */
      @property access_info {
         [[Accessibility information.

           This is a replacement string to be read by the accessibility
           text-to-speech engine, if accessibility is enabled by configuration.
           This will take precedence over the default text for this object,
           which means for instance that the label of a button won't be read
           out loud, instead $txt will be read out.
         ]]
         values {
            txt: string @nullable; [[Accessibility text description.]]
         }
      }
      on_access_activate @protected @beta {
         [[Hook function called when widget is activated through accessibility.

           This meant to be overridden by subclasses to support accessibility.
           This is an unstable API.
         ]]
         params {
            @in act: Efl.Ui.Activate; [[Type of activation.]]
         }
         return: bool; [[$true on success, $false otherwise]]
         legacy: null; /* FIXME: legacy API does extra work */
      }
      on_access_update @protected @beta {
         [[Hook function called when accessibility is changed on the widget.

           This meant to be overridden by subclasses to support accessibility.
           This is an unstable API.
         ]]
         params {
            @in enable: bool; [[$true if accessibility is enabled.]]
         }
         legacy: null; /* FIXME: legacy API does extra work */
      }

      /* Internal hooks. */
      widget_sub_object_add @protected {
         [[Virtual function handling sub objects being added.

           Sub objects can be any canvas object, not necessarily widgets.

           See also @.widget_parent.
         ]]
         params {
            @in sub_obj: Efl.Canvas.Object;
               [[Sub object to be added. Not necessarily a widget itself.]]
         }
         return: bool; [[Indicates if the operation succeeded.]]
         legacy: elm_widget_sub_object_add;
      }
      widget_sub_object_del @protected {
         [[Virtual function handling sub objects being removed.

           Sub objects can be any canvas object, not necessarily widgets.

           See also @.widget_parent.
         ]]
         params {
            @in sub_obj: Efl.Canvas.Object;
               [[Sub object to be removed. Should be a child of this widget.]]
         }
         return: bool; [[Indicates if the operation succeeded.]]
         legacy: elm_widget_sub_object_del;
      }
      on_orientation_update @protected {
         [[Virtual function handling canvas orientation changes.

           This method will be called recursively from the top widget (the
           window) to all the children objects whenever the window rotation
           is changed. The given $rotation will be one of 0, 90, 180, 270 or
           the special value -1 if @.orientation_mode_disabled is $true.

           If @.orientation_mode_disabled is $false, the default implementation
           will emit the signal "elm,state,orient,$R" will be emitted (where $R
           is the rotation angle in degrees).

           Note: This function may be called even if the orientation has not
           actually changed, like when a widget needs to be reconfigured.

           See also @Efl.Orientation.orientation.set.
         ]]
         params {
            rotation: int; [[Orientation in degrees: 0, 90, 180, 270 or -1 if
               @.orientation_mode_disabled is $true.]]
         }
      }
      on_disabled_update @protected {
         [[Virtual function called when the widget becomes disabled.

           This may be triggered even if this widget is not disabled, as the
           parent widget could be disabled and propagate its state.
         ]]
         params {
            disabled: bool; [[The new value of @.disabled.]]
         }
         return: bool; [[Indicates if the operation succeeded.]]
      }
      theme_apply @protected {
         [[Virtual function called when the widget needs to re-apply its theme.

           This may be called when the object is first created, or whenever
           the widget is modified in any way that may require a reload of the
           theme. This may include but is not limited to scale, theme, or
           mirrored mode changes.

           Note: even widgets not based on layouts may override this method
           to handle widget updates (scale, mirrored mode, etc...).
         ]]
         return: Efl.Ui.Theme.Apply; [[Indicates success, and if the current
                                       theme or default theme was used.]]
      }
      on_focus_update @protected {
         [[Virtual function handling focus in/out events on the widget]]
         params {
            /* FIXME: EO API is not supposed to have any widget item!!! */
            @in item: Elm.Widget.Item @nullable; [[Widget]]
         }
         return: bool; [[$true if this widget can handle focus, $false otherwise]]
      }

      /* Scroll API. */
      @property on_show_region_hook @protected {
         [[Hook function called when the @.show_region is changed.

           See also @.show_region.
         ]]
         set {}
         values {
            func: Efl.Ui.Scrollable_On_Show_Region @nullable; [[Region hook function]]
         }
      }
      @property show_region @protected {
         [[Region inside the widget to show.

           See also @.on_show_region_hook.
         ]]
         set {
            [[Request parent scrollers to pan around so that this region
              of the widget becomes visible.

              If $force is $true this will trigger scroller changes and
              the @.on_show_region_hook to be called even if the region is
              unchanged.
            ]]
            values {
               region: Eina.Rect; [[The region to show.]]
               force: bool; [[Set to $true to force show even if unchanged.]]
            }
         }
         get {
            [[Returns the current region to show.]]
            values {
               region: Eina.Rect; [[The region to show.]]
            }
         }
      }

      /* FIXME: Scroll API. Not sure how those APIs should be exposed with
       * the new scrollable API. */
      scroll_hold_push {
         [[Push scroll hold]]
      }
      scroll_hold_pop {
         [[Pop scroller hold]]
      }
      scroll_freeze_push {
         [[Push scroller freeze]]
      }
      scroll_freeze_pop {
         [[Pop scroller freeze]]
      }

      /* Region of interest */
      @property interest_region @protected {
         [[Region of interest inside this widget, that should be given
           priority to be visible inside a scroller.

           When this widget or one of its subwidgets is given focus, this
           region should be shown, which means any parent scroller should
           attempt to display the given area of this widget. For instance, an
           entry given focus should scroll to show the text cursor if that
           cursor moves. In this example, this region defines the relative
           geometry of the cursor within the widget.

           Note: The region is relative to the top-left corner of the widget,
           i.e. X,Y start from 0,0 to indicate the top-left corner of the
           widget. W,H must be greater or equal to 1 for this region to be
           taken into account, otherwise it is ignored.

           See also @.interest_region_mode
         ]]
         get {
            legacy: elm_widget_focus_region_get;
         }
         values {
            region: Eina.Rect;
               [[The relative region to show. If width or height is <= 0 it
                 will be ignored, and no action will be taken.]]
         }
      }
      @property interest_region_mode {
         [[Defines how @.show_region should be calculated.

           It is up to the implementation of @.show_region.get to take this
           value into account (or ignore it).
         ]]
         get {
            legacy: elm_widget_focus_region_show_mode_get;
         }
         set {
            legacy: elm_widget_focus_region_show_mode_set;
         }
         values {
            mode: Efl.Ui.Interest_Region_Mode;
               [[Whether to show a specific item or the widget as a whole.]]
         }
      }

      /* Focus highlight (visual focus rectangle) properties */
      @property focus_highlight_geometry @protected {
         [[The rectangle region to be highlighted on focus.

           This is a rectangle region where the focus highlight should be
           displayed.
         ]]
         get {
            [[This is a read-only property.]]
         }
         values {
            region: Eina.Rect; [[The rectangle area.]]
         }
      }
      @property focus_highlight_enabled {
         [[Whether focus highlight is enabled or not.

           As of EFL 1.21 focus highlight properties apply to a single window,
           not a single widget. As a consequence, calls to this function may
           be forwarded to the parent window. Future versions of EFL may
           implement widget-specific focus highlight properties.

           See also @.widget_top.
           See also @.focus_highlight_style.
           See also @.focus_highlight_animate.
         ]]
         set {
            [[Set the enabled status for the focus highlight in a window.

              This function will enable or disable the focus highlight,
              regardless of the global setting for it.
            ]]
         }
         get {
            [[Get the enabled value of the focus highlight for this window.]]
         }
         values {
            enabled: bool; [[The enabled value for the highlight.]]
         }
      }
      @property focus_highlight_style {
         [[Control the widget focus highlight style.

           If $style is $null, the default will be used.

           As of EFL 1.21 focus highlight properties apply to a single window,
           not a single widget. As a consequence, calls to this function may
           be forwarded to the parent window. Future versions of EFL may
           implement widget-specific focus highlight properties.

           See also @.widget_top.
           See also @.focus_highlight_enabled.
           See also @.focus_highlight_animate.
         ]]
         set {
            /* FIXME: This is async... success here means nothing. */
            return: bool; [[$true on success, $false otherwise.]]
         }
         get {
         }
         values {
            style: string @nullable; [[The name of the focus highlight style.]]
         }
      }
      @property focus_highlight_animate {
         [[Whether focus highlight should animate or not.

           As of EFL 1.21 focus highlight properties apply to a single window,
           not a single widget. As a consequence, calls to this function may
           be forwarded to the parent window. Future versions of EFL may
           implement widget-specific focus highlight properties.

           See also @.widget_top.
           See also @.focus_highlight_style.
           See also @.focus_highlight_enabled.
         ]]
         set {
            [[Set the animate status for the focus highlight for this window.

              This function will enable or disable the animation of focus
              highlight.
            ]]
         }
         get {
            [[Get the animate value of the focus highlight for this window.]]
         }
         values {
            animate: bool; [[The enabled value for the highlight animation.]]
         }
      }
      @property focus_move_policy @beta {
         [[The widget's focus move policy.]]
         values {
            policy: Efl.Ui.Focus.Move_Policy; [[Focus move policy]]
         }
      }
      @property focus_move_policy_automatic @beta {
         [[Control the widget's focus_move_policy mode setting.

           @since 1.18]]
         values {
            automatic: bool; [[$true to follow system focus move policy change,
                               $false otherwise]]
         }
      }

      /* FIXME: No more items in EO API */
      @property focused_item @beta {
         get {
            [[Get the focused widget item.]]
            return: Elm.Widget.Item; [[Focused item]]
         }
      }

      /* Focus Manager API */
      focus_state_apply @protected {
         [[Register focus with the given configuration.

           The implementation can feel free to change the logical flag as it
           wants, but other than that it should strictly keep the configuration.

           The implementation in elm.widget updates the current state into what
           is passed as configured state, respecting manager changes,
           registeration and unregistration based on if it should be registered
           or unregistered.

           A manager field that is $null means that the widget should not or was
           not registered.
         ]]
         params {
            @in current_state : Efl.Ui.Widget.Focus_State;
               [[The focus manager to register with.]]
            @inout configured_state : Efl.Ui.Widget.Focus_State;
               [[The evalulated Focus state that should be used.]]
            @in redirect : Elm.Widget;
               [[A redirect that will be set by the elm.widget implementation.]]
         }
         return: bool; [[Returns whether the widget is registered or not.]]
      }
      focus_manager_create @protected {
         [[If the widget needs a focus manager, this function will be called.

           It can be used and overriden to inject your own manager or set
           custom options on the focus manager.
         ]]
         params {
            @in root: Efl.Ui.Focus.Object; [[The logical root object for focus.]]
         }
         return: Efl.Ui.Focus.Manager; [[The focus manager.]]
      }
   }
   parts {
      shadow: Efl.Ui.Widget.Part_Shadow;
   }
   implements {
      class.constructor;
      Efl.Object.constructor;
      Efl.Object.finalize;
      Efl.Object.destructor;
      Efl.Object.provider_find;
      Efl.Object.debug_name_override;
      Efl.Gfx.Color.color { set; }
      Efl.Gfx.visible { set; }
      Efl.Gfx.position { set; }
      Efl.Gfx.size { set; }
      Efl.Gfx.scale { set; get; }
      Efl.Canvas.Object.clip { set; }
      Efl.Canvas.Object.no_render { set; }
      Efl.Canvas.Object.is_frame_object { set; }
      Efl.Canvas.Group.group_calculate;
      Efl.Canvas.Group.group_member_del;
      Efl.Canvas.Group.group_member_add;
      Efl.Access.name { get; }
      Efl.Access.state_set { get; }
      Efl.Access.children { get; }
      Efl.Access.parent { get; }
      Efl.Access.attributes { get; }
      Efl.Access.Component.focus_grab;
      Efl.Ui.Focus.User.focus_manager { get; }
      Efl.Ui.Focus.User.focus_parent { get; }
      Efl.Ui.Focus.Object.focus_geometry { get; }
      Efl.Ui.Focus.Object.focus { set; }
      Efl.Ui.Base.mirrored { get; set; }
      Efl.Ui.Base.mirrored_automatic { get; set; }
      Efl.Ui.Cursor.cursor { get; set; }
      Efl.Ui.Cursor.cursor_style { get; set; }
      Efl.Ui.Cursor.cursor_theme_search_enabled { get; set; }
      Efl.Ui.Translatable.translation_update; [[This implements the calls to $gettext() and $text_set().]]
      Efl.Part.part; [[Returns @Efl.Ui.Widget.Part.]]
   }
   events {
      moved; [[Called when widget moved]]
      language,changed; [[Called when widget language changed]]
      access,changed; [[Called when accessibility changed]]
   }
}