From 2440b258eda4410763f3f9d321ffd969c935b1d8 Mon Sep 17 00:00:00 2001 From: Rafael Antognolli Date: Mon, 4 Jul 2011 18:31:13 +0000 Subject: [PATCH] ecore/events - add detailed description to this group. SVN revision: 61015 --- legacy/ecore/src/lib/ecore/ecore_events.c | 30 +++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/legacy/ecore/src/lib/ecore/ecore_events.c b/legacy/ecore/src/lib/ecore/ecore_events.c index c8e1a31a16..886f008bab 100644 --- a/legacy/ecore/src/lib/ecore/ecore_events.c +++ b/legacy/ecore/src/lib/ecore/ecore_events.c @@ -81,6 +81,36 @@ static void *_ecore_event_del(Ecore_Event *event); /** * @addtogroup Ecore_Event_Group Ecore Event functions * + * Ecore events are used to wake up the Ecore main loop to warn about state + * changes, tasks completed, data available for reading or writing, etc. They + * are the base of the event oriented programming. + * + * The idea is to write many functions (callbacks) that will be registered to + * specific events, and called when these events happen. This way, when the + * system state changes (a mouse click is detected, a key is pressed, or the + * content of a file changes, for example), the respective callbacks will be + * called with some information about that event. Usually the function/callback + * will have a data pointer to the event info (the position in the screen where + * the mouse was clicked, the name of the key that was pressed, or the name of + * the file that has changed). + * + * The basic usage, when one needs to watch for an existing event, is to + * register a callback to it using ecore_event_add(). Of course it's necessary + * to know beforehand what are the types of events that the system/library will + * emmit. This should be available with the documentation from that + * system/library. + * + * When writing a library or group of functions that need to inform about + * something, and you already are running on top of a main loop, it is usually a + * good approach to use events. This way you allow others to register as many + * callbacks as necessary to this event, and don't have to care about who is + * registering to it. The functions ecore_event_type_new() and ecore_event_add() + * are available for this purpose. + * + * Example that deals with events: + * + * @li @ref ecore_event_example_c + * * @{ */