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

docs: Update documentation on Gestures 

We need to keep in mind that the Manager and the Recognizers are not visible to the user.
The user only sees the events and the different Efl.Canvas.Gesture_* payloads.
This commit is contained in:
Xavi Artigas 2019-09-19 11:17:49 +02:00
parent 8a66c2eaea
commit ac531f881f
18 changed files with 170 additions and 133 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
src/lib/evas/gesture/efl_canvas_gesture.eo
View File

@ -1,44 +1,49 @@
import efl_canvas_gesture_types;
parse efl_gesture_events;
abstract @beta Efl.Canvas.Gesture extends Efl.Object
{
[[EFL Gesture abstract class
[[Base abstract class to support gesture-specific classes.
A gesture class defines a method that specific gesture event and privides information
about the gesture's type, state, and associated pointer information.
A gesture object holds the current state of that gesture (i.e. whether the gesture has
just been started, it is in progress or it has finished) along with any gesture-specific
information it needs (like the number of taps so far, to detect triple-taps, for example).
For cetain gesture types, additional methods are defined to provide meaningful gesture
information to the user.]]
Typically this class is not used directly, instead, some sub-class of it (like
@Efl.Canvas.Gesture_Tap or @Efl.Canvas.Gesture_Zoom) is retrieved from gesture events
(like @[Efl.Gesture.Events.gesture,tap] or @[Efl.Gesture.Events.gesture,zoom]).
]]
c_prefix: efl_gesture;
methods {
@property state {
[[This property holds the current state of the gesture.]]
[[Current state of the gesture, from initial detection to successful recognition.]]
get {
}
set {
}
values {
state: Efl.Canvas.Gesture_State; [[gesture state]]
state: Efl.Canvas.Gesture_State; [[State.]]
}
}
@property hotspot {
[[This property holds the hotspot of the current gesture.]]
[[Hotspot of the gesture currently being analyzed.
The exact meaning depends on the gesture type.]]
get {
}
set {
}
values {
hotspot: Eina.Position2D;[[hotspot co-ordinate]]
hotspot: Eina.Position2D;[[Hotspot coordinates.]]
}
}
@property timestamp {
[[This property holds the timestamp of the current gesture.]]
[[Moment when the gesture currently being analyzed started.]]
get {
}
set {
}
values {
timestamp: uint;[[The timestamp]]
timestamp: uint;[[The time-stamp.]]
}
}
}

8
src/lib/evas/gesture/efl_canvas_gesture_double_tap.eo
View File

@ -1,9 +1,9 @@
class @beta Efl.Canvas.Gesture_Double_Tap extends Efl.Canvas.Gesture
{
[[EFL Gesture Double Tap class
A gesture class defines a method that double tap gesture event and provides information
about the double tap gesture's type, state and associated pointer information.]]
[[Double-tap gesture class holding state information.
See @Efl.Canvas.Gesture to see what this state is and
@[Efl.Gesture.Events.gesture,double_tap] for a description of the Double-tap gesture.
]]
data: null;
c_prefix: efl_gesture_double_tap;
implements {

21
src/lib/evas/gesture/efl_canvas_gesture_flick.eo
View File

@ -2,20 +2,21 @@ import eina_types;
class @beta Efl.Canvas.Gesture_Flick extends Efl.Canvas.Gesture
{
[[EFL Gesture Flick class
This gesture class defines a method that flick gesture event and provides
information about the flick gesture's type, state, and associated pointer
information.]]
[[Flick gesture class holding state information.
See @Efl.Canvas.Gesture to see what this state is and
@[Efl.Gesture.Events.gesture,flick] for a description of the Flick gesture.
]]
c_prefix: efl_gesture_flick;
methods {
momentum_get {
[[Gets flick gesture momentum value]]
return: Eina.Vector2; [[The momentum vector]]
}
[[Gets flick gesture momentum value, this is, the direction in which the
pointer was flicked.]]
return: Eina.Vector2; [[The momentum vector.]]
}
angle_get {
[[Gets flick direction angle]]
return: double; [[The angle value]]
[[Gets flick gesture direction angle, this is, the angle in which the
pointer was flicked.]]
return: double; [[The angle value.]]
}
}
implements {

9
src/lib/evas/gesture/efl_canvas_gesture_long_tap.eo
View File

@ -1,10 +1,9 @@
class @beta Efl.Canvas.Gesture_Long_Tap extends Efl.Canvas.Gesture
{
[[EFL Gesture Long Tap class
This gesture class defines a method that long tap gesture event and provides
information about the long tap gesture's type, state and associated pointer
information.]]
[[Long-tap gesture class holding state information.
See @Efl.Canvas.Gesture to see what this state is and
@[Efl.Gesture.Events.gesture,long_tap] for a description of the Long-tap gesture.
]]
data: null;
c_prefix: efl_gesture_long_tap;
implements {

26
src/lib/evas/gesture/efl_canvas_gesture_manager.eo
View File

@ -1,41 +1,43 @@
class @beta Efl.Canvas.Gesture_Manager extends Efl.Object
{
[[EFL Gesture Manager class
[[This class keeps track of active @Efl.Canvas.Gesture_Recognizer objects.
For internal use only.
This gesture class defines methods that register and unregister a recognizer and
get a recognizer according to gesture event type.]]
get a recognizer according to gesture event type.
]]
c_prefix: efl_gesture_manager;
methods {
recognizer_register {
[[This function is called to register a new Efl.Canvas.Gesture_Recognizer]]
[[Registers a new @Efl.Canvas.Gesture_Recognizer.]]
params {
@in recognizer: Efl.Canvas.Gesture_Recognizer; [[The gesture recognizer object]]
@in recognizer: Efl.Canvas.Gesture_Recognizer; [[The gesture recognizer object.]]
}
}
recognizer_unregister {
[[This function is called to unregister a Efl.Canvas.Gesture_Recognizer]]
[[Unregisters an existing @Efl.Canvas.Gesture_Recognizer.]]
params {
@in recognizer: Efl.Canvas.Gesture_Recognizer; [[The gesture recognizer object]]
@in recognizer: Efl.Canvas.Gesture_Recognizer; [[The gesture recognizer object.]]
}
}
recognizer_get {
[[Gets event type's recognizer]]
[[Returns the event recognizer object associated with the given $gesture_type.]]
params {
@in gesture_type: Efl.Canvas.Gesture_Recognizer_Type; [[The gesture event type]]
@in gesture_type: Efl.Canvas.Gesture_Recognizer_Type; [[The gesture event type.]]
}
return: const(Efl.Canvas.Gesture_Recognizer); [[The gesture recognizer]]
return: const(Efl.Canvas.Gesture_Recognizer); [[The gesture recognizer.]]
}
@property config {
[[This property holds the config value for the recognizer]]
[[This property holds configuration values for the recognizer.]]
set {
}
get {
}
keys {
name: string; [[propery name]]
name: string; [[Property name.]]
}
values {
value: any_value_ptr; [[value of the property]]
value: any_value_ptr; [[Value of the property.]]
}
}
}

12
src/lib/evas/gesture/efl_canvas_gesture_momentum.eo
View File

@ -2,15 +2,15 @@ import eina_types;
class @beta Efl.Canvas.Gesture_Momentum extends Efl.Canvas.Gesture
{
[[EFL Gesture Momentum class
This gesture class defines a method to get momentum value of specific
gesture event such as flick.]]
[[Momentum gesture class holding state information.
See @Efl.Canvas.Gesture to see what this state is and
@[Efl.Gesture.Events.gesture,momentum] for a description of the Momentum gesture.
]]
c_prefix: efl_gesture_momentum;
methods {
momentum_get {
[[Gets momentum value]]
return: Eina.Vector2; [[The momentum vector]]
[[Gets the momentum value, this is, the direction in which the action occurred.]]
return: Eina.Vector2; [[The momentum vector.]]
}
}
implements {

38
src/lib/evas/gesture/efl_canvas_gesture_recognizer.eo
View File

@ -2,53 +2,53 @@ import efl_canvas_gesture_types;
abstract @beta Efl.Canvas.Gesture_Recognizer extends Efl.Object
{
[[EFL Gesture Recognizer abstract class
[[Base abstract class for Gesture Recognizers. For internal use only.
The gesture recognizer class grabs events that occur on the target
object that user register to see if a particluar gesture has occurred.
Gesture recognizers listen to events that occur on a target object
to see if a particular gesture has occurred.
Uesr can adjust the config value involved in gesture recognition
through the method provided by the gesture recognizer.
The default config values follow the system default config value.]]
Recognizer-specific configuration values can be modified through @.config.
Default configuration values are taken from the system's configuration.
]]
c_prefix: efl_gesture_recognizer;
methods {
add @pure_virtual {
[[This function is called to create a new Efl.Canvas.Gesture object for the given target]]
[[This function is called to create a new @Efl.Canvas.Gesture object for the given target.]]
params {
@in target: Efl.Object; [[The target widget]]
@in target: Efl.Object; [[The target canvas object.]]
}
return: Efl.Canvas.Gesture; [[Returns the Efl.Canvas.Gesture event object]]
return: Efl.Canvas.Gesture; [[Returns the gesture object that will be used to track this gesture.]]
}
recognize @pure_virtual {
[[Handles the given event for the watched object.
[[Analyzes the given $event and the current state of the $gesture object to see if the state
has to be modified. For example, to signal a complete gesture detection.
Updates the state of the gesture object as required, and returns a
suitable result for the current recognition step.
]]
params {
@in gesture: Efl.Canvas.Gesture; [[The gesture object]]
@in watched: Efl.Object; [[The watched object]]
@in event: Efl.Canvas.Gesture_Touch; [[The pointer event]]
@in gesture: Efl.Canvas.Gesture; [[The gesture object.]]
@in watched: Efl.Object; [[The target canvas object.]]
@in event: Efl.Canvas.Gesture_Touch; [[The pointer event being analyzed.]]
}
return: Efl.Canvas.Gesture_Recognizer_Result; [[Returns the Efl.Canvas.Gesture event object]]
return: Efl.Canvas.Gesture_Recognizer_Result; [[Returns the result of the analysis.]]
}
/* FIXME: This function is not used? */
reset {
[[This function is called by the framework to reset a given gesture.]]
params {
@in gesture: Efl.Canvas.Gesture; [[The gesture object]]
@in gesture: Efl.Canvas.Gesture; [[The gesture object.]]
}
}
@property config {
[[This property holds the config value for the recognizer]]
[[This property holds configuration values for the recognizer.]]
get {
}
keys {
name: string; [[propery name]]
name: string; [[Property name.]]
}
values {
value: any_value_ptr; [[value of the property]]
value: any_value_ptr; [[Value of the property.]]
}
}
}

12
src/lib/evas/gesture/efl_canvas_gesture_recognizer_double_tap.eo
View File

@ -1,19 +1,19 @@
class @beta Efl.Canvas.Gesture_Recognizer_Double_Tap extends Efl.Canvas.Gesture_Recognizer
{
[[EFL Gesture Recognizer Double Tap class
This gesture recognizer class grabs double tap gesture events that occur on
target object that user register.]]
[[This is the recognizer for Double-Tap gestures.
See @Efl.Canvas.Gesture_Double_Tap and @Efl.Canvas.Gesture_Recognizer.
For internal use only.
]]
c_prefix: efl_gesture_recognizer_double_tap;
methods {
@property timeout {
[[Sets the time between taps to be recognized as a double tap]]
[[Maximum time between taps to be recognized as a double tap.]]
set {
}
get {
}
values {
time: double; [[Allowed time gap value]]
time: double; [[Time in seconds.]]
}
}
}

8
src/lib/evas/gesture/efl_canvas_gesture_recognizer_flick.eo
View File

@ -1,9 +1,9 @@
class @beta Efl.Canvas.Gesture_Recognizer_Flick extends Efl.Canvas.Gesture_Recognizer
{
[[EFL Gesture Recognizer Flick Class
This gesture recognizer class grabs flick gesture events that occur on
the target object that user register.]]
[[This is the recognizer for Flick gestures.
See @Efl.Canvas.Gesture_Flick and @Efl.Canvas.Gesture_Recognizer.
For internal use only.
]]
c_prefix: efl_gesture_recognizer_flick;
implements {
Efl.Canvas.Gesture_Recognizer.add;

12
src/lib/evas/gesture/efl_canvas_gesture_recognizer_long_tap.eo
View File

@ -1,19 +1,19 @@
class @beta Efl.Canvas.Gesture_Recognizer_Long_Tap extends Efl.Canvas.Gesture_Recognizer
{
[[EFL Gesture Recognizer Long Tap class
This gesture recognizer class grabs long tap gesture events that occur
on the target that user register.]]
[[This is the recognizer for Long-tap gestures.
See @Efl.Canvas.Gesture_Long_Tap and @Efl.Canvas.Gesture_Recognizer.
For internal use only.
]]
c_prefix: efl_gesture_recognizer_long_tap;
methods {
@property timeout {
[[Sets the holding time to be recognized as a long tap.]]
[[Minimum holding time to be recognized as a long tap.]]
set {
}
get {
}
values {
time: double; [[Allowed time gap value]]
time: double; [[Time in seconds.]]
}
}
}

8
src/lib/evas/gesture/efl_canvas_gesture_recognizer_momentum.eo
View File

@ -1,9 +1,9 @@
class @beta Efl.Canvas.Gesture_Recognizer_Momentum extends Efl.Canvas.Gesture_Recognizer
{
[[EFL Gesture Recognizer Momentum class
This gesture recognizer class grabs monentum based gesture events such as
from flick on the target object that user register.]]
[[This is the recognizer for Momentum gestures.
See @Efl.Canvas.Gesture_Momentum and @Efl.Canvas.Gesture_Recognizer.
For internal use only.
]]
c_prefix: efl_gesture_recognizer_momentum;
implements {
Efl.Canvas.Gesture_Recognizer.add;

8
src/lib/evas/gesture/efl_canvas_gesture_recognizer_tap.eo
View File

@ -1,9 +1,9 @@
class @beta Efl.Canvas.Gesture_Recognizer_Tap extends Efl.Canvas.Gesture_Recognizer
{
[[EFL Gesture Recognizer Tap class
This gesture recognizer class grabs tap based gesture events that occur on
the target object that user register.]]
[[This is the recognizer for Tap gestures.
See @Efl.Canvas.Gesture_Tap and @Efl.Canvas.Gesture_Recognizer.
For internal use only.
]]
c_prefix: efl_gesture_recognizer_tap;
implements {
Efl.Canvas.Gesture_Recognizer.add;

24
src/lib/evas/gesture/efl_canvas_gesture_recognizer_triple_tap.eo
View File

@ -1,21 +1,21 @@
class @beta Efl.Canvas.Gesture_Recognizer_Triple_Tap extends Efl.Canvas.Gesture_Recognizer
{
[[EFL Gesture Recognizer Triple Tap class
This gesture recognizer class grabs triple tap gesture events that occur on the
target object that user register.]]
[[This is the recognizer for Triple-tap gestures.
See @Efl.Canvas.Gesture_Triple_Tap and @Efl.Canvas.Gesture_Recognizer.
For internal use only.
]]
c_prefix: efl_gesture_recognizer_triple_tap;
methods {
@property timeout {
[[Sets the time between taps to be recognized as a double tap.]]
[[Minimum time between each consecutive tap to be recognized as a triple tap.]]
set {
}
get {
}
values {
time: double; [[Time value.]]
}
}
}
get {
}
values {
time: double; [[Time in seconds.]]
}
}
}
implements {
Efl.Object.destructor;

8
src/lib/evas/gesture/efl_canvas_gesture_recognizer_zoom.eo
View File

@ -1,9 +1,9 @@
class @beta Efl.Canvas.Gesture_Recognizer_Zoom extends Efl.Canvas.Gesture_Recognizer
{
[[EFL Gesture Recognizer Zoom class
This gesture recognizer class grabs zoom gesture events that occur on the
target object that user register.]]
[[This is the recognizer for Zoom gestures.
See @Efl.Canvas.Gesture_Zoom and @Efl.Canvas.Gesture_Recognizer.
For internal use only.
]]
c_prefix: efl_gesture_recognizer_zoom;
implements {
Efl.Canvas.Gesture_Recognizer.add;

9
src/lib/evas/gesture/efl_canvas_gesture_tap.eo
View File

@ -1,10 +1,9 @@
class @beta Efl.Canvas.Gesture_Tap extends Efl.Canvas.Gesture
{
[[EFL Gesture Tap class
This gesture class defines a method that tap gesture event and provides
information about the tap gesture's type, state, and associated pointer
information.]]
[[Tap gesture class holding state information.
See @Efl.Canvas.Gesture to see what this state is and
@[Efl.Gesture.Events.gesture,tap] for a description of the Tap gesture.
]]
data: null;
c_prefix: efl_gesture_tap;
implements {

9
src/lib/evas/gesture/efl_canvas_gesture_triple_tap.eo
View File

@ -1,10 +1,9 @@
class @beta Efl.Canvas.Gesture_Triple_Tap extends Efl.Canvas.Gesture
{
[[EFL Gesture Triple Tap class
This gesture class defines a method that triple tap gesture event and provides
information about the triple tap gesture's type, state and associated pointer
information.]]
[[Triple-tap gesture class holding state information.
See @Efl.Canvas.Gesture to see what this state is and
@[Efl.Gesture.Events.gesture,triple_tap] for a description of the Triple-tap gesture.
]]
data: null;
c_prefix: efl_gesture_triple_tap;
implements {

20
src/lib/evas/gesture/efl_canvas_gesture_zoom.eo
View File

@ -1,19 +1,21 @@
class @beta Efl.Canvas.Gesture_Zoom extends Efl.Canvas.Gesture
{
[[EFL Gesture Zoom class
This gesture class defines methods to get zoom center point and zoom value
and provides information about the zoom gesture's type, state and associated
pointer information.]]
[[Zoom gesture class holding state information.
See @Efl.Canvas.Gesture to see what this state is and
@[Efl.Gesture.Events.gesture,zoom] for a description of the Flick gesture.
]]
c_prefix: efl_gesture_zoom;
methods {
radius_get {
[[Gets zoom center point reported to user]]
return: double; [[The radius value]]
[[Gets the current radius (i.e. the distance between the two fingers) of the gesture.]]
return: double; [[The radius value in pixels.]]
}
zoom_get {
[[Gets zoom value. (1.0 means no zoom)]]
return: double; [[The zoom value]]
[[Gets the current zoom value of the gesture. When the gesture begins, the finger
distance is recorded. When the distance becomes greater than the initial one, a
zoom value greater than $[1.0] is reported. When it becomes smaller, a zoom value
lesser than $[1.0] is reported.]]
return: double; [[The zoom value. $[1.0] means no zoom.]]
}
}
implements {

44
src/lib/evas/gesture/efl_gesture_events.eo
View File

@ -2,12 +2,42 @@ interface @beta Efl.Gesture.Events
{
event_prefix: efl;
events {
gesture,tap: Efl.Canvas.Gesture_Tap; [[Event for tap gesture]]
gesture,double_tap: Efl.Canvas.Gesture_Double_Tap; [[Event for double tap gesture]]
gesture,triple_tap: Efl.Canvas.Gesture_Triple_Tap; [[Event for triple tap gesture]]
gesture,long_tap: Efl.Canvas.Gesture_Long_Tap; [[Event for long tap gesture]]
gesture,momentum: Efl.Canvas.Gesture_Momentum; [[Event for momentum gesture]]
gesture,flick: Efl.Canvas.Gesture_Flick; [[Event for flick gesture]]
gesture,zoom: Efl.Canvas.Gesture_Zoom; [[Event for zoom gesture]]
gesture,tap: Efl.Canvas.Gesture_Tap; [[Emitted when a Tap gesture has been detected.
A Tap gesture consists of a touch of the screen (or click of the mouse) quickly followed by
a release. If the release happens too late a @[Efl.Gesture.Events.gesture,long_tap] event will be
emitted instead.
]]
gesture,double_tap: Efl.Canvas.Gesture_Double_Tap; [[Emitted when a Double-tap gesture has been detected.
A Double-tap gesture consists of two taps on the screen (or clicks of the mouse) in quick
succession. If the second one is delayed for too long they will be detected as two independent
@[Efl.Gesture.Events.gesture,tap] events.
]]
gesture,triple_tap: Efl.Canvas.Gesture_Triple_Tap; [[Emitted when a Triple-tap gesture has been detected.
A Triple-tap gesture consists of three taps on the screen (or clicks of the mouse) in quick
succession. If any of them is delayed for too long they will be detected as independent
@[Efl.Gesture.Events.gesture,tap] or @[Efl.Gesture.Events.gesture,double_tap] events.
]]
gesture,long_tap: Efl.Canvas.Gesture_Long_Tap; [[Emitted when a Long-tap gesture has been detected.
A Long-tap gesture consists of a touch of the screen (or click of the mouse) followed by a release
after some time. If the release happens too quickly a @[Efl.Gesture.Events.gesture,tap] event will be
emitted instead.
]]
gesture,momentum: Efl.Canvas.Gesture_Momentum; [[Emitted when a Momentum gesture has been detected.
A Momentum gesture consists of a quick displacement of the finger while touching the screen (or while
holding down a mouse button).
]]
gesture,flick: Efl.Canvas.Gesture_Flick; [[Emitted when a Flick gesture has been detected.
]]
gesture,zoom: Efl.Canvas.Gesture_Zoom; [[Emitted when a Zoom gesture has been detected.
A Zoom gesture consists of two fingers touching the screen and separating ("zoom in") or
getting closer ("zoom out" or "pinch").
This gesture cannot be performed with a mouse as it requires more than one pointer.
]]
}
}