edje/dragable - Docs and example for dragable parts API.

SVN revision: 62076

legacy/edje/doc/examples.dox

@@ -11,6 +11,7 @@
  * @li @ref Example_Edje_Signals_Messages
  * @li @ref tutorial_edje_box
  * @li @ref tutorial_edje_box2
+ * @li @ref tutorial_edje_drag
  */
 
 /**
@@ -399,6 +400,88 @@
  * @example edje-box2.c
  */
 
+/**
+ * @page tutorial_edje_drag Dragable parts example
+ *
+ * This example shows how to manipulate a dragable part through the
+ * edje_object_part_drag API.
+ *
+ * First, in the edc code, we are declaring a part which will be our movable
+ * part, called "knob". It is a normal rectangle, which contains a block called
+ * "dragable", that will define the area where this rectangle can be moved, and
+ * in which axis it can be moved.
+ *
+ * This is our part:
+ *
+ * @dontinclude drag.edc
+ * @skip // drag_area
+ * @skip part
+ * @until example/knob
+ * @until example/knob
+ *
+ * Notice that it defines, through its @c "x:" and @c "y:' properties, that the
+ * part will be only moved on the y axis (vertical). Check the edc reference
+ * docs for more info about this.
+ *
+ * Now, in our example C code, we just do the same as on the other examples,
+ * setting some global data on a structure, load the edje file and so:
+ *
+ * @dontinclude edje-drag.c
+ * @skip value changed
+ * @skip }
+ * @skip int
+ * @until evas_object_show(app.edje)
+ *
+ * We want to use the drag_page and drag_step functions, and in order to do so we
+ * need to define the step size and page size of our dragable part. They are
+ * defined as float values which represent a portion of the entire size of the
+ * dragable area:
+ *
+ * @until drag page step
+ *
+ * We are going to use the keyboard to move the @c knob part, through the key
+ * down callback @c _bg_key_down, but we also want to know when the user has
+ * moved the knob by using the mouse (which is possible, since we defined that
+ * this part will receive mouse events). Thus, we set a callback for the signal
+ * "drag", which comes from the dragable part:
+ *
+ * @until _knob_moved_cb
+ *
+ * Now, let's take a look at our key down callback:
+ *
+ * @dontinclude edje-drag.c
+ * @skip _canvas_resize_cb
+ * @skip static
+ * @until unhandled key
+ * @until }
+ *
+ * On this callback we define that the user will use the "up" and "down" arrows
+ * to move the dragable part, respectively, -1.0 and 1.0 times the step size.
+ * And that the "Page Up" (Prior) and "Page Down" (Next) keys will move -1.0 and
+ * 1.0 times the page size. Both of these will occur on the vertical axis, since
+ * we pass 0.0 as value to the respective horizontal axis parameters. And our
+ * dragable part also only supports being moved in the vertical axis (defined in
+ * the edc).
+ *
+ * We also define that the "m" key will be used to explicitly position the knob
+ * part in the middle of the dragable area.
+ *
+ * And here is the callback for the @c "drag" signal that is received from the
+ * theme:
+ *
+ * @until }
+ *
+ * The example's window should look like this picture:
+ *
+ * @image html edje-drag-example.png
+ * @image rtf edje-drag-example.png
+ * @image latex edje-drag-example.eps
+ *
+ * The full source code follows:
+ * @include edje-drag.c
+ * @example edje-drag.c
+ */
+
 /**
  * @page Example_Edje_Signals_Messages Edje signals and messages
  *

legacy/edje/src/examples/Makefile.am

@@ -8,6 +8,7 @@ EDCS = basic.edc \
 	text.edc \
 	table.edc \
 	box.edc \
+	drag.edc \
 	signals-messages.edc \
 	color-class.edc
 
@@ -37,6 +38,7 @@ pkglib_PROGRAMS += \
 	edje-table \
 	edje-box \
 	edje-box2 \
+	edje-drag\
 	edje-signals-messages \
 	edje-color-class
 
@@ -64,6 +66,7 @@ files_DATA += \
 	$(srcdir)/edje-table.c \
 	$(srcdir)/edje-box.c \
 	$(srcdir)/edje-box2.c \
+	$(srcdir)/edje-drag.c \
 	$(srcdir)/edje-signals-messages.c \
 	$(srcdir)/edje-color-class.c
 endif
@@ -76,5 +79,6 @@ EXTRA_DIST = $(EDCS) \
 	$(srcdir)/edje-table.c \
 	$(srcdir)/edje-box.c \
 	$(srcdir)/edje-box2.c \
+	$(srcdir)/edje-drag.c \
 	$(srcdir)/edje-signals-messages.c \
 	$(srcdir)/edje-color-class.c

legacy/edje/src/examples/drag.edc

@@ -0,0 +1,91 @@
+collections {
+   group {
+      name: "example/group";
+
+      min: 160 160;
+
+      parts {
+         part {
+            name: "bg";
+            type: RECT;
+
+            mouse_events: 0;
+
+            description {
+               state: "default" 0.0;
+            }
+         } // bg
+
+         part {
+            name: "title";
+            type: TEXT;
+            mouse_events: 0;
+
+            description {
+               state: "default" 0.0;
+               color: 0 0 0 255;
+               rel1 {
+                  relative: 0.0 0.0;
+                  offset: 0 0;
+                  to: "bg";
+               }
+               rel2 {
+                  relative: 1.0 0.2;
+                  offset: -1 -1;
+                  to: "bg";
+               }
+               text {
+                  text: "Drag Example";
+                  size: 16;
+                  font: "sans";
+                  min: 1 1;
+               }
+            }
+         }
+
+         part {
+            name: "drag_area";
+            type: RECT;
+
+            mouse_events: 0;
+
+            description {
+               state: "default" 0.0;
+               color: 0 0 0 255;
+               rel1 {
+                  relative: 0.5 0.3;
+                  offset: -5 0;
+               }
+
+               rel2 {
+                  relative: 0.5 0.9;
+                  offset: 4 0;
+               }
+            }
+         } // drag_area
+
+         part {
+            name: "example/knob";
+            type: RECT;
+
+            mouse_events: 1;
+
+            dragable {
+               confine: "drag_area";
+               x: 0 0 0;
+               y: 1 1 0;
+            }
+
+            description {
+               state: "default" 0.0;
+
+               color: 255 0 0 200;
+
+               min: 10 30;
+               max: 10 30;
+            }
+         } // example/knob
+
+      }
+   }
+}

legacy/edje/src/examples/edje-drag.c

@@ -0,0 +1,155 @@
+/**
+ * Simple Edje example illustrating drag functions.
+ *
+ * You'll need at least one Evas engine built for it (excluding the
+ * buffer one). See stdout/stderr for output.
+ *
+ * @verbatim
+ * edje_cc drag.edc && gcc -o drag-box drag-box.c `pkg-config --libs --cflags evas ecore ecore-evas edje`
+ * @endverbatim
+ */
+
+#ifdef HAVE_CONFIG_H
+#include "config.h"
+#else
+#define PACKAGE_EXAMPLES_DIR "."
+#define __UNUSED__
+#endif
+
+#include <Ecore.h>
+#include <Ecore_Evas.h>
+#include <Edje.h>
+
+#define WIDTH  300
+#define HEIGHT 300
+
+#define RECTW 30
+#define RECTH 30
+
+#define NRECTS 20
+
+static const char *PARTNAME = "example/knob";
+
+static const char *edje_file_path = PACKAGE_EXAMPLES_DIR "/drag.edj";
+
+struct _App {
+    Ecore_Evas *ee;
+    Evas_Object *edje;
+    Evas_Object *bg;
+};
+
+static void
+_on_destroy(Ecore_Evas *ee __UNUSED__)
+{
+   ecore_main_loop_quit();
+}
+
+/* here just to keep our example's window size and background image's
+ * size in synchrony */
+static void
+_canvas_resize_cb(Ecore_Evas *ee)
+{
+   int w, h;
+   struct _App *app = ecore_evas_data_get(ee, "app");
+
+   ecore_evas_geometry_get(ee, NULL, NULL, &w, &h);
+   evas_object_resize(app->bg, w, h);
+   evas_object_resize(app->edje, w, h);
+}
+
+static void
+_bg_key_down(void *data, Evas *e, Evas_Object *o __UNUSED__, void *event_info)
+{
+   struct _App *app = data;
+   Evas_Event_Key_Down *ev = event_info;
+   Evas_Object *rect;
+   Eina_Bool r;
+
+
+   if (!strcmp(ev->keyname, "Down"))
+     {
+	edje_object_part_drag_step(app->edje, PARTNAME, 0, 1.0);
+     }
+   else if (!strcmp(ev->keyname, "Up"))
+     {
+	edje_object_part_drag_step(app->edje, PARTNAME, 0, -1.0);
+     }
+   else if (!strcmp(ev->keyname, "m"))
+     {
+	edje_object_part_drag_value_set(app->edje, PARTNAME, 0.0, 0.5);
+     }
+   else if (!strcmp(ev->keyname, "Prior"))
+     {
+	edje_object_part_drag_page(app->edje, PARTNAME, 0.0, -1.0);
+     }
+   else if (!strcmp(ev->keyname, "Next"))
+     {
+	edje_object_part_drag_page(app->edje, PARTNAME, 0.0, 1.0);
+     }
+   else if (!strcmp(ev->keyname, "Escape"))
+     ecore_main_loop_quit();
+   else
+     printf("unhandled key: %s\n", ev->keyname);
+}
+
+static void
+_knob_moved_cb(void *data, Evas_Object *o, const char *emission, const char *source)
+{
+   double val;
+   edje_object_part_drag_value_get(o, PARTNAME, NULL, &val);
+   printf("value changed to: %0.3f\n", val);
+}
+
+int
+main(void)
+{
+   Evas *evas;
+   struct _App app;
+   int i;
+
+   ecore_evas_init();
+   edje_init();
+
+   /* this will give you a window with an Evas canvas under the first
+    * engine available */
+   app.ee = ecore_evas_new(NULL, 0, 0, WIDTH, HEIGHT, NULL);
+
+   ecore_evas_callback_destroy_set(app.ee, _on_destroy);
+   ecore_evas_callback_resize_set(app.ee, _canvas_resize_cb);
+   ecore_evas_title_set(app.ee, "Edje Box Example");
+   ecore_evas_show(app.ee);
+
+   ecore_evas_data_set(app.ee, "app", &app);
+
+   evas = ecore_evas_get(app.ee);
+
+   app.bg = evas_object_rectangle_add(evas);
+   evas_object_color_set(app.bg, 255, 255, 255, 255);
+   evas_object_resize(app.bg, WIDTH, HEIGHT);
+   evas_object_focus_set(app.bg, EINA_TRUE);
+   evas_object_show(app.bg);
+
+   evas_object_event_callback_add(app.bg, EVAS_CALLBACK_KEY_DOWN, _bg_key_down, &app);
+
+   app.edje = edje_object_add(evas);
+
+   edje_object_file_set(app.edje, edje_file_path, "example/group");
+   evas_object_move(app.edje, 0, 0);
+   evas_object_resize(app.edje, WIDTH, HEIGHT);
+   evas_object_show(app.edje);
+
+   if (!edje_object_part_drag_step_set(app.edje, PARTNAME, 0.0, 0.1))
+     printf("error when setting drag step size.\n");
+
+   if (!edje_object_part_drag_page_set(app.edje, PARTNAME, 0.0, 0.3))
+     printf("error when setting drag page step size.\n");
+
+   edje_object_signal_callback_add(app.edje, "drag", PARTNAME, _knob_moved_cb, &app);
+
+   ecore_main_loop_begin();
+
+   ecore_evas_free(app.ee);
+   ecore_evas_shutdown();
+   edje_shutdown();
+   return 0;
+}

legacy/edje/src/lib/Edje.h

@@ -2917,10 +2917,14 @@ EAPI const char      *edje_object_part_state_get      (const Evas_Object *obj, c
  * @param obj A valid Evas_Object handle
  * @param part The part name
  *
- * @return 0: Not dragable\n
- * 1: Dragable in X direction\n
- * 2: Dragable in Y direction\n
- * 3: Dragable in X & Y directions
+ * The dragable directions are defined in the EDC file, inside the @c dragable
+ * section, by the attributes @c x and @c y. See the @ref edcref for more
+ * information.
+ *
+ * @return #EDJE_DRAG_DIR_NONE: Not dragable\n
+ * #EDJE_DRAG_DIR_X: Dragable in X direction\n
+ * #EDJE_DRAG_DIR_Y: Dragable in Y direction\n
+ * #EDJE_DRAG_DIR_XY: Dragable in X & Y directions
  */
 EAPI Edje_Drag_Dir    edje_object_part_drag_dir_get   (const Evas_Object *obj, const char *part);
 
@@ -2933,6 +2937,18 @@ EAPI Edje_Drag_Dir    edje_object_part_drag_dir_get   (const Evas_Object *obj, c
  * @param dy The y value
  *
  * Places the dragable object at the given location.
+ *
+ * Values for @p dx and @p dy are real numbers that range from 0 to 1,
+ * representing the relative position to the dragable area on that axis.
+ *
+ * This value means, for the vertical axis, that 0.0 will be at the top if the
+ * first parameter of @c y in the dragable part theme is 1, and at bottom if it
+ * is -1.
+ *
+ * For the horizontal axis, 0.0 means left if the first parameter of @c x in the
+ * dragable part theme is 1, and right if it is -1.
+ *
+ * @see edje_object_part_drag_value_get()
  */
 EAPI Eina_Bool        edje_object_part_drag_value_set (Evas_Object *obj, const char *part, double dx, double dy);
 
@@ -2944,6 +2960,11 @@ EAPI Eina_Bool        edje_object_part_drag_value_set (Evas_Object *obj, const c
  * @param dx The X value pointer
  * @param dy The Y value pointer
  *
+ * Values for @p dx and @p dy are real numbers that range from 0 to 1,
+ * representing the relative position to the dragable area on that axis.
+ *
+ * @see edje_object_part_drag_value_set()
+ *
  * Gets the drag location values.
  */
 EAPI Eina_Bool        edje_object_part_drag_value_get (const Evas_Object *obj, const char *part, double *dx, double *dy);
@@ -2956,7 +2977,12 @@ EAPI Eina_Bool        edje_object_part_drag_value_get (const Evas_Object *obj, c
  * @param dw The drag width
  * @param dh The drag height
  *
+ * Values for @p dw and @p dh are real numbers that range from 0 to 1,
+ * representing the relative size of the dragable area on that axis.
+ *
  * Sets the size of the dragable object.
+ *
+ * @see edje_object_part_drag_size_get()
  */
 EAPI Eina_Bool        edje_object_part_drag_size_set  (Evas_Object *obj, const char *part, double dw, double dh);
 
@@ -2969,6 +2995,8 @@ EAPI Eina_Bool        edje_object_part_drag_size_set  (Evas_Object *obj, const c
  * @param dh The drag height pointer
  *
  * Gets the dragable object size.
+ *
+ * @see edje_object_part_drag_size_set()
  */
 EAPI Eina_Bool        edje_object_part_drag_size_get  (const Evas_Object *obj, const char *part, double *dw, double *dh);
 
@@ -2981,6 +3009,12 @@ EAPI Eina_Bool        edje_object_part_drag_size_get  (const Evas_Object *obj, c
  * @param dy The y step amount
  *
  * Sets the x,y step increments for a dragable object.
+ *
+ * Values for @p dx and @p dy are real numbers that range from 0 to 1,
+ * representing the relative size of the dragable area on that axis by which the
+ * part will be moved.
+ *
+ * @see edje_object_part_drag_step_get()
  */
 EAPI Eina_Bool        edje_object_part_drag_step_set  (Evas_Object *obj, const char *part, double dx, double dy);
 
@@ -2993,6 +3027,9 @@ EAPI Eina_Bool        edje_object_part_drag_step_set  (Evas_Object *obj, const c
  * @param dy The y step increment pointer
  *
  * Gets the x and y step increments for the dragable object.
+ *
+ *
+ * @see edje_object_part_drag_step_set()
  */
 EAPI Eina_Bool        edje_object_part_drag_step_get  (const Evas_Object *obj, const char *part, double *dx, double *dy);
 
@@ -3005,6 +3042,12 @@ EAPI Eina_Bool        edje_object_part_drag_step_get  (const Evas_Object *obj, c
  * @param dy The y page step increment
  *
  * Sets the x,y page step increment values.
+ *
+ * Values for @p dx and @p dy are real numbers that range from 0 to 1,
+ * representing the relative size of the dragable area on that axis by which the
+ * part will be moved.
+ *
+ * @see edje_object_part_drag_page_get()
  */
 EAPI Eina_Bool        edje_object_part_drag_page_set  (Evas_Object *obj, const char *part, double dx, double dy);
 
@@ -3017,6 +3060,8 @@ EAPI Eina_Bool        edje_object_part_drag_page_set  (Evas_Object *obj, const c
  * @param dy The dy page increment pointer
  *
  * Gets the x,y page step increments for the dragable object.
+ *
+ * @see edje_object_part_drag_page_set()
  */
 EAPI Eina_Bool        edje_object_part_drag_page_get  (const Evas_Object *obj, const char *part, double *dx, double *dy);
 
@@ -3030,6 +3075,10 @@ EAPI Eina_Bool        edje_object_part_drag_page_get  (const Evas_Object *obj, c
  *
  * Steps x,y where the step increment is the amount set by
  * edje_object_part_drag_step_set.
+ *
+ * Values for @p dx and @p dy are real numbers that range from 0 to 1.
+ *
+ * @see edje_object_part_drag_page()
  */
 EAPI Eina_Bool        edje_object_part_drag_step      (Evas_Object *obj, const char *part, double dx, double dy);
 
@@ -3042,7 +3091,13 @@ EAPI Eina_Bool        edje_object_part_drag_step      (Evas_Object *obj, const c
  * @param dy The y step
  *
  * Pages x,y where the increment is defined by
- * edje_object_part_drag_page_set.\n WARNING: Paging is bugged!
+ * edje_object_part_drag_page_set.
+ *
+ * Values for @p dx and @p dy are real numbers that range from 0 to 1.
+ *
+ * @warning Paging is bugged!
+ *
+ * @see edje_object_part_drag_step()
  */
 EAPI Eina_Bool        edje_object_part_drag_page      (Evas_Object *obj, const char *part, double dx, double dy);