forked from enlightenment/efl
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
This commit is contained in:
parent
5bae833123
commit
08e5b09d0a
|
@ -1,75 +1,124 @@
|
|||
parse efl_gfx_hint;
|
||||
enum @beta Efl.Ui.Popup_Align {
|
||||
[[Popup alignment type.]]
|
||||
[[This is the alignment method for positioning Popup widgets.]]
|
||||
none = 0, [[Popup not aligned.]]
|
||||
center, [[Popup aligned to center.]]
|
||||
left, [[Popup aligned to left.]]
|
||||
right, [[Popup aligned to right.]]
|
||||
top, [[Popup aligned to top.]]
|
||||
bottom [[Popup aligned to bottom.]]
|
||||
center, [[Popup is aligned to the center of its anchor object.]]
|
||||
left, [[Popup's left edge is aligned to the left side of its anchor object.]]
|
||||
right, [[Popup's right edge is aligned to the right side of its anchor object.]]
|
||||
top, [[Popup's top is aligned to the top of its anchor object.]]
|
||||
bottom [[Popup's bottom is aligned to the bottom of its anchor object.]]
|
||||
}
|
||||
|
||||
class @beta Efl.Ui.Popup extends Efl.Ui.Layout_Base implements Efl.Content, Efl.Ui.Focus.Layer,
|
||||
Efl.Ui.Widget_Scrollable_Content
|
||||
{
|
||||
[[EFL UI popup class]]
|
||||
[[A styled container widget which overlays a window's contents.
|
||||
|
||||
The Popup widget is a theme-capable container which can be used for various purposes.
|
||||
Regular contents can be set using the @Efl.Content interface, or basic scrollable contents
|
||||
can be set through the @Efl.Ui.Widget_Scrollable_Content mixin API. For contents which
|
||||
should be scrollable but require more fine-grained tuning, it may be necessary for users
|
||||
to set up and provide their own scroller object such as @Efl.Ui.Scroller.
|
||||
|
||||
A Popup widget will create an overlay for the window contents. This overlay is an
|
||||
@Efl.Ui.Popup_Part_Backwall object, which provides functionality for passing events
|
||||
through to the main window while the Popup is active as well as the ability to set
|
||||
background images for the Popup.
|
||||
|
||||
By default, a Popup is positioned by the user through the @Efl.Gfx.Entity.position property.
|
||||
This behavior can be altered by using the @.align and @.anchor properties. Setting the
|
||||
@Efl.Gfx.Entity.position property directly will unset both the @.align and @.anchor properties,
|
||||
and vice versa.
|
||||
|
||||
By default, a Popup will size itself based on the minimum size of its contents through the
|
||||
@Efl.Gfx.Hint interface. A Popup will never size itself smaller than the minimum size of its contents,
|
||||
but by manually setting the @Efl.Gfx.Entity.size property or the @Efl.Gfx.Hint.hint_size_min property,
|
||||
a larger size can be specified.
|
||||
|
||||
Users can set a given Popup widget to close automatically after a specified time using the @.closing_timeout
|
||||
property.
|
||||
|
||||
For a Popup with a more specialized purpose, see @Efl.Ui.Alert_Popup.
|
||||
]]
|
||||
methods {
|
||||
@property align {
|
||||
[[Popup alignment.]]
|
||||
[[The align property specifies a Popup's current positioning relative to its anchor.
|
||||
|
||||
When set, this property will override any user-provided value for
|
||||
the widget's @Efl.Gfx.Entity.position property.
|
||||
]]
|
||||
set {
|
||||
}
|
||||
get {
|
||||
}
|
||||
values {
|
||||
type: Efl.Ui.Popup_Align; [[Alignment type.]]
|
||||
type: Efl.Ui.Popup_Align; [[Alignment of the Popup relative to its anchor.
|
||||
The default is @Efl.Ui.Popup_Align.none.]]
|
||||
}
|
||||
}
|
||||
@property closing_timeout {
|
||||
[[Set the timeout seconds.
|
||||
After timeout seconds, popup will be deleted automatically.
|
||||
[[The closing_timeout property is the time after which the Popup widget will be automatically deleted.
|
||||
|
||||
The timer is initiated at the time when the popup is shown. If the value is changed
|
||||
prior to the timer expiring, the existing timer will be deleted. If the new value is greater than $0,
|
||||
a new timer will be created.
|
||||
]]
|
||||
set {
|
||||
}
|
||||
get {
|
||||
}
|
||||
values {
|
||||
time: double; [[Timeout in seconds.]]
|
||||
time: double; [[If greater than $0, the Popup will close automatically after the value in seconds.
|
||||
The default is to not automatically delete the Popup.]]
|
||||
}
|
||||
}
|
||||
@property anchor {
|
||||
[[Anchor object which sets this popup's position.
|
||||
If anchor object is moved or parent window is resized, the popup moves to the new position.
|
||||
If anchor object is set to NULL, the popup stops following the anchor object.
|
||||
When the popup is moved by using @Efl.Gfx.Entity.position.set, $anchor is set NULL.
|
||||
[[The anchor object is the reference object for positioning a Popup
|
||||
using the @.align and @.align_priority properties.
|
||||
|
||||
A Popup will recalculate its alignment relative to its anchor and change its position when:
|
||||
- the anchor object is moved (unless the anchor is a window)
|
||||
- the anchor object is resized
|
||||
- the Popup is resized
|
||||
- the parent window is resized
|
||||
|
||||
If @.anchor.get returns NULL, the anchor is the parent window of the Popup.
|
||||
If the anchor object is set to $NULL, the Popup will no longer recalculate its alignment or change
|
||||
its position under any circumstance.
|
||||
If the Popup is moved by using @Efl.Gfx.Entity.position.set, $anchor is set NULL.
|
||||
]]
|
||||
set {
|
||||
}
|
||||
get {
|
||||
}
|
||||
values {
|
||||
anchor: Efl.Canvas.Object; [[The object which popup is following.]]
|
||||
anchor: Efl.Canvas.Object; [[The object which Popup is following. By default this is $NULL.]]
|
||||
}
|
||||
}
|
||||
@property align_priority {
|
||||
[[Prioritized popup alignment.
|
||||
|
||||
In contrast to the @.align property, each alignment is tried in turn until one is found which allows
|
||||
the popup to be placed in the exact requested position relative to the @.anchor.
|
||||
[[This is the priority in which alignments will be tested using the anchor object if the value of @.align
|
||||
is determined to be invalid. If a given alignment would result in the popup being partially or fully
|
||||
outside the visible area of the window, it is deemed invalid, and the next alignment is tested
|
||||
until either the priority list is exhausted or a usable alignment is found.
|
||||
|
||||
An alignment will also be deemed invalid if the popup occludes its anchor object,
|
||||
except if @Efl.Ui.Popup_Align.center is specified.
|
||||
]]
|
||||
set {
|
||||
}
|
||||
get {
|
||||
}
|
||||
values {
|
||||
first: Efl.Ui.Popup_Align; [[First alignment.]]
|
||||
second: Efl.Ui.Popup_Align; [[Second alignment.]]
|
||||
third: Efl.Ui.Popup_Align; [[Third alignment.]]
|
||||
fourth: Efl.Ui.Popup_Align; [[Fourth alignment.]]
|
||||
fifth: Efl.Ui.Popup_Align; [[Fifth alignment.]]
|
||||
first: Efl.Ui.Popup_Align; [[First alignment. The default is @Efl.Ui.Popup_Align.top.]]
|
||||
second: Efl.Ui.Popup_Align; [[Second alignment. The default is @Efl.Ui.Popup_Align.left.]]
|
||||
third: Efl.Ui.Popup_Align; [[Third alignment. The default is @Efl.Ui.Popup_Align.right.]]
|
||||
fourth: Efl.Ui.Popup_Align; [[Fourth alignment. The default is @Efl.Ui.Popup_Align.bottom.]]
|
||||
fifth: Efl.Ui.Popup_Align; [[Fifth alignment. The default is @Efl.Ui.Popup_Align.center.]]
|
||||
}
|
||||
}
|
||||
}
|
||||
parts {
|
||||
backwall: Efl.Ui.Popup_Part_Backwall; [[A backwall behind the popup.]]
|
||||
backwall: Efl.Ui.Popup_Part_Backwall; [[A backwall behind the Popup.]]
|
||||
}
|
||||
implements {
|
||||
Efl.Object.constructor;
|
||||
|
@ -84,7 +133,7 @@ class @beta Efl.Ui.Popup extends Efl.Ui.Layout_Base implements Efl.Content, Efl.
|
|||
Efl.Part.part_get;
|
||||
}
|
||||
events {
|
||||
backwall,clicked: void; [[This is called whenever the user clicks back wall of popup.]]
|
||||
timeout: void; [[This is called when popup times out.]]
|
||||
backwall,clicked: void; [[This is called whenever the user clicks the backwall part of the Popup.]]
|
||||
timeout: void; [[This is called when Popup times out.]]
|
||||
}
|
||||
}
|
||||
|
|
Loading…
Reference in New Issue