Edje: edje text parts documentation.

SVN revision: 61963

legacy/edje/doc/examples.dox

@@ -5,6 +5,7 @@
  *
  * @li @ref Example_Edje_Basics
  * @li @ref tutorial_edje_swallow
+ * @li @ref tutorial_edje_text
  */
 
 /**
@@ -150,4 +151,52 @@
  * The full source code follows:
  * @include edje-swallow.c
  * @example edje-swallow.c
+ */
+
+/**
+ * @page tutorial_edje_text Edje Text example
+ * @dontinclude edje-text.c
+ *
+ * This example shows how to manipulate TEXT and TEXTBLOCK parts from code.
+ *
+ * The very first we are going to do is register a callback to react to changes
+ * in the text of our parts:
+ * @skip _on_destroy
+ * @skip static void
+ * @until }
+ *
+ * @skipline text_change
+ * @note Since edje_obj represent a group we'll be notified whenever any part's
+ * text in that group changes.
+ *
+ * We now set the text for two our two parts:
+ * @until text_set
+ * @until text_set
+ * @note Since the "part_two" part is a TEXTBLOCK we can use formatting such as
+ * @<b@>
+ *
+ * And we now move on to selection issues, first thing we do is make sure the
+ * user can select text:
+ * @until select_allow
+ *
+ * We then select the entire text, and print the selected text:
+ * @until printf
+ *
+ * We now unselect the entire text(set selection to none), and print the
+ * selected text:
+ * @until printf
+ *
+ * Our example will look like this:
+ *
+ * @image html edje-text.png
+ * @image rtf edje-text.png
+ * @image latex edje-text.eps
+ *
+ * The full source code follows:
+ * @include edje-text.c
+ * @example edje-text.c
+ *
+ * The theme used in this example is:
+ * @include text.edc
+ * @example text.edc
  */

legacy/edje/src/examples/Makefile.am

@@ -4,7 +4,8 @@ pkglibdir = $(datadir)/$(PACKAGE)/examples
 
 #put here all EDCs one needs to the examples
 EDCS = basic.edc \
-	swallow.edc
+	swallow.edc \
+	text.edc
 
 filesdir = $(datadir)/$(PACKAGE)/examples
 files_DATA =
@@ -27,7 +28,8 @@ AM_CPPFLAGS += @ECORE_EVAS_CFLAGS@
 
 pkglib_PROGRAMS += \
 	edje-basic \
-	edje-swallow
+	edje-swallow \
+	edje-text
 
 LDADD = $(top_builddir)/src/lib/libedje.la @ECORE_EVAS_LIBS@
 
@@ -48,10 +50,12 @@ files_DATA += $(srcdir)/red.png
 files_DATA += \
 	$(EDCS) \
 	$(srcdir)/edje-basic.c \
-	$(srcdir)/edje-swallow.c
+	$(srcdir)/edje-swallow.c \
+	$(srcdir)/edje-text.c \
 endif
 
 EXTRA_DIST = $(EDCS) \
 	$(srcdir)/red.png \
 	$(srcdir)/edje-basic.c \
-	$(srcdir)/edje-swallow.c
+	$(srcdir)/edje-swallow.c \
+	$(srcdir)/edje-text.c

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

@@ -0,0 +1,92 @@
+/**
+ * Simple Edje example illustrating text functions.
+ *
+ * You'll need at least one Evas engine built for it (excluding the
+ * buffer one). See stdout/stderr for output.
+ *
+ * @verbatim
+ * edje_cc text.edc && gcc -o edje-text edje-text.c `pkg-config --libs --cflags 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)
+
+static const char *edje_file_path = PACKAGE_EXAMPLES_DIR "/text.edj";
+
+static Ecore_Evas *ee;
+static Evas_Object *bg;
+
+static void
+_on_destroy(Ecore_Evas *ee __UNUSED__)
+{
+   ecore_main_loop_quit();
+}
+
+static void
+_cb(void *data, Evas_Object *obj, const char *part)
+{
+   printf("text: %s\n", edje_object_part_text_unescaped_get(obj, part));
+}
+
+int
+main(void)
+{
+   Evas_Object *edje_obj, *rect, *obj;
+   Evas *evas;
+
+   ecore_evas_init();
+   edje_init();
+
+   /* this will give you a window with an Evas canvas under the first
+    * engine available */
+   ee = ecore_evas_new(NULL, 0, 0, WIDTH, HEIGHT, NULL);
+
+   ecore_evas_callback_destroy_set(ee, _on_destroy);
+   ecore_evas_title_set(ee, "Edje text Example");
+   ecore_evas_show(ee);
+
+   evas = ecore_evas_get(ee);
+
+   bg = evas_object_rectangle_add(evas);
+   evas_object_color_set(bg, 255, 255, 255, 255); /* white bg */
+   evas_object_move(bg, 0, 0); /* at canvas' origin */
+   evas_object_resize(bg, WIDTH, HEIGHT); /* covers full canvas */
+   evas_object_show(bg);
+   ecore_evas_object_associate(ee, bg, ECORE_EVAS_OBJECT_ASSOCIATE_BASE);
+
+   edje_obj = edje_object_add(evas);
+
+   edje_object_file_set(edje_obj, edje_file_path, "example_group");
+   evas_object_move(edje_obj, 20, 20);
+   evas_object_resize(edje_obj, WIDTH - 40, HEIGHT - 40);
+   evas_object_show(edje_obj);
+
+   edje_object_text_change_cb_set(edje_obj, _cb, NULL);
+   edje_object_part_text_set(edje_obj, "part_one", "one");
+   edje_object_part_text_set(edje_obj, "part_two", "<b>two");
+
+   edje_object_part_text_select_allow_set(edje_obj, "part_two", EINA_TRUE);
+   edje_object_part_text_select_all(edje_obj, "part_two");
+   printf("selection: %s\n", edje_object_part_text_selection_get(edje_obj, "part_two"));
+   edje_object_part_text_select_none(edje_obj, "part_two");
+   printf("selection: %s\n", edje_object_part_text_selection_get(edje_obj, "part_two"));
+
+   ecore_main_loop_begin();
+
+   ecore_evas_free(ee);
+   ecore_evas_shutdown();
+   edje_shutdown();
+   return 0;
+}

legacy/edje/src/examples/text.edc

@@ -0,0 +1,68 @@
+collections {
+   group {
+      name: "sel_group";
+      parts {
+         part {
+            name: "rect";
+            type: RECT;
+            description {
+               state: "default" 0.0;
+               color: 0 255 0 255; /* green */
+               rel1.relative: 0.0 0.0;
+               rel2.relative: 1.0 1.0;
+            }
+         }
+      }
+   }
+   group {
+      name: "example_group";
+      max: 500 500;
+      min: 50 50;
+
+      styles {
+         style {
+            name: "textblock_style";
+            base: "font=Sans font_size=22 color=#600 wrap=word";
+            tag:  "br" "\n";
+            tag:  "hilight" "+ font_weight=Bold";
+            tag:  "b" "+ font_weight=Bold";
+            tag:  "tab" "\t";
+         }
+      }
+      parts {
+         part {
+            name: "part_one";
+            type: TEXT;
+            description {
+               min: 50 50;
+               state: "default" 0.0;
+               color: 0 0 255 255; /* blue */
+               rel1.relative: 0.0 0.0;
+               rel2.relative: 1.0 0.5;
+               text {
+                  font: "arial";
+                  size: 22;
+                  min: 1 1;
+               }
+            }
+         }
+         part {
+            name: "part_two";
+            type: TEXTBLOCK;
+            select_mode: EXPLICIT;
+            source: "sel_group";
+            entry_mode: PLAIN;
+            description {
+               min: 50 50;
+               state: "default" 0.0;
+               rel1.relative: 0.0 0.5;
+               rel2.relative: 1.0 1.0;
+               text {
+                  style: "textblock_style";
+                  min: 1 1;
+               }
+            }
+         }
+      }
+   }
+}

legacy/edje/src/lib/Edje.h

@@ -2324,16 +2324,13 @@ EAPI void         edje_object_item_provider_set       (Evas_Object *obj, Edje_It
  * @param func The callback function to handle the text change
  * @param data The data associated to the callback function.
  *
- * This function gets the geometry of an Edje part
- *
- * It is valid to pass NULL as any of @a x, @a y, @a w or @a h, whose
- * values you are uninterested in.
- *
+ * This function sets the callback to be called when the text changes.
  */
 EAPI void         edje_object_text_change_cb_set      (Evas_Object *obj, Edje_Text_Change_Cb func, void *data);
 
 /**
- * Sets the text for an object part
+ * @brief Sets the text for an object part
+ *
  * @param obj A valid Evas Object handle
  * @param part The part name
  * @param text The text string
@@ -2350,6 +2347,7 @@ EAPI Eina_Bool    edje_object_part_text_set           (Evas_Object *obj, const c
  *
  * This function returns the text associated to the object part.
  *
+ * @see edje_object_part_text_set().
  */
 EAPI const char  *edje_object_part_text_get           (const Evas_Object *obj, const char *part);
 
@@ -2360,12 +2358,10 @@ EAPI const char  *edje_object_part_text_get           (const Evas_Object *obj, c
  * @param part The part name
  * @param text_to_escape The text string
  *
- * This funciton will do escape for you if it is a TEXTBLOCK part,
- * that is, if text contain tags, these tags will not be
- * interpreted/parsed by TEXTBLOCK.
+ * This funciton will not do escape for you if it is a TEXTBLOCK part, that is,
+ * if text contain tags, these tags will not be interpreted/parsed by TEXTBLOCK.
  *
  * @see edje_object_part_text_unescaped_get().
- *
  */
 EAPI Eina_Bool    edje_object_part_text_unescaped_set (Evas_Object *obj, const char *part, const char *text_to_escape);
 
@@ -2383,7 +2379,6 @@ EAPI Eina_Bool    edje_object_part_text_unescaped_set (Evas_Object *obj, const c
  * when done.
  *
  * @see edje_object_part_text_unescaped_set().
- *
  */
 EAPI char        *edje_object_part_text_unescaped_get (const Evas_Object *obj, const char *part);
 
@@ -2396,6 +2391,8 @@ EAPI char        *edje_object_part_text_unescaped_get (const Evas_Object *obj, c
  *
  * This function returns selection text of the object part.
  *
+ * @see edje_object_part_text_select_all()
+ * @see edje_object_part_text_select_none()
  */
 EAPI const char      *edje_object_part_text_selection_get           (const Evas_Object *obj, const char *part);
 
@@ -2406,7 +2403,6 @@ EAPI const char      *edje_object_part_text_selection_get           (const Evas_
  * @param part The part name
  *
  * This function sets the selection text to be none.
- *
  */
 EAPI void             edje_object_part_text_select_none             (const Evas_Object *obj, const char *part);
 
@@ -2417,7 +2413,6 @@ EAPI void             edje_object_part_text_select_none             (const Evas_
  * @param part The part name
  *
  * This function selects all text of the object of the part.
- *
  */
 EAPI void             edje_object_part_text_select_all              (const Evas_Object *obj, const char *part);
 
@@ -2530,6 +2525,10 @@ EAPI void             edje_object_part_text_cursor_geometry_get     (const Evas_
  * @param obj A valid Evas_Object handle
  * @param part The part name
  * @param allow EINA_TRUE to enable, EINA_FALSE otherwise
+ *
+ * The default is to @b not allow selection. This function only affects user
+ * selection, functions such as edje_object_part_text_select_all() and
+ * edje_object_part_text_select_none() are not affected.
  */
 EAPI void             edje_object_part_text_select_allow_set        (const Evas_Object *obj, const char *part, Eina_Bool allow);
 

legacy/edje/src/lib/edje_util.c

@@ -1046,11 +1046,6 @@ _edje_object_part_text_raw_append(Evas_Object *obj, Edje_Real_Part *rp, const ch
    return EINA_TRUE;
 }
 
-/** Sets the text for an object part
- * @param obj A valid Evas Object handle
- * @param part The part name
- * @param text The text string
- */
 EAPI Eina_Bool
 edje_object_part_text_set(Evas_Object *obj, const char *part, const char *text)
 {