EWL Callback Information

In order for an application to be able to function in a GUI environment it needs to be notified when specific actions occur. These actions could be mouse movement, keyboard input, closing the window or the user clicking on a button. In order to facilitate this communication EWL has a callback system that will be used.

When an application wants to know when a specific event occurs to a widget they can add a callback using one of the ewl_callback functions. These functions include: ewl_callback_append(), ewl_callback_prepend() and ewl_callback_insert_after(). Each of these functions accept the following parameters:

Ewl_Widget * 

The widget that the callback is attached too.

unsigned int 

The type of the callback. The available callback types are listed at the end of this article. It's also possible to add custom callback types if so desired.

Ewl_Callback_Function 

The function to be called when the event on the given widget is triggered.

void * 

The user data to attach to the callback.

The ewl_callback_insert_after() function accepts two other parameters specifying they callback to insert after.

You can attach callbacks to any widget and, with containers, you can intercept events to their child widgets.

Every callback type in EWL requires the same function signature. This makes it a lot easier to remember what signature you need for each callback in the system. It's always:

   void (*func)(Ewl_Widget *w, void *ev, void *data);

The parameters are defined as:

Ewl_Widget *w 

The widget the callback was triggered on.

void *ev 

The event structure for this event, or NULL if none returned.

void *data 

The user data that was set when the callback was created.

One feature of EWL that is different from other toolkits is that it makes extensive use of callbacks internally. In fact, almost all appearance changes for widgets are actually callbacks, and most of the ewl_widget calls actually do very little work, but trigger specific callbacks. This feature allows for overriding specific actions on a widget, or for ordering user specified callbacks relative to internal ones.

Custom Callbacks

If you'd like to take advantage of the EWL callback system in your application to handle communication between different modules you can create custom callback types in EWL and trigger their events as needed.

Creating a custom callback is as easy as calling ewl_callback_type_add() which will return the int value of the callback. You can now have your application register callbacks on this new type ID.

When you want to trigger the callback on a specific widget you'll make a call to either; ewl_callback_call() or ewl_callback_call_with_event_data() depending on if you have an event structure to pass to the widget.

Available Standard Callbacks

EWL_CALLBACK_EXPOSE 

Triggered when the window needs redrawing. You can safely ignore this callback in your application.

EWL_CALLBACK_REALIZE

This callback is triggered when a widget is first drawn.

During the realize process EWL will first reveal the the widget, obtain the inset and padding values from the theme and set these values onto the widget.

The event data is always NULL.

EWL_CALLBACK_UNREALIZE 

Triggered when a widget will no longer be drawn.

EWL_CALLBACK_SHOW 

The widget has been marked visible.

EWL_CALLBACK_HIDE 

The widget has been marked hidden.

EWL_CALLBACK_OBSCURE 

The widget is off screen.

EWL_CALLBACK_REVEAL

The widget is displayed on screen. You can safely ignore this callback in your application as long you don't use your own Evas/Edje objects.

To reduce memory usage EWL creates the Evas/Edje objects only if they are visible on screen. If the object is off screen it will be obscured. A objects are needed during the realize process, the widget is revealed during the the realize process and obscured afterwards.

EWL stores a cache of Evas objects that it reuses. As items are obscured their underlying Evas objects are added to the cache. On reveal, if there is an available object in the cache, it is retrieved. Otherwise, a new object is created. This helps to limit the total number of required Evas objecst in the system to what is needed for onscreen display. Reducing memory and runtime requirements.

If you use your own Evas/Edje objects you have two possible ways to set them up. If you can save the state of the object, and it doesn't need to exist if it is not visible, you'll probably want to create the Evas or Edje object in the reveal callback and destroy it in the obscure callback. If you can't save the state, or the object has to exist even if it is not visible, like a emotion object, you'll want to create the object in the realize callback and delete it in the unrealize callback.

No matter which way you choose you'll always have to setup the object layering in the reveal callback. This setup is quite simple. You just have to add the object to the smart object of your widget. This can be seen in the following code example.

void
my_widget_cb_reveal(Ewl_Widget *w, void *ev_data, void *user_data)
{
        My_Widget *my;
        my = (MyWidget *)w;
        ...
        evas_object_smart_member_add(my->evas_object, w->smart_object);
        ...
}

A good example of using Evas objects inside an EWL widget can be seen in ewl_image.c and ewl_media.c.

The event data is always NULL.

EWL_CALLBACK_DESTROY

This callback is called when a widget will be destroyed. You don't have to free the widget itself, EWL already does this for you but if you've created a custom widget that has allocated memory you should free it here.

The event data is always NULL.

EWL_CALLBACK_DELETE_WINDOW

This callback is called when the user ask to close the window. It is a good idea to listen to this event for every window as EWL will do nothing by default. If you want your window to close you'll need to delete it in this callback. You can also popup a dialog to ask the user if they really want to close the window. If this is your last open window, you may also want to exit the EWL main loop by calling: ewl_main_quit().

The event data is always NULL.

EWL_CALLBACK_CONFIGURE

This callback type is only needed if you write a custom widget. The callback is called when the object is being resized or moved. If you changed a parameter that changes the internal placement of the child widgets, for example the value of your progressbar like widget, you can call ewl_widget_configure(widget) to queue the request and call the configure event when the widget gets redrawn.

The event data is always NULL.

EWL_CALLBACK_REPARENT

This callback is triggered when a widget has been placed in a container or switched containers.

The event data is a pointer to the new parent.

EWL_CALLBACK_KEY_DOWN

This callback is called when a key is pressed down. The callback will only be emitted to the current selected widget and its parents. If you want to provide global key bindings you'll want to listen for key down events on the window (or embed).

The event data is a pointer to a. Ewl_Event_Key_Down structure.

struct Ewl_Event_Key_Down
{
        unsigned int modifiers; /**< Modifiers that were pressed */
        char *keyname;          /**< Name of the key that was pressed */
};

You can test the modifiers with a binary AND against the modifier flag you're looking for.

if (event->modifiers & EWL_KEY_MODIFIER_SHIFT) {
...

The available modifiers are:

• EWL_KEY_MODIFIER_SHIFT
• EWL_KEY_MODIFIER_CTRL
• EWL_KEY_MODIFIER_ALT
• EWL_KEY_MODIFIER_MOD
• EWL_KEY_MODIFIER_WIN

The keyname can be a name like "Enter", "Left", "Right", "Return", "BackSpace", etc or it's the character that was pressed on the keyboard. Note that EWL use a UTF-8 character encoding and hence, a character can be longer than one byte.

EWL_CALLBACK_KEY_UP

This callback works similar to EWL_CALLBACK_KEY_DOWN except it's called when the key is released.

The event data is a Ewl_Event_Key_Up structure.

struct Ewl_Event_Key_Up
{
        unsigned int modifiers; /**< Modifiers that were pressed */
        char *keyname;          /**< Name of the key that was released */
};

EWL_CALLBACK_MOUSE_DOWN

This callback is called when the mouse is pressed down on the widget or one of its children.

The event data is a Ewl_Event_Mouse_Down structure.

struct Ewl_Event_Mouse_Down
{
        unsigned int modifiers; /**< Modifiers that were pressed */
        int button;             /**< The mouse button that was pressed */
        int clicks;             /**< Number of consecutive clicks */
        int x;                  /**< X coordinate the mouse press occurred at */
        int y;                  /**< Y coordinate the mouse press occurred at */
};

The modifiers are the currently pressed key modifiers; see EWL_CALLBACK_KEY_DOWN for more information. The button attribute is the number of the button being pressed, where 1 is the left mouse button, 2 is the middle button and 3 is the right button. The x and y members are the coordinates of the mouse when it was pressed. The coordinates are relative to the embed (the window) and not to the widget.

EWL_CALLBACK_MOUSE_UP

This callback is called when the mouse was released on the widget or one of its children.

The event data is a Ewl_Event_Mouse_Up structure.

struct Ewl_Event_Mouse_Up
{
        unsigned int modifiers; /**< Modifiers that were pressed */
        int button;             /**< The mouse button that was released */
        int x;                  /**< X coordinate the mouse release occurred at */
        int y;                  /**< Y coordinate the mouse release occurred at */
};

The attributes have the same meaning as those seen in the EWL_EVENT_MOUSE_DOWN event.

EWL_CALLBACK_MOUSE_MOVE

This callback is called when the mouse was moved on the widget or one of its children.

The event data is a Ewl_Event_Mouse_Move structure.

struct Ewl_Event_Mouse_Move
{
        unsigned int modifiers; /**< Modifiers that were pressed */
        int x;                  /**< X coordinate the mouse moved to */
        int y;                  /**< Y coordinate the mouse moved to */
};

The attributes have the same meaning as those seen in the EWL_EVENT_MOUSE_DOWN event.

EWL_CALLBACK_MOUSE_WHEEL

This callback is called when the mouse wheel is rolled on the widget or one of its children.

The event data is a Ewl_Event_Mouse_Wheel structure.

struct Ewl_Event_Mouse_Wheel
{
        unsigned int modifiers; /**< Modifiers that were pressed */
        int x;                  /**< X coordinate the mouse left at */
        int y;                  /**< Y coordinate the mouse left at */
        int z;                  /**< Z value of mouse wheel */
        int dir;                /**< Direction mouse wheel scrolled */
};

EWL_CALLBACK_MOUSE_IN

This callback is called when the mouse enters the region of a widget.

The event data is a Ewl_Event_Mouse_In structure.

struct Ewl_Event_Mouse_In
{
        unsigned int modifiers; /**< Modifiers that were pressed */
        int x;                  /**< X coordinate the mouse entered at */
        int y;                  /**< Y coordinate the mouse entered at */
};

EWL_CALLBACK_MOUSE_OUT

This callback is called when the mouse leaves the region of a widget.

The event data is an Ewl_Event_Mouse_Out structure.

struct Ewl_Event_Mouse_Out
{
        unsigned int modifiers; /**< Modifiers that were pressed */
        int x;                  /**< X coordinate the mouse left at */
        int y;                  /**< Y coordinate the mouse left at */
};

EWL_CALLBACK_CLICKED

This callback is called when a widget has been clicked. This implies that the mouse has been pressed and released.

The event data is an Ewl_Event_Mouse_Up structure. See more details about this structure in the EWL_CALLBACK_MOUSE_UP section..

EWL_CALLBACK_FOCUS_IN 

Widget was selected by mouse or key.

EWL_CALLBACK_FOCUS_OUT 

Widget was deselected by mouse or key.

EWL_CALLBACK_VALUE_CHANGED 

Value in widget changed.

EWL_CALLBACK_STATE_CHANGED 

Alter the state of the appearance.

EWL_CALLBACK_APPEARANCE_CHANGED 

Theme key of widget changed.

EWL_CALLBACK_WIDGET_ENABLE 

Widget will accept input.

EWL_CALLBACK_WIDGET_DISABLE 

Widget no longer takes input.

EWL_CALLBACK_DND_POSITION 

Called when a drag and drop position event is fired.

EWL_CALLBACK_DND_ENTER 

Called when a drag starts on the widget.

EWL_CALLBACK_DND_LEAVE 

Called when a drag leaves the widget.

EWL_CALLBACK_DND_DROP 

Called when a drop happens on the widget.

EWL_CALLBACK_DND_DATA_RECEIVED 

Called when the drop data is available.

EWL_CALLBACK_DND_DATA_REQUEST