Edje signals and messages

In this example, we illustrate how Edje signals and Edje messages work.

We place, in the canvas, an Edje object along with a red border image to delimit its geometry. The object's group definition is so that we have four parts:

• a blue rectangle, aligned to the right
• a white rectangle, aligned to the left
• a text part, aligned to the center
• a clipper rectangle on the blue rectangle

The left rectangle is bound to a color class, so that we can multiply its colors by chosen values on the go:

#define MSG_COLOR 1
#define MSG_TEXT 2

collections {
   group {
      name: "example_group";

      parts {
         part {
            name: "part_right";
            type: RECT;
            clip_to: "part_right_clipper";
            description {
               min: 50 50;
               max: 50 50;
               state: "default" 0.0;
               color: 0 0 255 255; /* blue */
               rel1.relative: 1.0 0.5;
               rel1.offset: -49 0;
               rel2.relative: 1.0 0.5;
            }
         }

         part {
            name: "part_left";
            type: RECT;
            description {
               color_class: "cc";
               min: 50 50;
               max: 50 50;
               state: "default" 0.0;
               rel1.relative: 0.0 0.5;
               rel2.relative: 0.0 0.5;
               rel2.offset: 50 -1;
            }
         }

         part {
            name: "text";
            type: TEXT;
            description {
               min: 150 50;
               max: 150 50;
               fixed: 1 1;
               color: 0 0 0 255;
               state: "default" 0.0;
               rel1.relative: 0.5 0.5;
               rel2.relative: 0.5 0.5;
               text {
                  font:     "Sans";
                  size:     20;
                  min:      1 1;
                  align:    0.5 0.5;
               }
            }
         }

         part {
            name: "part_right_clipper";
            type: RECT;
            repeat_events: 1;

            description {
               min: 50 50;
               max: 50 50;

               state: "default" 0.0;
               rel1.relative: 1.0 0.5;
               rel1.offset: -49 0;
               rel2.relative: 1.0 0.5;
            }

            description {
               state: "hidden" 0.0;
               inherit: "default" 0.0;
               visible: 0;
            }
         }
      }

The #define's on the beginning will serve as message identifiers, for our accorded message interface between the code and the this theme file.

Let's move to the code, then. After instantiating the Edje object, we register two signal callbacks on it. The first one uses globbing, making all of the wheel mouse actions over the left rectangle to trigger _mouse_wheel. Note that those kind of signals are generated internally (and automatically) in Edje. The second is a direct signal match, to a (custom) signal we defined in the EDC, ourselves:

   edje_obj = edje_object_add(evas);

   if (!edje_object_file_set(edje_obj, edje_file, "example_group"))
     {
        int err = edje_object_load_error_get(edje_obj);
        const char *errmsg = edje_load_error_str(err);
        fprintf(stderr, "Could not load 'example_group' from "
                        "signals-messages.edj: %s\n", errmsg);

        evas_object_del(edje_obj);
        goto shutdown_edje;
     }

   edje_object_signal_callback_add(edje_obj, "mouse,wheel,*", "part_left",
                                   _on_mouse_wheel, NULL);

   edje_object_signal_callback_add(edje_obj, "mouse,over", "part_right",
                                   _on_mouse_over, NULL);

/* print signals coming from theme */
static void
_sig_print(const char *emission,
           const char *source)
{
   printf("Signal %s coming from part %s!\n", emission, source);
}

static void
_on_mouse_wheel(void        *data EINA_UNUSED,
                  Evas_Object *obj EINA_UNUSED,
                  const char  *emission,
                  const char  *source)
{
   _sig_print(emission, source);
}

That second callback is on a signal we emit on the theme, where we just translate Edje "mouse,move" internal events to the custom "mouse,over" one. When that signals reaches the code, we are, besides printing the signals' strings, sending a message back to the theme. We generate random values of color components and send them as an EDJE_MESSAGE_INT_SET message type:

         program { /* custom signal */
            name: "part_right,hovered";
            signal: "mouse,move";
            source: "part_right";
            action: SIGNAL_EMIT "mouse,over" "part_right";
         }

/* mouse over signals */
static void
_on_mouse_over(void        *data EINA_UNUSED,
               Evas_Object *edje_obj,
               const char  *emission,
               const char  *source)
{
   int i;

   _sig_print(emission, source);

   Edje_Message_Int_Set *msg = malloc(sizeof(*msg) + 3 * sizeof(int));
   msg->count = 4;
   for (i = 0; i < 4; i++)
     msg->val[i] = rand() % 256;

   edje_object_message_send(edje_obj, EDJE_MESSAGE_INT_SET, MSG_COLOR, msg);

   free(msg);
}

In our theme we'll be changing the "cc" color class' values with those integer values of the message, so that moving the mouse over the right rectangle will change the left one's colors:

        public message(Msg_Type:type, id, ...) {
           if ((type == MSG_INT_SET) && (id == MSG_COLOR)) {
               new r, g, b, a;

               r = getarg(2);
               g = getarg(3);
               b = getarg(4);
               a = getarg(5);

               set_color_class("cc", r, g, b, a);
           }
        }

Now we're also sending messages from the Edje object, besides signals. We do so when one clicks with the left button over the left rectangle. With that, we change the text part's text, cycling between 3 pre-set strings declared in the EDC. With each new text string attribution, we send a string message to our code, with the current string as argument:

      programs {
         program {
            name: "bootstrap";
            signal: "load";
            source: "";
            script {
               set_str(global_str0, "String one");
               set_str(global_str1, "String two");
               set_str(global_str2, "String three");
               set_int(str_idx, 0);
               set_text_string();
            }
         }
         program { /* change text part's string value */
            name: "text,change";
            signal: "mouse,clicked,1";
            source: "part_left";
            script {
               new idx;
               idx = get_int(str_idx);
               idx = idx + 1;

               if (idx > 2)
                  set_int(str_idx, 0);
               else
                  set_int(str_idx, idx);

               set_text_string();
            }
         }

        public set_text_string() {
           new tmp[1024];
           new idx;
           idx = get_int(str_idx);

           if (idx == 0)
              get_str(global_str0, tmp, 1024);
           else if (idx == 1)
              get_str(global_str1, tmp, 1024);
           else if (idx == 2)
              get_str(global_str2, tmp, 1024);
              else return;

           set_text(PART:"text", tmp);
           send_message(MSG_STRING, MSG_TEXT, tmp);
        }

To get the message in code, we have to register a message handler, as follows:

   edje_object_message_handler_set(edje_obj, _message_handle, NULL);

/* print out received message string */
static void
_message_handle(void             *data EINA_UNUSED,
                Evas_Object      *obj EINA_UNUSED,
                Edje_Message_Type type,
                int               id,
                void             *msg)
{
   Edje_Message_String *m;

   if (type != EDJE_MESSAGE_STRING) return;
   if (id != MSG_TEXT) return;

   m = msg;

   printf("String message received: %s\n", m->str);
}

To interact with the last missing feature – emitting signals from code – there's a command line interface to exercise it. A help string can be asked for with the 'h' key:

static const char commands[] = \
  "commands are:\n"
  "\tt - toggle right rectangle's visibility\n"
  "\tEsc - exit\n"
  "\th - print help\n";

The 't' command will send either "part_right,show" or "part_right,hide" signals to the Edje object (those being the emission part of the signal), which was set to react on them as the names indicate. We'll set the right rectangle's visibility on/off, respectively, for those two signals:

         program { /* hide right rectangle */
            name: "part_right,hide";
            signal: "part_right,hide";
            source: "";
            action: STATE_SET "hidden" 0.0;
            target: "part_right_clipper";
         }

         program {
            name: "part_right,show";
            signal: "part_right,show";
            source: "";
            action: STATE_SET "default" 0.0;
            target: "part_right_clipper";
         }

   else if (!strcmp(ev->key, "t")) /* toggle right rectangle's visibility */
     {
        char buf[1024];

        right_rect_show = !right_rect_show;
        snprintf(buf, sizeof(buf), "part_right,%s",
                 right_rect_show ? "show" : "hide");

        printf("emitting %s\n", buf);

        edje_object_signal_emit(edje_obj, buf, "");

        return;
     }

The example's window should look like this picture:

The full example follows, along with its EDC file.

#define MSG_COLOR 1
#define MSG_TEXT 2

collections {
   group {
      name: "example_group";

      parts {
         part {
            name: "part_right";
            type: RECT;
            clip_to: "part_right_clipper";
            description {
               min: 50 50;
               max: 50 50;
               state: "default" 0.0;
               color: 0 0 255 255; /* blue */
               rel1.relative: 1.0 0.5;
               rel1.offset: -49 0;
               rel2.relative: 1.0 0.5;
            }
         }

         part {
            name: "part_left";
            type: RECT;
            description {
               color_class: "cc";
               min: 50 50;
               max: 50 50;
               state: "default" 0.0;
               rel1.relative: 0.0 0.5;
               rel2.relative: 0.0 0.5;
               rel2.offset: 50 -1;
            }
         }

         part {
            name: "text";
            type: TEXT;
            description {
               min: 150 50;
               max: 150 50;
               fixed: 1 1;
               color: 0 0 0 255;
               state: "default" 0.0;
               rel1.relative: 0.5 0.5;
               rel2.relative: 0.5 0.5;
               text {
                  font:     "Sans";
                  size:     20;
                  min:      1 1;
                  align:    0.5 0.5;
               }
            }
         }

         part {
            name: "part_right_clipper";
            type: RECT;
            repeat_events: 1;

            description {
               min: 50 50;
               max: 50 50;

               state: "default" 0.0;
               rel1.relative: 1.0 0.5;
               rel1.offset: -49 0;
               rel2.relative: 1.0 0.5;
            }

            description {
               state: "hidden" 0.0;
               inherit: "default" 0.0;
               visible: 0;
            }
         }
      }

      script {
        public global_str0;
        public global_str1;
        public global_str2;
        public str_idx;

        public set_text_string() {
           new tmp[1024];
           new idx;
           idx = get_int(str_idx);

           if (idx == 0)
              get_str(global_str0, tmp, 1024);
           else if (idx == 1)
              get_str(global_str1, tmp, 1024);
           else if (idx == 2)
              get_str(global_str2, tmp, 1024);
              else return;

           set_text(PART:"text", tmp);
           send_message(MSG_STRING, MSG_TEXT, tmp);
        }

        public message(Msg_Type:type, id, ...) {
           if ((type == MSG_INT_SET) && (id == MSG_COLOR)) {
               new r, g, b, a;

               r = getarg(2);
               g = getarg(3);
               b = getarg(4);
               a = getarg(5);

               set_color_class("cc", r, g, b, a);
           }
        }
      }

      programs {
         program {
            name: "bootstrap";
            signal: "load";
            source: "";
            script {
               set_str(global_str0, "String one");
               set_str(global_str1, "String two");
               set_str(global_str2, "String three");
               set_int(str_idx, 0);
               set_text_string();
            }
         }

         program { /* custom signal */
            name: "part_right,hovered";
            signal: "mouse,move";
            source: "part_right";
            action: SIGNAL_EMIT "mouse,over" "part_right";
         }

         program { /* hide right rectangle */
            name: "part_right,hide";
            signal: "part_right,hide";
            source: "";
            action: STATE_SET "hidden" 0.0;
            target: "part_right_clipper";
         }

         program {
            name: "part_right,show";
            signal: "part_right,show";
            source: "";
            action: STATE_SET "default" 0.0;
            target: "part_right_clipper";
         }

         program { /* change text part's string value */
            name: "text,change";
            signal: "mouse,clicked,1";
            source: "part_left";
            script {
               new idx;
               idx = get_int(str_idx);
               idx = idx + 1;

               if (idx > 2)
                  set_int(str_idx, 0);
               else
                  set_int(str_idx, idx);

               set_text_string();
            }
         }
      }
   }
}

#ifdef HAVE_CONFIG_H
#include "config.h"
#else
#define PACKAGE_EXAMPLES_DIR "."
#define EINA_UNUSED
#endif

#ifndef PACKAGE_DATA_DIR
#define PACKAGE_DATA_DIR "."
#endif

#include <Ecore.h>
#include <Ecore_Evas.h>
#include <Edje.h>
#include <stdio.h>

#define WIDTH     (300)
#define HEIGHT    (300)

#define MSG_COLOR 1
#define MSG_TEXT  2

static const char commands[] = \
  "commands are:\n"
  "\tt - toggle right rectangle's visibility\n"
  "\tEsc - exit\n"
  "\th - print help\n";

static Eina_Bool right_rect_show = EINA_TRUE;

static void
_on_keydown(void        *data,
            Evas        *evas EINA_UNUSED,
            Evas_Object *o EINA_UNUSED,
            void        *einfo)
{
   Evas_Event_Key_Down *ev;
   Evas_Object         *edje_obj;

   ev = (Evas_Event_Key_Down *)einfo;
   edje_obj = (Evas_Object *)data;

   if (!strcmp(ev->key, "h")) /* print help */
     {
        printf(commands);
        return;
     }
   else if (!strcmp(ev->key, "t")) /* toggle right rectangle's visibility */
     {
        char buf[1024];

        right_rect_show = !right_rect_show;
        snprintf(buf, sizeof(buf), "part_right,%s",
                 right_rect_show ? "show" : "hide");

        printf("emitting %s\n", buf);

        edje_object_signal_emit(edje_obj, buf, "");

        return;
     }
   else if (!strcmp(ev->key, "Escape"))
     ecore_main_loop_quit();
   else
     {
        printf("unhandled key: %s\n", ev->key);
        printf(commands);
     }
}

static void
_on_delete(Ecore_Evas *ee EINA_UNUSED)
{
   ecore_main_loop_quit();
}

/* print signals coming from theme */
static void
_sig_print(const char *emission,
           const char *source)
{
   printf("Signal %s coming from part %s!\n", emission, source);
}

static void
_on_mouse_wheel(void        *data EINA_UNUSED,
                  Evas_Object *obj EINA_UNUSED,
                  const char  *emission,
                  const char  *source)
{
   _sig_print(emission, source);
}

/* mouse over signals */
static void
_on_mouse_over(void        *data EINA_UNUSED,
               Evas_Object *edje_obj,
               const char  *emission,
               const char  *source)
{
   int i;

   _sig_print(emission, source);

   Edje_Message_Int_Set *msg = malloc(sizeof(*msg) + 3 * sizeof(int));
   msg->count = 4;
   for (i = 0; i < 4; i++)
     msg->val[i] = rand() % 256;

   edje_object_message_send(edje_obj, EDJE_MESSAGE_INT_SET, MSG_COLOR, msg);

   free(msg);
}

/* print out received message string */
static void
_message_handle(void             *data EINA_UNUSED,
                Evas_Object      *obj EINA_UNUSED,
                Edje_Message_Type type,
                int               id,
                void             *msg)
{
   Edje_Message_String *m;

   if (type != EDJE_MESSAGE_STRING) return;
   if (id != MSG_TEXT) return;

   m = msg;

   printf("String message received: %s\n", m->str);
}

int
main(int argc EINA_UNUSED, char *argv[] EINA_UNUSED)
{
   const char  *img_file = PACKAGE_DATA_DIR"/red.png";
   const char  *edje_file = PACKAGE_DATA_DIR"/signals-messages.edj";
   Ecore_Evas  *ee;
   Evas        *evas;
   Evas_Object *bg;
   Evas_Object *edje_obj;
   Evas_Object *border;

   if (!ecore_evas_init())
     return EXIT_FAILURE;

   if (!edje_init())
     goto shutdown_ecore_evas;

   /* 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);
   if (!ee) goto shutdown_edje;

   ecore_evas_callback_delete_request_set(ee, _on_delete);
   ecore_evas_title_set(ee, "Edje Signals and Messages Example");

   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);
   evas_object_focus_set(bg, EINA_TRUE);
   ecore_evas_object_associate(ee, bg, ECORE_EVAS_OBJECT_ASSOCIATE_BASE);

   edje_obj = edje_object_add(evas);

   if (!edje_object_file_set(edje_obj, edje_file, "example_group"))
     {
        int err = edje_object_load_error_get(edje_obj);
        const char *errmsg = edje_load_error_str(err);
        fprintf(stderr, "Could not load 'example_group' from "
                        "signals-messages.edj: %s\n", errmsg);

        evas_object_del(edje_obj);
        goto shutdown_edje;
     }

   edje_object_signal_callback_add(edje_obj, "mouse,wheel,*", "part_left",
                                   _on_mouse_wheel, NULL);

   edje_object_signal_callback_add(edje_obj, "mouse,over", "part_right",
                                   _on_mouse_over, NULL);

   edje_object_message_handler_set(edje_obj, _message_handle, NULL);

   evas_object_move(edje_obj, 20, 20);
   evas_object_resize(edje_obj, WIDTH - 40, HEIGHT - 40);
   evas_object_show(edje_obj);

   evas_object_event_callback_add(bg, EVAS_CALLBACK_KEY_DOWN, _on_keydown, edje_obj);

   /* this is a border around the Edje object above, here just to
    * emphasize its geometry */
   border = evas_object_image_filled_add(evas);
   evas_object_image_file_set(border, img_file, NULL);
   evas_object_image_border_set(border, 2, 2, 2, 2);
   evas_object_image_border_center_fill_set(border, EVAS_BORDER_FILL_NONE);

   evas_object_resize(border, WIDTH - 40 + 4, HEIGHT - 40 + 4);
   evas_object_move(border, 20 - 2, 20 - 2);
   evas_object_repeat_events_set(border, EINA_TRUE);
   evas_object_show(border);

   printf(commands);

   ecore_evas_show(ee);

   ecore_main_loop_begin();

   ecore_evas_free(ee);
   ecore_evas_shutdown();
   edje_shutdown();

   return EXIT_SUCCESS;

 shutdown_edje:
   edje_shutdown();
 shutdown_ecore_evas:
   ecore_evas_shutdown();

   return EXIT_FAILURE;
}

To compile use this command:

* gcc -o edje-signals-messages edje-signals-messages.c -DPACKAGE_BIN_DIR=\"/Where/enlightenment/is/installed/bin\"
* -DPACKAGE_LIB_DIR=\"/Where/enlightenment/is/installed/lib\"
* -DPACKAGE_DATA_DIR=\"/Where/enlightenment/is/installed/share\"
* `pkg-config --cflags --libs evas ecore ecore-evas edje`
*
* edje_cc signals-messages.edc
*