kimcinoo
/
efl
forked from enlightenment/efl
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

[edje] Documentation for the following: 

- edje_object_message_handler_set
 - edje_object_message_send
 - edje_object_signal_callback_add
 - edje_object_signal_callback_del_full
 - edje_object_signal_emit



SVN revision: 61966
This commit is contained in:
Gustavo Lima Chaves 2011-08-01 20:15:23 +00:00
parent 67111bacac
commit d55a77bae9
7 changed files with 7887 additions and 115 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

124
legacy/edje/doc/examples.dox
View File

@ -6,7 +6,8 @@
* @li @ref Example_Edje_Basics
* @li @ref tutorial_edje_swallow
* @li @ref tutorial_edje_text
* @li@ref tutorial_edje_table
* @li @ref tutorial_edje_table
* @li @ref Example_Edje_Signals_Messages
*/
/**
@ -257,3 +258,124 @@
* @include edje-table.c
* @example edje-table.c
*/
/**
* @page Example_Edje_Signals_Messages 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 @b 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 <b>color class</b>, so that we can
* multiply its colors by chosen values on the go:
* @dontinclude signals-messages.edc
* @until visible
* @until }
* @until }
* @until }
*
* The @c #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 <b>signal callbacks</b> on it. The first one uses
* @b globbing, making all of the wheel mouse actions over the left
* rectangle to trigger @c _mouse_wheel_cb. Note that those kind of
* signals are generated @b internally (and automatically) in Edje. The
* second is a direct signal match, to a (custom) signal we defined in
* the EDC, ourselves:
* @dontinclude edje-signals-messages.c
* @skip edje_object_add
* @until _mouse_over_cb
* @dontinclude edje-signals-messages.c
* @skip print signals coming from theme
* @until }
* @until }
*
* That second callback is on a signal we emit on the theme, where we
* just translate Edje @c "mouse,move" internal events to the custom @c
* "mouse,over" one. When that signals reaches the code, we are,
* besides printing the signals' strings, sending a @b message back to
* the theme. We generate random values of color components and send
* them as an #EDJE_MESSAGE_INT_SET message type:
* @dontinclude signals-messages.edc
* @skip custom signal
* @until }
* @dontinclude edje-signals-messages.c
* @skip mouse over signals
* @until }
*
* In our theme we'll be changing the @c "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:
* @dontinclude signals-messages.edc
* @skip public message
* @until }
* @until }
*
* Now we're also sending messages <b>from the Edje object</b>,
* 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:
* @dontinclude signals-messages.edc
* @skip program
* @until }
* @until }
* @skip change text
* @until }
* @until }
* @dontinclude signals-messages.edc
* @skip set_text_string
* @until }
*
* To get the message in code, we have to register a message handler, as
* follows:
* @dontinclude edje-signals-messages.c
* @skip message_handler_set
* @until message_handler_set
* @dontinclude edje-signals-messages.c
* @skip print out
* @until }
*
* To interact with the last missing feature -- emitting signals
* <b>from code</b> -- there's a command line interface to exercise
* it. A help string can be asked for with the 'h' key:
* @dontinclude edje-signals-messages.c
* @skip commands
* @until ;
*
* The @c 't' command will send either @c "part_right,show" or @c
* "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:
* @dontinclude signals-messages.edc
* @skip hide right rectangle
* @until }
* @until }
* @dontinclude edje-signals-messages.c
* @skip keyname, "t"
* @until }
*
* The example's window should look like this picture:
*
* @image html edje-signals-messages-example.png
* @image rtf edje-signals-messages-example.png
* @image latex edje-signals-messages-example.eps
*
* The full example follows, along with its EDC file.
*
* @include signals-messages.edc
* @include edje-signals-messages.c
* @example edje-signals-messages.c
*/

7202
legacy/edje/doc/img/edje-signals-messages-example.eps Normal file
View File

File diff suppressed because it is too large Load Diff

BIN
legacy/edje/doc/img/edje-signals-messages-example.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.6 KiB

12
legacy/edje/src/examples/Makefile.am
View File

@ -6,7 +6,8 @@ pkglibdir = $(datadir)/$(PACKAGE)/examples
EDCS = basic.edc \
swallow.edc \
text.edc \
table.edc
table.edc \
signals-messages.edc
filesdir = $(datadir)/$(PACKAGE)/examples
files_DATA =
@ -31,7 +32,8 @@ pkglib_PROGRAMS += \
edje-basic \
edje-swallow \
edje-text \
edje-table
edje-table \
edje-signals-messages
LDADD = $(top_builddir)/src/lib/libedje.la @ECORE_EVAS_LIBS@
@ -54,7 +56,8 @@ files_DATA += \
$(srcdir)/edje-basic.c \
$(srcdir)/edje-swallow.c \
$(srcdir)/edje-text.c \
$(srcdir)/edje-table.c
$(srcdir)/edje-table.c \
$(srcdir)/edje-signals-messages.c
endif
EXTRA_DIST = $(EDCS) \
@ -62,4 +65,5 @@ EXTRA_DIST = $(EDCS) \
$(srcdir)/edje-basic.c \
$(srcdir)/edje-swallow.c \
$(srcdir)/edje-text.c \
$(srcdir)/edje-table.c
$(srcdir)/edje-table.c \
$(srcdir)/edje-signals-messages.c

230
legacy/edje/src/examples/edje-signals-messages.c Normal file
View File

@ -0,0 +1,230 @@
/**
* Simple Edje example illustrating the Edje signals and messages
*
* You'll need at least one Evas engine built for it (excluding the
* buffer one). See stdout/stderr for output.
*
* @verbatim
* gcc -o edje-signals-messages edje-signals-messages.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>
#include <stdio.h>
#define WIDTH (300)
#define HEIGHT (300)
#define MSG_COLOR 1
#define MSG_TEXT 2
static const char *border_img_path = PACKAGE_EXAMPLES_DIR "/red.png";
static const char *edje_file_path = \
PACKAGE_EXAMPLES_DIR "/signals-messages.edj";
static Ecore_Evas *ee;
static Evas_Object *edje_obj;
static Eina_Bool right_rect_show = EINA_TRUE;
static const char *commands = \
"commands are:\n"
"\tt - toggle right rectangle's visibility\n"
"\th - print help\n";
static void
_on_keydown(void *data __UNUSED__,
Evas *evas __UNUSED__,
Evas_Object *o __UNUSED__,
void *einfo)
{
Evas_Event_Key_Down *ev = einfo;
if (strcmp(ev->keyname, "h") == 0) /* print help */
{
fprintf(stdout, commands);
return;
}
if (strcmp(ev->keyname, "t") == 0) /* 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;
}
}
static void
_on_destroy(Ecore_Evas *ee __UNUSED__)
{
ecore_main_loop_quit();
}
/* print signals coming from theme */
static void
_sig_print(const char *emission,
const char *source)
{
fprintf(stdout, "Signal %s coming from part %s!\n", emission, source);
}
static void
_mouse_wheel_cb(void *data __UNUSED__,
Evas_Object *obj __UNUSED__,
const char *emission,
const char *source)
{
_sig_print(emission, source);
}
/* mouse over signals */
static void
_mouse_over_cb(void *data __UNUSED__,
Evas_Object *obj __UNUSED__,
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 __UNUSED__,
Evas_Object *obj __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;
fprintf(stdout, "String message received: %s\n", m->str);
}
int
main(void)
{
Evas_Object *border, *bg;
Evas *evas;
srand(time(NULL));
if (!ecore_evas_init())
return EXIT_FAILURE;
if (!edje_init())
return EXIT_FAILURE;
/* 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 error;
ecore_evas_callback_destroy_set(ee, _on_destroy);
ecore_evas_title_set(ee, "Edje Basics 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);
evas_object_focus_set(bg, EINA_TRUE);
evas_object_event_callback_add(
bg, EVAS_CALLBACK_KEY_DOWN, _on_keydown, NULL);
edje_obj = edje_object_add(evas);
if (!edje_object_file_set(edje_obj, edje_file_path, "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 error_edj;
}
edje_object_signal_callback_add(edje_obj, "mouse,wheel,*", "part_left",
_mouse_wheel_cb, NULL);
edje_object_signal_callback_add(edje_obj, "mouse,over", "part_right",
_mouse_over_cb, 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);
/* 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, border_img_path, 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);
fprintf(stdout, commands);
ecore_main_loop_begin();
ecore_evas_free(ee);
ecore_evas_shutdown();
edje_shutdown();
return 0;
error:
fprintf(stderr, "You got to have at least one Evas engine built"
" and linked up to ecore-evas for this example to run"
" properly.\n");
ecore_evas_shutdown();
return -1;
error_edj:
fprintf(stderr, "Failed to load signals-messages.edj!\n");
ecore_evas_shutdown();
return -2;
}

174
legacy/edje/src/examples/signals-messages.edc Normal file
View File

@ -0,0 +1,174 @@
#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(3);
g = getarg(4);
b = getarg(5);
a = getarg(6);
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();
}
}
}
}
}

260
legacy/edje/src/lib/Edje.h
View File

@ -449,6 +449,7 @@ part of Edje's API:
- @ref Example_Edje_Basics
- @ref tutorial_edje_swallow
- @ref tutorial_edje_table
- @ref Example_Edje_Signals_Messages
@ -583,25 +584,32 @@ extern "C" {
* These routines are used for Edje.
*/
/**
* Identifiers of Edje message types, which can be sent back and forth
* code and a given Edje object's theme file/group.
*
* @see edje_object_message_send()
* @see edje_object_message_handler_set()
*/
typedef enum _Edje_Message_Type
{
EDJE_MESSAGE_NONE = 0,
EDJE_MESSAGE_SIGNAL = 1, /* DONT USE THIS */
EDJE_MESSAGE_STRING = 2,
EDJE_MESSAGE_INT = 3,
EDJE_MESSAGE_FLOAT = 4,
EDJE_MESSAGE_STRING = 2, /**< A message with a string as value. Use #Edje_Message_String structs as message body, for this type. */
EDJE_MESSAGE_INT = 3, /**< A message with an integer number as value. Use #Edje_Message_Int structs as message body, for this type. */
EDJE_MESSAGE_FLOAT = 4, /**< A message with a floating pointer number as value. Use #Edje_Message_Float structs as message body, for this type. */
EDJE_MESSAGE_STRING_SET = 5,
EDJE_MESSAGE_INT_SET = 6,
EDJE_MESSAGE_FLOAT_SET = 7,
EDJE_MESSAGE_STRING_SET = 5, /**< A message with a list of strings as value. Use #Edje_Message_String_Set structs as message body, for this type. */
EDJE_MESSAGE_INT_SET = 6, /**< A message with a list of integer numbers as value. Use #Edje_Message_Int_Set structs as message body, for this type. */
EDJE_MESSAGE_FLOAT_SET = 7, /**< A message with a list of floating point numbers as value. Use #Edje_Message_Float_Set structs as message body, for this type. */
EDJE_MESSAGE_STRING_INT = 8,
EDJE_MESSAGE_STRING_FLOAT = 9,
EDJE_MESSAGE_STRING_INT = 8, /**< A message with a struct containing a string and an integer number as value. Use #Edje_Message_String_Int structs as message body, for this type. */
EDJE_MESSAGE_STRING_FLOAT = 9, /**< A message with a struct containing a string and a floating point number as value. Use #Edje_Message_String_Float structs as message body, for this type. */
EDJE_MESSAGE_STRING_INT_SET = 10,
EDJE_MESSAGE_STRING_FLOAT_SET = 11
EDJE_MESSAGE_STRING_INT_SET = 10, /**< A message with a struct containing a string and list of integer numbers as value. Use #Edje_Message_String_Int_Set structs as message body, for this type. */
EDJE_MESSAGE_STRING_FLOAT_SET = 11 /**< A message with a struct containing a string and list of floating point numbers as value. Use #Edje_Message_String_Float_Set structs as message body, for this type. */
} Edje_Message_Type;
typedef enum _Edje_Aspect_Control
@ -728,62 +736,62 @@ typedef struct _Edje_Message_String_Float_Set Edje_Message_String_Float_Set;
struct _Edje_Message_String
{
char *str;
};
char *str; /**< The message's string pointer */
}; /**< Structure passed as value on #EDJE_MESSAGE_STRING messages. The string in it is automatically freed be Edje */
struct _Edje_Message_Int
{
int val;
};
int val; /**< The message's value */
}; /**< Structure passed as value on #EDJE_MESSAGE_INT messages */
struct _Edje_Message_Float
{
double val;
};
double val; /**< The message's value */
}; /**< Structure passed as value on #EDJE_MESSAGE_FLOAT messages */
struct _Edje_Message_String_Set
{
int count;
char *str[1];
};
int count; /**< The size of the message's array (may be greater than 1) */
char *str[1]; /**< The message's @b array of string pointers */
}; /**< Structure passed as value on #EDJE_MESSAGE_STRING_SET messages. The array in it is automatically freed be Edje */
struct _Edje_Message_Int_Set
{
int count;
int val[1];
};
int count; /**< The size of the message's array (may be greater than 1) */
int val[1]; /**< The message's @b array of integers */
}; /**< Structure passed as value on #EDJE_MESSAGE_INT_SET messages. The array in it is automatically freed be Edje */
struct _Edje_Message_Float_Set
{
int count;
double val[1];
};
int count; /**< The size of the message's array (may be greater than 1) */
double val[1]; /**< The message's @b array of floats */
}; /**< Structure passed as value on #EDJE_MESSAGE_FLOAT_SET messages. The array in it is automatically freed be Edje */
struct _Edje_Message_String_Int
{
char *str;
int val;
};
char *str; /**< The message's string value */
int val; /**< The message's integer value */
}; /**< Structure passed as value on #EDJE_MESSAGE_STRING_INT messages */
struct _Edje_Message_String_Float
{
char *str;
double val;
};
char *str; /**< The message's string value */
double val; /**< The message's float value */
}; /**< Structure passed as value on #EDJE_MESSAGE_STRING_FLOAT messages */
struct _Edje_Message_String_Int_Set
{
char *str;
int count;
int val[1];
};
char *str; /**< The message's string value */
int count; /**< The size of the message's array (may be greater than 1) */
int val[1]; /**< The message's @b array of integers */
}; /**< Structure passed as value on #EDJE_MESSAGE_STRING_INT_SET messages */
struct _Edje_Message_String_Float_Set
{
char *str;
int count;
double val[1];
};
char *str; /**< The message's string value */
int count; /**< The size of the message's array (may be greater than 1) */
double val[1]; /**< The message's @b array of floats */
}; /**< Structure passed as value on #EDJE_MESSAGE_STRING_FLOAT_SET messages */
typedef enum _Edje_Drag_Dir
{
@ -1034,9 +1042,9 @@ struct _Edje_External_Type_Info
};
typedef struct _Edje_External_Type_Info Edje_External_Type_Info;
typedef void (*Edje_Signal_Cb) (void *data, Evas_Object *obj, const char *emission, const char *source);
typedef void (*Edje_Signal_Cb) (void *data, Evas_Object *obj, const char *emission, const char *source); /**< Edje signal callback functions's prototype definition. @c data will have the auxiliary data pointer set at the time the callback registration. @c obj will be a pointer the Edje object where the signal comes from. @c emission will identify the exact signal's emission string and @c source the exact signal's source one. */
typedef void (*Edje_Text_Change_Cb) (void *data, Evas_Object *obj, const char *part);
typedef void (*Edje_Message_Handler_Cb) (void *data, Evas_Object *obj, Edje_Message_Type type, int id, void *msg);
typedef void (*Edje_Message_Handler_Cb) (void *data, Evas_Object *obj, Edje_Message_Type type, int id, void *msg); /**< Edje message handler callback functions's prototype definition. @c data will have the auxiliary data pointer set at the time the callback registration. @c obj will be a pointer the Edje object where the message comes from. @c type will identify the type of the given message and @c msg will be a pointer the message's contents, de facto, which depend on @c type. */
typedef void (*Edje_Text_Filter_Cb) (void *data, Evas_Object *obj, const char *part, Edje_Text_Filter_Type type, char **text);
typedef Evas_Object *(*Edje_Item_Provider_Cb) (void *data, Evas_Object *obj, const char *part, const char *item);
@ -1769,52 +1777,64 @@ EAPI const char *edje_load_error_str (Edje_Load_Error error);
EAPI Eina_Bool edje_object_preload (Evas_Object *obj, Eina_Bool cancel);
/**
* @brief Add a callback for a signal emitted by @a obj.
* @brief Add a callback for an arriving Edje signal, emitted by
* a given Ejde object.
*
* @param obj A valid Evas_Object handle.
* @param emission The signal's name.
* @param source The signal's source.
* @param obj A handle to an Edje object
* @param emission The signal's "emission" string
* @param source The signal's "source" string
* @param func The callback function to be executed when the signal is
* emitted.
* @param data A pointer to data to pass in to the callback function.
* @param data A pointer to data to pass in to @p func.
*
* Connects a callback function to a signal emitted by @a obj.
* In EDC, a program can emit a signal as follows:
* Edje signals are one of the communication interfaces between
* @b code and a given Edje object's @b theme. With signals, one can
* communicate two string values at a time, which are:
* - "emission" value: the name of the signal, in general
* - "source" value: a name for the signal's context, in general
*
* Though there are those common uses for the two strings, one is free
* to use them however they like.
*
* This function adds a callback function to a signal emitted by @a obj, to
* be issued every time an EDC program like the following
* @code
* program {
* name: "emit_example";
* action: SIGNAL_EMIT "a_signal" "a_source";
* }
* @endcode
* is run, if @p emission and @p source are given those same values,
* here.
*
* Assuming a function with the following declaration is definded:
* Signal callback registration is powerful, in the way that @b blobs
* may be used to match <b>multiple signals at once</b>. All the @c
* "*?[\" set of @c fnmatch() operators can be used, both for @p
* emission and @p source.
*
* Edje has @b internal signals it will emit, automatically, on
* various actions taking place on group parts. For example, the mouse
* cursor being moved, pressed, released, etc., over a given part's
* area, all generate individual signals.
*
* By using something like
* @code
* void cb_signal(void *data, Evas_Object *o, const char *emission, const char *source);
* edje_object_signal_callback_add(obj, "mouse,down,*", "button.*",
* signal_cb, NULL);
* @endcode
* being @c "button.*" the pattern for the names of parts implementing
* buttons on an interface, you'd be registering for notifications on
* events of mouse buttons being pressed down on either of those parts
* (those events all have the @c "mouse,down," common prefix on their
* names, with a suffix giving the button number). The actual emisson
* and source strings of an event will be passed in as the @a emission
* and @a source parameters of the callback function (e.g. @c
* "mouse,down,2" and @c "button.close"), for each of those events.
*
* a callback is attached using:
*
* @code
* edje_object_signal_callback_add(obj, "a_signal", "a_source", cb_signal, data);
* @endcode
*
* Here, @a data is an arbitrary pointer to be used as desired. Note
* that @a emission and @a source correspond respectively to the first
* and the second parameters at the SIGNAL_EMIT action.
*
* Internal edje signals can also be attached to, and globs can occur
* in either the emission or source name, e.g.
*
* @code
* edje_object_signal_callback_add(obj, "mouse,down,*", "button.*", NULL);
* @endcode
*
* Here, any mouse down events on an edje part whose name begins with
* "button." will trigger the callback. The actual signal and source
* names will be passed in to the @a emission and @a source parameters
* of the callback function (e.g. "mouse,down,2" and "button.close").
* @note See @ref edcref "the syntax" for EDC files
* @see edje_object_signal_emit() on how to emits Edje signals from
* code to a an object
* @see edje_object_signal_callback_del_full()
*/
EAPI void edje_object_signal_callback_add (Evas_Object *obj, const char *emission, const char *source, Edje_Signal_Cb func, void *data);
@ -1840,20 +1860,23 @@ EAPI void edje_object_signal_callback_add (Evas_Object *obj, const char
EAPI void *edje_object_signal_callback_del (Evas_Object *obj, const char *emission, const char *source, Edje_Signal_Cb func);
/**
* @brief Remove a signal-triggered callback from an object.
* @brief Unregister/delete a callback set for an arriving Edje
* signal, emitted by a given Ejde object.
*
* @param obj A valid Evas_Object handle.
* @param emission The emission string.
* @param source The source string.
* @param func The callback function.
* @param data The user data passed to the callback.
* @return The data pointer
* @param obj A handle to an Edje object
* @param emission The signal's "emission" string
* @param source The signal's "source" string
* @param func The callback function passed on the callback's
* registration
* @param data The pointer given to be passed as data to @p func
* @return @p data, on success or @c NULL, on errors (or if @p data
* had this value)
*
* This function removes a callback, previously attached to the
* emittion of a signal, from the object @a obj. The parameters @a
* emission, @a sourcei, @a func and @a data must match exactly those
* passed to a previous call to edje_object_signal_callback_add(). The data
* pointer that was passed to this call will be returned.
* emittion of a signal, from the object @a obj. The parameters
* @a emission, @a source, @a func and @a data must match exactly those
* passed to a previous call to edje_object_signal_callback_add(). The
* data pointer that was passed to this call will be returned.
*
* @see edje_object_signal_callback_add().
* @see edje_object_signal_callback_del().
@ -1862,22 +1885,22 @@ EAPI void *edje_object_signal_callback_del (Evas_Object *obj, const char
EAPI void *edje_object_signal_callback_del_full(Evas_Object *obj, const char *emission, const char *source, Edje_Signal_Cb func, void *data);
/**
* @brief Send a signal to an edje object.
* @brief Send/emit an Edje signal to a given Edje object
*
* @param obj A valid Evas_Object handle.
* @param emission The signal's name.
* @param source The signal's source.
* @param obj A handle to an Edje object
* @param emission The signal's "emission" string
* @param source The signal's "source" string
*
* This function sends a signal to the object @a obj. An edje program
* can respond to a signal by specifying matching 'signal' and
* 'source' fields.
* This function sends a signal to the object @a obj. An Edje program,
* at @p obj's EDC specification level, can respond to a signal by
* having declared matching @c 'signal' and @c 'source' fields on its
* block (see @ref edcref "the syntax" for EDC files).
*
* As an example,
* @code
* edje_object_signal_emit(obj, "a_signal", "");
* @endcode
*
* will trigger a program whose EDC block is:
*
* would trigger a program which had an EDC declaration block like
* @code
* program {
* name: "a_program";
@ -1887,7 +1910,7 @@ EAPI void *edje_object_signal_callback_del_full(Evas_Object *obj, const c
* }
* @endcode
*
* FIXME: should this signal be sent to children also?
* @see edje_object_signal_callback_add() for more on Edje signals.
*/
EAPI void edje_object_signal_emit (Evas_Object *obj, const char *emission, const char *source);
@ -3232,35 +3255,52 @@ EAPI Eina_Bool edje_object_part_table_col_row_size_get (const Evas_Object *ob
EAPI Eina_Bool edje_object_part_table_clear (Evas_Object *obj, const char *part, Eina_Bool clear);
/**
* @brief Send message to object.
* @brief Send an (Edje) message to a given Edje object
*
* @param obj The edje object reference.
* @param type The type of message to send.
* @param id A identification number for the message.
* @param msg The message to be send.
* @param obj A handle to an Edje object
* @param type The type of message to send to @p obj
* @param id A identification number for the message to be sent
* @param msg The message's body, a struct depending on @p type
*
* This function sends an Edje message to @p obj and to all of its
* child objects, if it has any (swallowed objects are one kind of
* child object). @p type and @p msg @b must be matched accordingly,
* as documented in #Edje_Message_Type.
*
* This function sends messages to this object and to all of its child
* objects, if applicable. The function that handles messages arriving
* at this edje object is is set with
* The @p id argument as a form of code and theme defining a common
* interface on message communication. One should define the same IDs
* on both code and EDC declaration (see @ref edcref "the syntax" for
* EDC files), to individualize messages (binding them to a given
* context).
*
* The function to handle messages arriving @b from @b obj is set with
* edje_object_message_handler_set().
*
* @see edje_object_message_handler_set()
*
*/
EAPI void edje_object_message_send (Evas_Object *obj, Edje_Message_Type type, int id, void *msg);
/**
* @brief Set the message handler function for this an object.
* @brief Set an Edje message handler function for a given Edje object.
*
* @param obj The edje object reference.
* @param func The function to handle messages.
* @param data The data to be associated to the message handler.
* @param obj A handle to an Edje object
* @param func The function to handle messages @b coming from @p obj
* @param data Auxiliary data to be passed to @p func
*
* Edje messages are one of the communication interfaces between
* @b code and a given Edje object's @b theme. With messages, one can
* communicate values beyond strings (which are the subject of Edje
* signals -- see edje_object_signal_emit()), like float and integer
* numbers. Moreover, messages can be identified by integer
* numbers. See #Edje_Message_Type for the full list of message types.
*
* This function associates a message handler function and data to the
* edje object.
* For scriptable programs on an Edje object's defining EDC file which
* send messages with the @c send_message() primitive, one can attach
* <b>handler functions</b>, to be called in the code which creates
* that object (see @ref edcref "the syntax" for EDC files).
*
* This function associates a message handler function and the
* attached data pointer to the object @p obj.
*
* @see edje_object_message_send()
*/
EAPI void edje_object_message_handler_set (Evas_Object *obj, Edje_Message_Handler_Cb func, void *data);