Edje basics example

In this example, we illustrate how to start using the Edje library, with the very basic one needs to instantiate an Edje object.

We place, in the canvas, an Edje object along with a red border image to delimit its geometry. After we instantiate the Edje object, we have to set a file and a group, within that file, to bind to it. For this example, we're using an EDC file which declares two parts (blue and green rectangles) and an item data:

We start by trying to access an unexistant group in the file, so that you can see the usefulness of edje_object_load_error_get() and edje_load_error_str(). Check that the error message will tell you just that -- a group which didn't exist in the file was called for:

   edje_obj = edje_object_add(evas);

   /* exercising Edje loading error, on purpose */
   if (!edje_object_file_set(edje_obj, edje_file, "unexistant_group"))
     {
        int err = edje_object_load_error_get(edje_obj);
        const char *errmsg = edje_load_error_str(err);
        fprintf(stderr, "Could not load 'unexistant_group' from basic.edj:"
                        " %s\n", errmsg);
     }

Than, we finally bind our Edje object to "example_group", printing a message afterwards:

What follows is a series of Edje API calls which are of general use. The first of them is edje_object_data_get(), which we use to get the value we have put in the "example_data" data field, in our EDC object declaration:

   fprintf(stdout, "'example_data' data field in group 'example_group' has "
                   "the value: %s\n", edje_object_data_get(edje_obj,
                                                           "example_data"));

Than, we exemplify edje_object_part_exists():

   fprintf(stdout, "Testing if 'part_one' part exists: %s\n",
           edje_object_part_exists(edje_obj, "part_one") ? "yes!" : "no");

The next call is to query "part_one"'s geometry, relative to the whole Edje object's area. The part will be situated in the middle of the Edje object's, because it has a restricted forced size (we set its minimum size equal to its maximum, for that) and, by default, parts are aligned to the center of their containers:

   edje_object_part_geometry_get(edje_obj, "part_one", &x, &y, &w, &h);
   fprintf(stdout, "The geometry of that part inside the Edje object's area "
                   "is: x = %d, y = %d, w = %d, h = %d\n", x, y, w, h);

We can grab a direct pointer on the rectangle implementing "part_one", by using edje_object_part_object_get(). Since we are not allowed to set properties on it, we just check its color, to assure its really blue, as declared in the EDC:

   evas_object_color_get(edje_object_part_object_get(edje_obj, "part_one"),
                         &x, &y, &w, &h);
   fprintf(stdout, "That part's color components are: r = %d, g = %d, b = %d,"
                   " a = %d\n", x, y, w, h);

The "min" and "max" EDC properties can be queried with the following calls:

   edje_object_size_max_get(edje_obj, &w, &h);
   fprintf(stdout, "The Edje object's max. size is: %d, %d\n", w, h);

   edje_object_size_min_get(edje_obj, &w, &h);
   fprintf(stdout, "The Edje object's min. size is: %d, %d\n", w, h);

The next two calls are to make size calculations on our object. Because of the minimum size declared for "part_one" part's default state description, that will be our exact minimum size calculated for the group (remember the "min" declaration at group level is just a hint, not an enforcement). We then exercise the edje_object_size_min_restricted_calc() function, passing a minimum size of 500, in each axis. Since we have no object bigger than that, it will be the minimum size calculated, in the end:

   edje_object_size_min_calc(edje_obj, &w, &h);
   fprintf(stdout, "The Edje object's min. size reported by min. size"
                   " calculation is: w = %d, h = %d\n", w, h);

   edje_object_size_min_restricted_calc(edje_obj, &w, &h, 500, 500);
   fprintf(stdout, "The Edje object's min. size reported by *restricted* "
                   "min. size calculation is: w = %d, h = %d\n", w, h);

"part_two" part is there with a purpose: since it extrapolates the Edje object's boundaries, the edje_object_parts_extends_calc() function will report origin coordinates for the rectangle grouping both parts with negative values, indicating it extrapolates to the upper left of our group, just as we see it.

To interact with the last features exemplified in the program, there's a command line interface. A help string can be asked for with the 'h' key:

static const char commands[] = \
  "commands are:\n"
  "\ts - change Edje's global scaling factor\n"
  "\tr - change center rectangle's scaling factor\n"
  "\tEsc - exit\n"
  "\th - print help\n";

Those commands will change the scaling factors of our Edje objects. The first of them, 's', will change Edje's global scaling factor between 1.0 (no scaling) and 2.0 (double scale). Scaling will be applied to "part_one", only, because that's the part flagged to be scaled at EDC level:

   else if (strcmp(ev->key, "s") == 0) /* global scaling factor */
     {
        double scale = edje_scale_get();

        printf("got scale %f\n", scale);

        if (scale != 1.0) scale = 1.0;
        else scale = 2.0;

        edje_scale_set(scale);

        fprintf(stdout, "Setting global scaling factor to %f.\n", scale);

        return;
     }

Note, finally, that the 's' command will depend on the 'r' one to have its effects applied. The latter will change "part_one"'s individual scaling factor, which overrides Edje's global scaling factor. Only when the individual one is set to zero, will the global one take effect:

   else if (strcmp(ev->key, "r") == 0) /* individual scaling factor */
     {
        double scale = edje_object_scale_get(edje_obj);

        printf("got scale %f\n", scale);

        if (!scale) scale = 1.0;
        else if (scale == 1.0) scale = 2.0;
        else scale = 0.0;

        edje_object_scale_set(edje_obj, scale);

        fprintf(stdout, "Setting center rectangle's scaling factor to %f.\n",
                scale);

        return;
     }

The example's window should look like this picture:

The full example follows.

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

#ifndef PACKAGE_DATA_DIR
#define PACKAGE_DATA_DIR "."
#endif

#include <stdio.h>

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

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

static const char commands[] = \
  "commands are:\n"
  "\ts - change Edje's global scaling factor\n"
  "\tr - change center rectangle's scaling factor\n"
  "\tEsc - exit\n"
  "\th - print help\n";

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") == 0) /* print help */
     {
        fprintf(stdout, commands);
        return;
     }
   else if (strcmp(ev->key, "s") == 0) /* global scaling factor */
     {
        double scale = edje_scale_get();

        printf("got scale %f\n", scale);

        if (scale != 1.0) scale = 1.0;
        else scale = 2.0;

        edje_scale_set(scale);

        fprintf(stdout, "Setting global scaling factor to %f.\n", scale);

        return;
     }
   else if (strcmp(ev->key, "r") == 0) /* individual scaling factor */
     {
        double scale = edje_object_scale_get(edje_obj);

        printf("got scale %f\n", scale);

        if (!scale) scale = 1.0;
        else if (scale == 1.0) scale = 2.0;
        else scale = 0.0;

        edje_object_scale_set(edje_obj, scale);

        fprintf(stdout, "Setting center rectangle's scaling factor to %f.\n",
                scale);

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

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

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"/basic.edj";
   Ecore_Evas  *ee;
   Evas        *evas;
   Evas_Object *bg;
   Evas_Object *border;
   Evas_Object *edje_obj;
   int          x;
   int          y;
   int          w;
   int          h;

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

   evas_object_focus_set(bg, EINA_TRUE);

   edje_obj = edje_object_add(evas);

   /* exercising Edje loading error, on purpose */
   if (!edje_object_file_set(edje_obj, edje_file, "unexistant_group"))
     {
        int err = edje_object_load_error_get(edje_obj);
        const char *errmsg = edje_load_error_str(err);
        fprintf(stderr, "Could not load 'unexistant_group' from basic.edj:"
                        " %s\n", errmsg);
     }

   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 basic.edj: %s\n",
                errmsg);

        evas_object_del(edje_obj);
        goto shutdown_edje;
     }

   fprintf(stdout, "Loaded Edje object bound to group 'example_group' from"
                   " file basic.edj with success!\n");

   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_show(border);

   fprintf(stdout, "'example_data' data field in group 'example_group' has "
                   "the value: %s\n", edje_object_data_get(edje_obj,
                                                           "example_data"));

   fprintf(stdout, "Testing if 'part_one' part exists: %s\n",
           edje_object_part_exists(edje_obj, "part_one") ? "yes!" : "no");

   edje_object_part_geometry_get(edje_obj, "part_one", &x, &y, &w, &h);
   fprintf(stdout, "The geometry of that part inside the Edje object's area "
                   "is: x = %d, y = %d, w = %d, h = %d\n", x, y, w, h);

   evas_object_color_get(edje_object_part_object_get(edje_obj, "part_one"),
                         &x, &y, &w, &h);
   fprintf(stdout, "That part's color components are: r = %d, g = %d, b = %d,"
                   " a = %d\n", x, y, w, h);

   edje_object_size_max_get(edje_obj, &w, &h);
   fprintf(stdout, "The Edje object's max. size is: %d, %d\n", w, h);

   edje_object_size_min_get(edje_obj, &w, &h);
   fprintf(stdout, "The Edje object's min. size is: %d, %d\n", w, h);

   edje_object_size_min_calc(edje_obj, &w, &h);
   fprintf(stdout, "The Edje object's min. size reported by min. size"
                   " calculation is: w = %d, h = %d\n", w, h);

   edje_object_size_min_restricted_calc(edje_obj, &w, &h, 500, 500);
   fprintf(stdout, "The Edje object's min. size reported by *restricted* "
                   "min. size calculation is: w = %d, h = %d\n", w, h);

   edje_object_parts_extends_calc(edje_obj, &x, &y, &w, &h);
   fprintf(stdout, "The Edje object's \"extended\" geometry is: x = %d, "
                   "y = %d, w = %d, h = %d\n", x, y, w, h);

   fprintf(stdout, 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-basic edje-basic.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 basic.edc
 *