NorwayFun
/
efl
forked from enlightenment/efl
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Efl.Ui.Active_View: Update Docs 

This should clarify how the different components of this new widget are meant
to be used.

Reviewed-by: Marcel Hollerbach <mail@marcel-hollerbach.de>
Differential Revision: https://phab.enlightenment.org/D9044
This commit is contained in:
Xavi Artigas 2019-05-29 15:35:19 +00:00 committed by Marcel Hollerbach
parent 37266b93a5
commit 8113f3f565
3 changed files with 105 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
src/lib/elementary/efl_ui_active_view_container.eo
View File

@ -1,61 +1,88 @@
struct @beta Efl.Ui.Active_View.Transition_Event {
from : int; [[The id from where the transition started, -1 if not known]]
to : int; [[The id from where the transition started, -1 if not known]]
[[Information regarding transition events.]]
from : int; [[The view index from where the transition started, -1 if not known.]]
to : int; [[The view index to where the transition is headed, -1 if not known.]]
}
enum Efl.Ui.Active_View.Container_Gravity {
content = 0, [[In case the internal list of content is changed, then the $active_index will always point to the same content]]
index = 1, [[In case the internal list of content is changed, then the $active_index will keep its value]]
[[This enum controls the behavior of @Efl.Ui.Active_View.Container.active_index when indices are
shifted due to object addition or removal.]]
content = 0, [[When a view is added or removed from the container, the @Efl.Ui.Active_View.Container.active_index will
be adjusted as necessary so it points to the same view as before.]]
index = 1, [[When a view is added or removed from the container, the @Efl.Ui.Active_View.Container.active_index will
remain the same, possibly pointing to a different view.]]
}
class @beta Efl.Ui.Active_View.Container extends Efl.Ui.Layout_Base implements Efl.Pack_Linear
{
[[ The active view widget can be used to display the added content in some animated way. The details of the animation and way of displaying depends on the transition object.
The size of the displayed content can be controlled via $active_view_size. The content with the main attraction can be setted with $active_index.
[[The Active View widget is a container for other sub-widgets (views), where only one sub-widget is active at any given time.
Without a transition object this widget will just display the content with the id set with $active_index. On page changes,
Views are added using the @Efl.Pack_Linear interface and the active view is selected using @.active_index.
The way the different views are rendered can be customized through the @.view_manager object. For example, only the active view
might be shown, or it might be shown in a central position whereas the other views are displayed on the sides, or grayed-out.
All views are displayed with the same size, selected with @.active_view_size.
Additionally, the transition from one view to another can be animated. This animation is also controlled by the @.view_manager object.
Also, an indicator widget can be used to show a visual cue of how many views 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 view represents a "page" full
of other widgets. All these cases can be implemented with a different @.view_manager and use the same @Efl.Ui.Active_View.Container.
]]
c_prefix: efl_ui_active_view;
methods {
@property view_manager {
[[The transition object which defines the animation and exact position of the content]]
[[This object defines how views are rendered and animated.
If it is not set, only the active view is shown and transitions are instantaneous (not animated).
]]
values {
transition : Efl.Ui.Active_View.View_Manager @owned;
view_manager : Efl.Ui.Active_View.View_Manager @owned; [[The View Manager object or $NULL.]]
}
}
@property indicator {
[[A indicator object which can be used to display the state and position of the content in this widget
When this object here is set, the position of the indicator object is immidiatly called to the current position of the widget
[[An indicator object to use, which will display the current state of the Active View (number of views 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 @.view_manager.
]]
values {
indicator : Efl.Ui.Active_View.Indicator @owned;
indicator : Efl.Ui.Active_View.Indicator @owned; [[The Indicator object or $NULL.]]
}
}
@property active_index {
[[Selects which is the maincontent to display by this widget. The exact positioning depends on the $transition object]]
[[Currently active view among all the views added to this widget.
Changing this value might trigger an animation.
]]
values {
index: int;
index: int; [[Index of the active view, from 0 to the number of views - 1 (@Efl.Container.content_count - 1).]]
}
}
@property active_view_gravity {
[[active_view can be used to set the currently active viewed content.
[[When a new view is added to this widget, the indices for the previous views might change (for example,
when adding a view at the beginning of the list with @Efl.Pack_Linear.pack_begin all previous view's indices are increased by one).
This property can be used to switch_to the semantic of the function. If gravity is content, then newly added content will change the index, but keep the content. If the gravity is set to index, then the index will stay when new content is added, which might show new content.
This property controls whether the Active View should remain the same view as before (@Efl.Ui.Active_View.Container_Gravity.content)
or if the Active View should be moved to the one with the same index as before (@Efl.Ui.Active_View.Container_Gravity.index).
For example, @Efl.Ui.Active_View.Container_Gravity.index can be used to build a Stack, where @.active_index is always 0 and new
views are pushed onto the stack with @Efl.Pack_Linear.pack_begin and popped from the stack with @Efl.Pack_Linear.pack_unpack_at 0.
]]
values {
gravity : Efl.Ui.Active_View.Container_Gravity;
gravity : Efl.Ui.Active_View.Container_Gravity; [[Active View behavior when adding new views. Default is @Efl.Ui.Active_View.Container_Gravity.content.]]
}
}
@property active_view_size {
[[The size that is give to each content when displayed]]
[[The size to use when displaying the Active View. This is used by the @.view_manager to perform the rendering.
Views other than the Active one may or may not use this size.]]
values {
size: Eina.Size2D;
size: Eina.Size2D; [[Render size for the Active View. (-1, -1) means that all available space inside the container is used.]]
}
}
}
events {
transition,start : Efl.Ui.Active_View.Transition_Event;
transition,end : Efl.Ui.Active_View.Transition_Event;
transition,start : Efl.Ui.Active_View.Transition_Event; [[A transition animation has started.]]
transition,end : Efl.Ui.Active_View.Transition_Event; [[A transition animation has ended.]]
}
implements {
Efl.Object.constructor;

44
src/lib/elementary/efl_ui_active_view_indicator.eo
View File

@ -1,48 +1,54 @@
abstract @beta Efl.Ui.Active_View.Indicator extends Efl.Object {
[[Indicator object that is used by @Efl.Ui.Active_View.Container]]
[[Object used by @Efl.Ui.Active_View.Container to render an indication of the active view's position among
the rest of the container's views.
An example would be Android's little dots in the home screen.
]]
methods {
bind @pure_virtual {
[[Initial call to flush the required objects of the active view to the transition object
[[This method is called the first time an @Efl.Ui.Active_View.Indicator is assigned to an @Efl.Ui.Active_View.Container, binding them together.
This call can be used to setup the indicator part of $active_view.
This call can be used to setup the indicator part of the $active_view.
if there is a position of the widget, then after this call, $position_update will be called.
The Active View of the container (if there is any) will be informed to the indicator by a later call to @.position_update.
]]
params {
active_view : Efl.Ui.Active_View.Container;
active_view : Efl.Ui.Active_View.Container; [[The container to bind this indicator to.]]
}
}
content_add @pure_virtual {
[[Content has been added to the container passed in .bind. The $subobj is at position $index.
[[A $subobj has been added at position $index in the bound container.
While in the call, the $current_page property of the active_view might change.
If such a change is happening. No animation should be displayed, and the new state should be applied.
The manager should check the container's @Efl.Ui.Active_View.Container.active_index since indices might have
shifted due to the insertion of the new object.
]]
params {
subobj : Efl.Gfx.Entity;
index : int;
subobj : Efl.Gfx.Entity; [[The new object that has been added to the container.]]
index : int; [[The index of the new object in the container's list.]]
}
}
content_del @pure_virtual {
[[Content has been removed from the container passed in .bind. The $subobj at position $index is now removed.
[[The $subobj at position $index in the bound container has been removed.
While in the call, the $current_page property of the active_view might change.
If such a change is happening. No animation should be displayed, and the new state should be applied.
The manager should check the container's @Efl.Ui.Active_View.Container.active_index since indices might have
shifted due to the removal of the object.
]]
params {
subobj : Efl.Gfx.Entity;
index : int;
subobj : Efl.Gfx.Entity; [[The object being removed from the container.]]
index : int; [[The index this object had in the container's list.]]
}
}
position_update @pure_virtual {
[[The position between the content has been changed.
[[This method tells the indicator that @Efl.Ui.Active_View.Container.active_index has changed in the bound container.
The position is absolut and ranges from [-1,x + 1] where x is the number of contents in the active_view.
$position ranges from -1 to the number of views in the bound container (@Efl.Container.content_count).
Notice this allows moving to a position before the first view or past the last view, which might happen if the view
is thumb-scrolled out-of-bounds. Indicators can choose to render these out-of-bounds positions or not.
Values between two actaul positions must be expected as this is the way the animation of the transition object populates to the indicator
Fractional values indicate positions in-between two views and should be respected to obtain a smooth transition.
]]
params {
position : double; [[The position the transition object is currently in]]
position : double; [[The index of the active view, or a value in-between views if a transition is currently playing.]]
}
}
}

58
src/lib/elementary/efl_ui_active_view_view_manager.eo
View File

@ -1,65 +1,71 @@
abstract @beta Efl.Ui.Active_View.View_Manager extends Efl.Object {
[[Transition object which is used by active_view.
[[Manager object used by @Efl.Ui.Active_View.Container to handle rendering and animation of its views, and user interaction.
The transition object can display changes to the active view with animations.
This object can also implement behavior user interaction in a animation manner. For example: Mouse dragging content, to get to a new $current_page. If this is the case, such a user interaction should terminate with a call to $current_page. The position of the content should be exposed by emitting pos_update.
For instance, changes to the currently active view (@Efl.Ui.Active_View.Container.active_index) can be animated with a transition.
This object can also handle user interaction. For example, dragging the active view to one side to get to a different view (like an Android home screen).
Such user interactions should end up setting a new @Efl.Ui.Active_View.Container.active_index.
During a transition, the evolution of the current position should be exposed by emitting $pos_update events.
]]
methods {
bind @pure_virtual {
[[Initial call to flush the required objects of the active view to the transition object]]
[[This method is called the first time an @Efl.Ui.Active_View.View_Manager is assigned to an @Efl.Ui.Active_View.Container, binding them together.
The manager can read the current content of the container, subscribe to events, or do any initialization it requires.
]]
params {
active_view : Efl.Ui.Active_View.Container;
group : Efl.Canvas.Group;
active_view : Efl.Ui.Active_View.Container; [[The container to bind the view manager to.]]
group : Efl.Canvas.Group; [[The graphical group where the views should be added with @Efl.Canvas.Group.group_member_add and removed with @Efl.Canvas.Group.group_member_remove.]]
}
}
content_add @pure_virtual {
[[Content has been added to the container passed in .bind. The $subobj is at position $index.
[[A $subobj has been added at position $index in the bound container.
While in the call, the $current_page property of the active_view might change.
If such a change is happening. No animation should be displayed, and the new state should be applied.
The manager should check the container's @Efl.Ui.Active_View.Container.active_index since indices might have
shifted due to the insertion of the new object.
]]
params {
subobj : Efl.Gfx.Entity;
index : int;
subobj : Efl.Gfx.Entity; [[The new object that has been added to the container.]]
index : int; [[The index of the new object in the container's list.]]
}
}
content_del @pure_virtual {
[[Content has been removed from the container passed in .bind. The $subobj at position $index is now removed.
[[The $subobj at position $index in the bound container has been removed.
While in the call, the $current_page property of the active_view might change.
If such a change is happening. No animation should be displayed, and the new state should be applied.
The manager should check the container's @Efl.Ui.Active_View.Container.active_index since indices might have
shifted due to the removal of the object.
]]
params {
subobj : Efl.Gfx.Entity;
index : int;
subobj : Efl.Gfx.Entity; [[The object being removed from the container.]]
index : int; [[The index this object had in the container's list.]]
}
}
switch_to @pure_virtual {
[[Switch from one side to another, if there has been no side before, from is -1.
This function should, if the transition object supports this, display a animation.
[[Switch from one view to another. If there was no previous view, $from might be -1.
This function should display an animation if the @Efl.Ui.Active_View.View_Manager supports them.
]]
params {
from : int;
to : int;
from : int; [[Index of the starting view in the container's list. Might be -1 if unknown.]]
to : int; [[Index of the target view in the container's list.]]
}
}
@property view_size @pure_virtual {
[[Will be called whenever the page size changes]]
[[Will be called whenever the @Efl.Ui.Active_View.Container.active_view_size changes so the @Efl.Ui.Active_View.View_Manager can update itself.]]
set {
}
values {
size : Eina.Size2D; [[The size of the page, real coordiates at any time]]
size : Eina.Size2D; [[The new size of the views.]]
}
}
@property animation_enabled @pure_virtual {
[[This flag can be used to indicate that no animations should be done]]
[[This flag can be used to disable animations.]]
values {
enable : bool; [[$true if you want animations to happen, $false if otherwise]]
enable : bool; [[$true if you want animations to happen, $false otherwise.]]
}
}
}
events {
pos_update : double; [[The absolut position where the state of the content currently is. So if there is a animation from 2 to 3 the event will go from 2.0 to 3.0. If there is a $switch_to from 2 to 3, then this event should go in one direction from 2 to 3. Not following this, will result in a event to abort the transition, and instanciating a new one.]]
pos_update : double; [[Index of the view currently being displayed. Fractional values indicate a position in-between views.
For instance, when transitioning from view 2 to view 3, this event should be emitted with monotonically
increasing values ranging from 2.0 to 3.0.
Animations can perform any movement they want, but the reported $pos_update must move in the same direction.]]
}
}