From: duna.oh <duna.oh@samsung.com>
Date: Mon, 7 Oct 2024 09:21:04 +0000 (+0900)
Subject: Improve gesture documentation
X-Git-Tag: accepted/tizen/9.0/unified/20241108.065622~4
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=7a3a3636f7d36626eadd780cdebeaa18fb26eb79;p=platform%2Fcore%2Fapi%2Fefl-util.git

Improve gesture documentation

Change-Id: Ib6255b76a8b39f5d29308451d030f5acc8b5482c
---

diff --git a/doc/ui_efl_util_gesture_doc.h b/doc/ui_efl_util_gesture_doc.h
index 6eeff36..1a29dce 100644
--- a/doc/ui_efl_util_gesture_doc.h
+++ b/doc/ui_efl_util_gesture_doc.h
@@ -27,8 +27,60 @@
  *
  * @section CAPI_EFL_UTIL_GESTURE_MODULE_OVERVIEW Overview
  * The EFL UTIL API provides functions to grab / select / activate global gestures
- * and propagate these events to Ecore_Event.
+ * and propagate these events to server modules or applications.
  *
+ * @section CAPI_EFL_UTIL_GESTURE_MODULE_GRABBING_GESTURES Grabbing Gestures
+ * To receive global gesture events, you must grab the gestures that you want.
+ * You can grab gestures in the background (without a window).
+ * Each gesture can only be grabbed by 1 client at a time.
+ * For example, if a client grabs a 2-finger double tap gesture,
+ * other clients cannot grab the same gesture but can grab a 2-finger triple tap gesture.
+ * You can grab edge swipe, edge drag, tap, and palm cover gestures.<br>
+ *
+ * To grab gestures, follow these steps:
+ * 1. Create callbacks for gesture events.<br>
+ * 2. Create the efl_util_gesture_h structure and initialize the structure members with the efl_util_gesture_initialize() function.<br>
+ * 3. Define the gesture data to grab using the efl_util_gesture_xxx_new() and efl_util_gesture_xxx_size_set() functions.<br>
+ *    Setting a size is optional. If a size is not set, the gesture is grabbed within a full-size edge.<br>
+ * 4. To grab a gesture, use the efl_util_gesture_grab() function.<br>
+ * 5. Define the gesture event handlers.<br>
+ * 6. Run the main loop.<br>
+ * 7. When no longer needed, free the resources and deinitialize the efl_util_gesture_h structure.<br>
+ *
+ * @section CAPI_EFL_UTIL_GESTURE_MODULE_SELECTING_GESTURES Selecting Gestures
+ * Unlike grabbing, selecting a gesture requires a window.
+ * By selecting a gesture, you can detect gesture events when the selected window is active.
+ * Selecting has a higher priority than grabbing. Only the palm cover gesture can be selected.<br>
+ *
+ * To select a gesture, follow these steps:
+ * 1. Create the required callbacks: a callback for the gesture event and a callback for window destruction<br>
+ * 2. Create the efl_util_gesture_h structure and initialize the structure members with the efl_util_gesture_initialize() function.<br>
+ * 3. Define the gesture data to select.<br>
+ * 4. Create and show a window in which you want to select a gesture.<br>
+ * 5. To select the gesture, use the efl_util_gesture_select() function.<br>
+ * 6. Define the gesture event handler.<br>
+ * 7. Run the main loop.<br>
+ * 8. When no longer needed, free the resources and deinitialize the efl_util_gesture_h structure.<br>
+ *
+ * @section CAPI_EFL_UTIL_GESTURE_MODULE_DEACTIVATING_GESTURES Deactivating Gestures
+ * Gestures are activated by default.<br>
+ *
+ * To deactivate and re-activate gestures, follow these steps:
+ * 1. Create the efl_util_gesture_h structure and initialize the structure members with the efl_util_gesture_initialize() function.<br>
+ * 2. To deactivate a gesture type, use the efl_util_gesture_activate_set() function.<br>
+ * 3. Run the main loop.<br>
+ * 4. When no longer needed, re-activate the gestures and deinitialize the efl_util_gesture_h structure.<br>
+ *
+ * @section CAPI_EFL_UTIL_GESTURE_MODULE_DEACTIVATING_GESTURES_IN_A_WINDOW Deactivating Gestures in a Window
+ * Gestures are activated by default.<br>
+ *
+ * To deactivate and re-activate gestures in a window, follow these steps:
+ * 1. Create the window destruction callback.<br>
+ * 2. Create the efl_util_gesture_h structure and initialize the structure members with the efl_util_gesture_initialize() function.<br>
+ * 3. Create and show a window in which you want to deactivate a gesture.<br>
+ * 4. To deactivate a gesture type, use the efl_util_gesture_activate_set_on_window() function.<br>
+ * 5. Run the main loop.<br>
+ * 6. When no longer needed, re-activate the gestures, delete the window, and deinitialize the efl_util_gesture_h structure.<br>
  */
 
 #endif /* __TIZEN_UI_EFL_UTIL_GESTURE_DOC_H__ */