summaryrefslogtreecommitdiff
path: root/src/lib/elementary/efl_ui_spotlight_container.eo
blob: bb39fd2fc6d2e0c8d327f469ae0db16190463129 (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
struct  @beta Efl.Ui.Spotlight.Transition_Event {
   [[Information regarding transition events.]]
   from : int; [[The index from where the transition started, -1 if not known.]]
   to : int; [[The index to where the transition is headed, -1 if not known.]]
}

class @beta Efl.Ui.Spotlight.Container extends Efl.Ui.Layout_Base implements Efl.Pack_Linear
{
   [[The Spotlight widget is a container for other sub-widgets, where only one sub-widget is active at any given time.

     Sub-widgets are added using the @Efl.Pack_Linear interface and the active one (the one in the "spotlight") is
     selected using @.active_element.

     The way the different sub-widgets are rendered can be customized through the @.spotlight_manager object.
     For example, only the active sub-widget might be shown, or it might be shown in a central position whereas the
     other sub-widgets are displayed on the sides, or grayed-out.
     All sub-widgets are displayed with the same size, selected with @.spotlight_size.

     Additionally, the transition from one sub-widget to another can be animated.
     This animation is also controlled by the @.spotlight_manager object.

     Also, an indicator widget can be used to show a visual cue of how many sub-widgets are there and which one is the
     active one.

     This class can be used to create other widgets like Pagers, Tabbed pagers or Stacks, where each sub-widget
     represents a "page" full of other widgets. All these cases can be implemented with a different
     @.spotlight_manager and use the same @Efl.Ui.Spotlight.Container.
   ]]
   c_prefix: efl_ui_spotlight;
   methods {
      @property spotlight_manager {
        [[This object defines how sub-widgets are rendered and animated.
          If it is not set, only the active sub-widget is shown and transitions are instantaneous (not animated).
        ]]
        values {
          spotlight_manager : Efl.Ui.Spotlight.Manager @move; [[The Spotlight Manager object or $NULL.]]
        }
      }
      @property indicator {
        [[An indicator object to use, which will display the current state of the spotlight (number of sub-widgets
          and active one).
          When this object is set, it is immediately updated to reflect the current state of the widget.
          Its location inside the container is controlled by the @.spotlight_manager.
        ]]
        values {
          indicator : Efl.Ui.Spotlight.Indicator @move; [[The Indicator object or $NULL.]]
        }
      }
      @property active_element {
         [[Currently active sub-widget (the one with the spotlight) among all the sub-widgets added to this widget

           Changing this value might trigger an animation.
         ]]
         values {
            element : Efl.Ui.Widget; [[Sub-widget that has the spotlight.
            The element has to be added prior to this call via the @Efl.Pack_Linear interface.]]
         }
      }
      @property spotlight_size {
         [[The size to use when displaying the Sub-Widget which has the spotlight.
           This is used by the @.spotlight_manager to perform the rendering.
           Sub-Widgets other than the Active one may or may not use this size.]]
         values {
            size: Eina.Size2D; [[Render size for the spotlight.
                                 (-1, -1) means that all available space inside the container can be used.]]
         }
      }
      push @beta {
         [[Packs a new sub-widget before @.active_element, and move the spotlight there.

           This is the same behavior as a push operation on a stack.

           An animation might be triggered to give the new sub-widget the spotlight and come into position.
         ]]
         params {
            widget : Efl.Gfx.Entity; [[Sub-Widget to add and set to be the spotlight sub-widget.]]
         }
      }
      pop @beta {
         [[Removes the sub-widget that has the spotlight from the widget.

           The sub-widgets behind it naturally flow down so the next one gets the spotlight.
           This is the same behavior as a pop operation on a stack.
           When combined with @.push you don't have to worry about @.active_element since only the first sub-widget is
           manipulated.

           An animation might be triggered to give the new sub-widget the spotlight, come into position and the old
           one disappear.

           The removed sub-widget can be returned to the caller or deleted (depending on $delete_on_transition_end).
         ]]
         params {
            deletion_on_transition_end : bool; [[If $true, then the object will be deleted before resolving the future,
                                                 and a NULL pointer is the value of the future.
                                                 $false if no operation should be applied to it.]]
         }
         return : future<Efl.Gfx.Entity>; [[This Future gets resolved when any transition animation finishes and the
                                            popped sub-widget is ready for collection.
                                            If there is no animation, the Future resolves immediately.
                                            If $deletion_on_transition_end is $true then this widget will destroy the
                                            popped sub-widget and the Future will contain no Value.
                                            Otherwise, the caller becomes the owner of the sub-widget contained in the
                                            Future and must dispose of it appropriately. ]]
      }
   }
   events {
      transition,start : Efl.Ui.Spotlight.Transition_Event; [[A transition animation has started.]]
      transition,end : Efl.Ui.Spotlight.Transition_Event; [[A transition animation has ended.]]
   }
   implements {
      Efl.Object.constructor;
      Efl.Object.finalize;
      Efl.Object.invalidate;
      Efl.Container.content_count;
      Efl.Container.content_iterate;
      Efl.Pack.pack_clear;
      Efl.Pack.unpack_all;
      Efl.Pack.unpack;
      Efl.Pack.pack;
      Efl.Pack_Linear.pack_begin;
      Efl.Pack_Linear.pack_end;
      Efl.Pack_Linear.pack_before;
      Efl.Pack_Linear.pack_after;
      Efl.Pack_Linear.pack_at;
      Efl.Pack_Linear.pack_content_get;
      Efl.Pack_Linear.pack_index_get;
      Efl.Pack_Linear.pack_unpack_at;
   }
}