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 {
|
enum @beta Efl.Ui.Popup_Align {
|
||||||
[[Popup alignment type.]]
|
[[This is the alignment method for positioning Popup widgets.]]
|
||||||
none = 0, [[Popup not aligned.]]
|
none = 0, [[Popup not aligned.]]
|
||||||
center, [[Popup aligned to center.]]
|
center, [[Popup is aligned to the center of its anchor object.]]
|
||||||
left, [[Popup aligned to left.]]
|
left, [[Popup's left edge is aligned to the left side of its anchor object.]]
|
||||||
right, [[Popup aligned to right.]]
|
right, [[Popup's right edge is aligned to the right side of its anchor object.]]
|
||||||
top, [[Popup aligned to top.]]
|
top, [[Popup's top is aligned to the top of its anchor object.]]
|
||||||
bottom [[Popup aligned to bottom.]]
|
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,
|
class @beta Efl.Ui.Popup extends Efl.Ui.Layout_Base implements Efl.Content, Efl.Ui.Focus.Layer,
|
||||||
Efl.Ui.Widget_Scrollable_Content
|
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 {
|
methods {
|
||||||
@property align {
|
@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 {
|
set {
|
||||||
}
|
}
|
||||||
get {
|
get {
|
||||||
}
|
}
|
||||||
values {
|
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 {
|
@property closing_timeout {
|
||||||
[[Set the timeout seconds.
|
[[The closing_timeout property is the time after which the Popup widget will be automatically deleted.
|
||||||
After timeout seconds, popup will be deleted automatically.
|
|
||||||
|
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 {
|
set {
|
||||||
}
|
}
|
||||||
get {
|
get {
|
||||||
}
|
}
|
||||||
values {
|
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 {
|
@property anchor {
|
||||||
[[Anchor object which sets this popup's position.
|
[[The anchor object is the reference object for positioning a Popup
|
||||||
If anchor object is moved or parent window is resized, the popup moves to the new position.
|
using the @.align and @.align_priority properties.
|
||||||
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.
|
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 {
|
set {
|
||||||
}
|
}
|
||||||
get {
|
get {
|
||||||
}
|
}
|
||||||
values {
|
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 {
|
@property align_priority {
|
||||||
[[Prioritized popup alignment.
|
[[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
|
||||||
In contrast to the @.align property, each alignment is tried in turn until one is found which allows
|
outside the visible area of the window, it is deemed invalid, and the next alignment is tested
|
||||||
the popup to be placed in the exact requested position relative to the @.anchor.
|
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 {
|
set {
|
||||||
}
|
}
|
||||||
get {
|
get {
|
||||||
}
|
}
|
||||||
values {
|
values {
|
||||||
first: Efl.Ui.Popup_Align; [[First alignment.]]
|
first: Efl.Ui.Popup_Align; [[First alignment. The default is @Efl.Ui.Popup_Align.top.]]
|
||||||
second: Efl.Ui.Popup_Align; [[Second alignment.]]
|
second: Efl.Ui.Popup_Align; [[Second alignment. The default is @Efl.Ui.Popup_Align.left.]]
|
||||||
third: Efl.Ui.Popup_Align; [[Third alignment.]]
|
third: Efl.Ui.Popup_Align; [[Third alignment. The default is @Efl.Ui.Popup_Align.right.]]
|
||||||
fourth: Efl.Ui.Popup_Align; [[Fourth alignment.]]
|
fourth: Efl.Ui.Popup_Align; [[Fourth alignment. The default is @Efl.Ui.Popup_Align.bottom.]]
|
||||||
fifth: Efl.Ui.Popup_Align; [[Fifth alignment.]]
|
fifth: Efl.Ui.Popup_Align; [[Fifth alignment. The default is @Efl.Ui.Popup_Align.center.]]
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
parts {
|
parts {
|
||||||
backwall: Efl.Ui.Popup_Part_Backwall; [[A backwall behind the popup.]]
|
backwall: Efl.Ui.Popup_Part_Backwall; [[A backwall behind the Popup.]]
|
||||||
}
|
}
|
||||||
implements {
|
implements {
|
||||||
Efl.Object.constructor;
|
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;
|
Efl.Part.part_get;
|
||||||
}
|
}
|
||||||
events {
|
events {
|
||||||
backwall,clicked: void; [[This is called whenever the user clicks back wall of popup.]]
|
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.]]
|
timeout: void; [[This is called when Popup times out.]]
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
Loading…
Reference in New Issue