From f917f75c56167ab87654d4209a48174da64ea721 Mon Sep 17 00:00:00 2001 From: Mike Blumenkrantz Date: Tue, 11 Feb 2020 10:10:57 -0500 Subject: [PATCH] efl/gesture: improve docs Reviewed-by: Xavi Artigas Differential Revision: https://phab.enlightenment.org/D11321 --- src/lib/evas/gesture/efl_canvas_gesture.eo | 5 +- .../evas/gesture/efl_canvas_gesture_custom.eo | 3 ++ .../gesture/efl_canvas_gesture_manager.eo | 4 +- .../gesture/efl_canvas_gesture_recognizer.eo | 5 +- .../efl_canvas_gesture_recognizer_custom.eo | 4 ++ .../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.]]