summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMike Blumenkrantz <zmike@samsung.com>2019-09-10 15:44:29 +0200
committerXavi Artigas <xavierartigas@yahoo.es>2019-09-10 15:47:38 +0200
commit08e5b09d0a985d4d556c2a22dbae93ed9e45cfa4 (patch)
tree724d2b27e7fd0a3c46d7c8814c12991d27814066
parent5bae833123b249f6452ace5d748bf3da9a65e751 (diff)
efl_ui/popup: improve docs
Summary: this provides full documentation for the class and all properties ref T7717 Reviewers: segfaultxavi Reviewed By: segfaultxavi Subscribers: cedric, #reviewers, #committers Tags: #efl_docs Maniphest Tasks: T7717 Differential Revision: https://phab.enlightenment.org/D9882
-rw-r--r--src/lib/elementary/efl_ui_popup.eo107
1 files changed, 78 insertions, 29 deletions
diff --git a/src/lib/elementary/efl_ui_popup.eo b/src/lib/elementary/efl_ui_popup.eo
index f2d0208fa2..b3f22b7857 100644
--- a/src/lib/elementary/efl_ui_popup.eo
+++ b/src/lib/elementary/efl_ui_popup.eo
@@ -1,75 +1,124 @@
1parse efl_gfx_hint;
1enum @beta Efl.Ui.Popup_Align { 2enum @beta Efl.Ui.Popup_Align {
2 [[Popup alignment type.]] 3 [[This is the alignment method for positioning Popup widgets.]]
3 none = 0, [[Popup not aligned.]] 4 none = 0, [[Popup not aligned.]]
4 center, [[Popup aligned to center.]] 5 center, [[Popup is aligned to the center of its anchor object.]]
5 left, [[Popup aligned to left.]] 6 left, [[Popup's left edge is aligned to the left side of its anchor object.]]
6 right, [[Popup aligned to right.]] 7 right, [[Popup's right edge is aligned to the right side of its anchor object.]]
7 top, [[Popup aligned to top.]] 8 top, [[Popup's top is aligned to the top of its anchor object.]]
8 bottom [[Popup aligned to bottom.]] 9 bottom [[Popup's bottom is aligned to the bottom of its anchor object.]]
9} 10}
10 11
11class @beta Efl.Ui.Popup extends Efl.Ui.Layout_Base implements Efl.Content, Efl.Ui.Focus.Layer, 12class @beta Efl.Ui.Popup extends Efl.Ui.Layout_Base implements Efl.Content, Efl.Ui.Focus.Layer,
12 Efl.Ui.Widget_Scrollable_Content 13 Efl.Ui.Widget_Scrollable_Content
13{ 14{
14 [[EFL UI popup class]] 15 [[A styled container widget which overlays a window's contents.
16
17 The Popup widget is a theme-capable container which can be used for various purposes.
18 Regular contents can be set using the @Efl.Content interface, or basic scrollable contents
19 can be set through the @Efl.Ui.Widget_Scrollable_Content mixin API. For contents which
20 should be scrollable but require more fine-grained tuning, it may be necessary for users
21 to set up and provide their own scroller object such as @Efl.Ui.Scroller.
22
23 A Popup widget will create an overlay for the window contents. This overlay is an
24 @Efl.Ui.Popup_Part_Backwall object, which provides functionality for passing events
25 through to the main window while the Popup is active as well as the ability to set
26 background images for the Popup.
27
28 By default, a Popup is positioned by the user through the @Efl.Gfx.Entity.position property.
29 This behavior can be altered by using the @.align and @.anchor properties. Setting the
30 @Efl.Gfx.Entity.position property directly will unset both the @.align and @.anchor properties,
31 and vice versa.
32
33 By default, a Popup will size itself based on the minimum size of its contents through the
34 @Efl.Gfx.Hint interface. A Popup will never size itself smaller than the minimum size of its contents,
35 but by manually setting the @Efl.Gfx.Entity.size property or the @Efl.Gfx.Hint.hint_size_min property,
36 a larger size can be specified.
37
38 Users can set a given Popup widget to close automatically after a specified time using the @.closing_timeout
39 property.
40
41 For a Popup with a more specialized purpose, see @Efl.Ui.Alert_Popup.
42 ]]
15 methods { 43 methods {
16 @property align { 44 @property align {
17 [[Popup alignment.]] 45 [[The align property specifies a Popup's current positioning relative to its anchor.
46
47 When set, this property will override any user-provided value for
48 the widget's @Efl.Gfx.Entity.position property.
49 ]]
18 set { 50 set {
19 } 51 }
20 get { 52 get {
21 } 53 }
22 values { 54 values {
23 type: Efl.Ui.Popup_Align; [[Alignment type.]] 55 type: Efl.Ui.Popup_Align; [[Alignment of the Popup relative to its anchor.
56 The default is @Efl.Ui.Popup_Align.none.]]
24 } 57 }
25 } 58 }
26 @property closing_timeout { 59 @property closing_timeout {
27 [[Set the timeout seconds. 60 [[The closing_timeout property is the time after which the Popup widget will be automatically deleted.
28 After timeout seconds, popup will be deleted automatically. 61
62 The timer is initiated at the time when the popup is shown. If the value is changed
63 prior to the timer expiring, the existing timer will be deleted. If the new value is greater than $0,
64 a new timer will be created.
29 ]] 65 ]]
30 set { 66 set {
31 } 67 }
32 get { 68 get {
33 } 69 }
34 values { 70 values {
35 time: double; [[Timeout in seconds.]] 71 time: double; [[If greater than $0, the Popup will close automatically after the value in seconds.
72 The default is to not automatically delete the Popup.]]
36 } 73 }
37 } 74 }
38 @property anchor { 75 @property anchor {
39 [[Anchor object which sets this popup's position. 76 [[The anchor object is the reference object for positioning a Popup
40 If anchor object is moved or parent window is resized, the popup moves to the new position. 77 using the @.align and @.align_priority properties.
41 If anchor object is set to NULL, the popup stops following the anchor object. 78
42 When the popup is moved by using @Efl.Gfx.Entity.position.set, $anchor is set NULL. 79 A Popup will recalculate its alignment relative to its anchor and change its position when:
80 - the anchor object is moved (unless the anchor is a window)
81 - the anchor object is resized
82 - the Popup is resized
83 - the parent window is resized
84
85 If @.anchor.get returns NULL, the anchor is the parent window of the Popup.
86 If the anchor object is set to $NULL, the Popup will no longer recalculate its alignment or change
87 its position under any circumstance.
88 If the Popup is moved by using @Efl.Gfx.Entity.position.set, $anchor is set NULL.
43 ]] 89 ]]
44 set { 90 set {
45 } 91 }
46 get { 92 get {
47 } 93 }
48 values { 94 values {
49 anchor: Efl.Canvas.Object; [[The object which popup is following.]] 95 anchor: Efl.Canvas.Object; [[The object which Popup is following. By default this is $NULL.]]
50 } 96 }
51 } 97 }
52 @property align_priority { 98 @property align_priority {
53 [[Prioritized popup alignment. 99 [[This is the priority in which alignments will be tested using the anchor object if the value of @.align
54 100 is determined to be invalid. If a given alignment would result in the popup being partially or fully
55 In contrast to the @.align property, each alignment is tried in turn until one is found which allows 101 outside the visible area of the window, it is deemed invalid, and the next alignment is tested
56 the popup to be placed in the exact requested position relative to the @.anchor. 102 until either the priority list is exhausted or a usable alignment is found.
103
104 An alignment will also be deemed invalid if the popup occludes its anchor object,
105 except if @Efl.Ui.Popup_Align.center is specified.
57 ]] 106 ]]
58 set { 107 set {
59 } 108 }
60 get { 109 get {
61 } 110 }
62 values { 111 values {
63 first: Efl.Ui.Popup_Align; [[First alignment.]] 112 first: Efl.Ui.Popup_Align; [[First alignment. The default is @Efl.Ui.Popup_Align.top.]]
64 second: Efl.Ui.Popup_Align; [[Second alignment.]] 113 second: Efl.Ui.Popup_Align; [[Second alignment. The default is @Efl.Ui.Popup_Align.left.]]
65 third: Efl.Ui.Popup_Align; [[Third alignment.]] 114 third: Efl.Ui.Popup_Align; [[Third alignment. The default is @Efl.Ui.Popup_Align.right.]]
66 fourth: Efl.Ui.Popup_Align; [[Fourth alignment.]] 115 fourth: Efl.Ui.Popup_Align; [[Fourth alignment. The default is @Efl.Ui.Popup_Align.bottom.]]
67 fifth: Efl.Ui.Popup_Align; [[Fifth alignment.]] 116 fifth: Efl.Ui.Popup_Align; [[Fifth alignment. The default is @Efl.Ui.Popup_Align.center.]]
68 } 117 }
69 } 118 }
70 } 119 }
71 parts { 120 parts {
72 backwall: Efl.Ui.Popup_Part_Backwall; [[A backwall behind the popup.]] 121 backwall: Efl.Ui.Popup_Part_Backwall; [[A backwall behind the Popup.]]
73 } 122 }
74 implements { 123 implements {
75 Efl.Object.constructor; 124 Efl.Object.constructor;
@@ -84,7 +133,7 @@ class @beta Efl.Ui.Popup extends Efl.Ui.Layout_Base implements Efl.Content, Efl.
84 Efl.Part.part_get; 133 Efl.Part.part_get;
85 } 134 }
86 events { 135 events {
87 backwall,clicked: void; [[This is called whenever the user clicks back wall of popup.]] 136 backwall,clicked: void; [[This is called whenever the user clicks the backwall part of the Popup.]]
88 timeout: void; [[This is called when popup times out.]] 137 timeout: void; [[This is called when Popup times out.]]
89 } 138 }
90} 139}