bu5hm4n pushed a commit to branch master.
http://git.enlightenment.org/core/efl.git/commit/?id=f917f75c56167ab87654d4209a48174da64ea721
commit f917f75c56167ab87654d4209a48174da64ea721
Author: Mike Blumenkrantz <zm...@samsung.com>
Date: Tue Feb 11 10:10:57 2020 -0500
efl/gesture: improve docs
Reviewed-by: Xavi Artigas <xavierarti...@yahoo.es>
Differential Revision: https://phab.enlightenment.org/D11321
---
src/lib/evas/gesture/efl_canvas_gesture.eo | 5 ++-
src/lib/evas/gesture/efl_canvas_gesture_custom.eo | 3 ++
src/lib/evas/gesture/efl_canvas_gesture_manager.eo | 4 +-
.../evas/gesture/efl_canvas_gesture_recognizer.eo | 5 ++-
.../efl_canvas_gesture_recognizer_custom.eo | 4 ++
src/lib/evas/gesture/efl_canvas_gesture_types.eot | 47 +++++++++++-----------
6 files changed, 40 insertions(+), 28 deletions(-)
diff --git a/src/lib/evas/gesture/efl_canvas_gesture.eo
b/src/lib/evas/gesture/efl_canvas_gesture.eo
index 26aef89af8..9166f71ca2 100644
--- a/src/lib/evas/gesture/efl_canvas_gesture.eo
+++ b/src/lib/evas/gesture/efl_canvas_gesture.eo
@@ -27,7 +27,8 @@ abstract @beta Efl.Canvas.Gesture extends Efl.Object
}
@property hotspot {
[[Hotspot of the gesture currently being analyzed.
- The exact meaning depends on the gesture type.]]
+ The exact meaning depends on the gesture type, but by default it
+ reflects the current position of the last touch event.]]
get {
}
set {
@@ -43,7 +44,7 @@ abstract @beta Efl.Canvas.Gesture extends Efl.Object
set {
}
values {
- timestamp: uint;[[The time-stamp.]]
+ timestamp: uint;[[The time-stamp, valued in milliseconds.]]
}
}
@property touch_count {
diff --git a/src/lib/evas/gesture/efl_canvas_gesture_custom.eo
b/src/lib/evas/gesture/efl_canvas_gesture_custom.eo
index 6792d1ba8f..4e4f3ae3d0 100644
--- a/src/lib/evas/gesture/efl_canvas_gesture_custom.eo
+++ b/src/lib/evas/gesture/efl_canvas_gesture_custom.eo
@@ -7,6 +7,9 @@ class @beta Efl.Canvas.Gesture_Custom extends Efl.Canvas.Gesture
@[Efl.Canvas.Gesture_Events.gesture,custom] for a description of the
Custom gesture.
Application developers receive these objects inside a gesture event and
do not typically need to create their own.
+
+ Custom gesture recognizers which implement their own gesture properties
(e.g., gesture momentum or angle) must
+ inherit this class.
]]
c_prefix: efl_gesture_custom;
methods {
diff --git a/src/lib/evas/gesture/efl_canvas_gesture_manager.eo
b/src/lib/evas/gesture/efl_canvas_gesture_manager.eo
index 2dad839a3d..dc5ad82862 100644
--- a/src/lib/evas/gesture/efl_canvas_gesture_manager.eo
+++ b/src/lib/evas/gesture/efl_canvas_gesture_manager.eo
@@ -5,8 +5,8 @@ class @beta Efl.Canvas.Gesture_Manager extends Efl.Object
[[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.
+ This class defines methods to manage gesture recognizers and handles
passing input events
+ to the recognizers that it manages.
]]
c_prefix: efl_gesture_manager;
methods {
diff --git a/src/lib/evas/gesture/efl_canvas_gesture_recognizer.eo
b/src/lib/evas/gesture/efl_canvas_gesture_recognizer.eo
index 86fd424aa7..c9801629ff 100644
--- a/src/lib/evas/gesture/efl_canvas_gesture_recognizer.eo
+++ b/src/lib/evas/gesture/efl_canvas_gesture_recognizer.eo
@@ -14,7 +14,8 @@ abstract @beta Efl.Canvas.Gesture_Recognizer extends
Efl.Object
c_prefix: efl_gesture_recognizer;
methods {
@property type @pure_virtual {
- [[This property returns the type of gesture recognized by this
recognizer.]]
+ [[This property returns the type of gesture recognized by this
recognizer.
+ It must be implemented for the recognizer to function.]]
get {}
values {
type: Efl.Canvas.Gesture_Recognizer_Type; [[The gesture type to
recognize.]]
@@ -26,6 +27,8 @@ abstract @beta Efl.Canvas.Gesture_Recognizer extends
Efl.Object
Updates the state of the gesture object as required, and returns a
suitable result for the current recognition step.
+
+ This method must be implemented for the recognizer to function.
]]
params {
@in gesture: Efl.Canvas.Gesture; [[The gesture object.]]
diff --git a/src/lib/evas/gesture/efl_canvas_gesture_recognizer_custom.eo
b/src/lib/evas/gesture/efl_canvas_gesture_recognizer_custom.eo
index 1254d29b03..92f9786e75 100644
--- a/src/lib/evas/gesture/efl_canvas_gesture_recognizer_custom.eo
+++ b/src/lib/evas/gesture/efl_canvas_gesture_recognizer_custom.eo
@@ -2,6 +2,10 @@ abstract @beta Efl.Canvas.Gesture_Recognizer_Custom extends
Efl.Canvas.Gesture_R
{
[[This is the recognizer for Custom gestures.
See @Efl.Canvas.Gesture_Recognizer.
+
+ Custom-written recognizers must inherit this class.
+ They are responsible for managing and updating the state of the
recognized @Efl.Canvas.Gesture object inside
+ their implementation of the @Efl.Canvas.Gesture_Recognizer.recognize
method, which is required.
]]
c_prefix: efl_gesture_recognizer_custom;
methods {
diff --git a/src/lib/evas/gesture/efl_canvas_gesture_types.eot
b/src/lib/evas/gesture/efl_canvas_gesture_types.eot
index a5a876dc5b..eb5fc841ff 100644
--- a/src/lib/evas/gesture/efl_canvas_gesture_types.eot
+++ b/src/lib/evas/gesture/efl_canvas_gesture_types.eot
@@ -1,25 +1,26 @@
import eina_types;
import efl_input_types;
+import efl_canvas_gesture_events;
enum @beta Efl.Canvas.Gesture_Touch_State
{
[[ This enum type describes the state of a touch event. ]]
legacy: efl_gesture_touch_state;
- unknown = 0, [[Gesture Touch State unknown]]
- begin , [[First fingure touch down]]
- update, [[fingure touch update]]
- end, [[Last fingure touch up]]
+ unknown = 0, [[Touch state is unset.]]
+ begin, [[First touch point has just been added.]]
+ update, [[A touch point position has updated or other touch points
were added.]]
+ end, [[A touch point has been released.]]
}
enum @beta Efl.Canvas.Gesture_State
{
[[ This enum type describes the state of a gesture. ]]
legacy: efl_gesture_state;
- none = 0, [[No gesture state]]
- started = 1, [[A continuous gesture has started.]]
- updated, [[A gesture continues.]]
- finished, [[A gesture has finished.]]
- canceled, [[A gesture was canceled.]]
+ none = 0, [[No gesture state.]]
+ started = 1, [[A gesture has started.]]
+ updated, [[A gesture has triggered.]]
+ finished, [[A gesture has ended and has triggered.]]
+ canceled, [[A gesture has ended without triggering.]]
}
enum @beta Efl.Canvas.Gesture_Recognizer_Result
@@ -28,37 +29,37 @@ enum @beta Efl.Canvas.Gesture_Recognizer_Result
legacy: efl_gesture_recognizer_result;
ignore = 0x0001, [[The event does not change the state of the
recognizer.]]
- maybe = 0x0002, [[The event changed the internal state of the
recognizer, but it isn't clear yet if it is a gesture or not. The recognizer
needs to filter more events to decide.]]
+ maybe = 0x0002, [[The event changed the internal state of the
recognizer, but it isn't clear yet if it is a gesture or not. The recognizer
needs to filter more events to decide.]]
trigger = 0x0004, [[The gesture has been triggered]]
- finish = 0x0008, [[The gesture has been finished successfully.]]
+ finish = 0x0008, [[The gesture has been finished successfully and the
gesture triggered.]]
cancel = 0x0010, [[The event made it clear that it is not a gesture. If
the gesture recognizer was in Triggered state before, then the gesture is
canceled.]]
result_mask = 0x00ff, [[The gesture result mask]]
}
enum @beta Efl.Canvas.Gesture_Recognizer_Type
{
- [[ This enum type describes the state of a touch event. ]]
+ [[ This enum type describes the type of gesture recognized by a given
recognizer. ]]
legacy: efl_gesture_recognizer_type;
- tap = 0,
- double_tap,
- triple_tap,
- long_tap,
- momentum,
- flick,
- zoom,
- custom,
+ tap = 0, [[See @[Efl.Canvas.Gesture_Events.gesture,tap] ]]
+ double_tap, [[See @[Efl.Canvas.Gesture_Events.gesture,double_tap] ]]
+ triple_tap, [[See @[Efl.Canvas.Gesture_Events.gesture,triple_tap] ]]
+ long_tap, [[See @[Efl.Canvas.Gesture_Events.gesture,long_tap] ]]
+ momentum, [[See @[Efl.Canvas.Gesture_Events.gesture,momentum] ]]
+ flick, [[See @[Efl.Canvas.Gesture_Events.gesture,flick] ]]
+ zoom, [[See @[Efl.Canvas.Gesture_Events.gesture,zoom] ]]
+ custom, [[See @[Efl.Canvas.Gesture_Events.gesture,custom] ]]
}
struct @beta @c_name(Efl_Gesture_Touch_Point_Info)
Efl.Canvas.Gesture_Touch_Point_Info {
[[This struct represents the underlying data of a touch point.]]
pos: Eina.Position2D; [[The canvas position of the touch point data.]]
- pressed: bool; [[Whether this touch point is being pressed down.]]
- timestamp: uint; [[The timestamp of the touch point data.]]
+ pressed: bool; [[Whether this touch point is currently being pressed down.]]
+ timestamp: uint; [[The timestamp of the touch point data in milliseconds.]]
}
struct @beta @c_name(Efl_Gesture_Touch_Point_Data)
Efl.Canvas.Gesture_Touch_Point_Data {
[[This struct represents the state of a touch point.]]
- id: int; [[Touch id of the point.]]
+ id: int; [[Touch id of the point, where the first point is $0.]]
action: Efl.Pointer.Action; [[The last event with this point.]]
start: Efl.Canvas.Gesture_Touch_Point_Info; [[The start data for the touch
point.]]
prev: Efl.Canvas.Gesture_Touch_Point_Info; [[The previous data for the
touch point.]]
--
