Events and Callbacks Guide
Using
Even though callbacks have different purposes from attributes, they are actually associated to an element by means of an attribute. To associate a function to a callback, the application must employ the IupSetAttribute function, linking the action to a name (passed as a string). From this point on, this name will refer to a callback. By means of function IupSetFunction, the user connects this name to the callback.
For example:
int myButton_action(Ihandle* self);
IupSetAttribute(myButton, "ACTION", "my_button_action");
IupSetFunction("my_button_action", (Icallback)myButton_action);Therefore, callbacks also have some of the attributes' functionalities. The most important one is inheritance. Though many callbacks are specific to a given element, a callback can be set to a composition element, such as a vbox, which contains other elements, and while the composition element does not call that callback all other elements contained in it will call the same callback, unless the callback is redefined in the element.
All callbacks receive at least the element which activated the action as a parameter (self).
The callbacks implemented in C by the application must return one of the following values:
- IUP_DEFAULT: Proceeds normally with user interaction. In case other return values do not apply, the callback should return this value.
- IUP_CLOSE: Makes the IupMainLoop function return the control to the application. Depending on the state of the application it will close all windows.
- IUP_IGNORE: Makes the native system ignore that callback action. Applies only to some actions. Please refer to specific action documentation to know whether it applies or not.
- IUP_CONTINUE: Makes the element to ignore the callback and pass the treatment of the execution to the parent element.
An important detail when using callbacks is that they are only called when the user actually executes an action over an element. A callback is not called when the programmer sets a value via IupSetAttribute. For instance: when the programmer changes a selected item on a list, no callback is called.
In a callback if one of the parameters is a string, this string may be modified during the callback if another IUP function (such as IupGetAttribute) is called.
Main Loop
IUP is an event-oriented interface system, so it will keep a loop �waiting� for the user to interact with the application. For this loop to occur, the application must call the IupMainLoop function, which is generally used right before IupClose.
When the application is closed by returning IUP_CLOSE in a callback or by user closing the last dialog, the function IupMainLoop will return.
The IupLoopStep and the IupFlush functions force the processing of incoming events while inside an application callback.
IupLua
In Lua, the callbacks are implemented as methods, using the language�s resources for object orientation. Thus, the element is implicitly passed as the self parameter and the functions do not need to return a value, since the binding is in charge of returning IUP_DEFAULT. Note that the callbacks in IupLua3 do not contain the suffix �_CB�, in IupLua5 the names are the same.
Callbacks of different types of interface events are registered by the library when they are initialized. These default callbacks call methods of the object receiving the event. Each different event calls a different method, which can have a few parameters. The objects are initialized with none of these methods set, so the programmer is in charge of setting them when required. They receive the same parameters as callbacks in C, in the same order, and they can either return a value or not. The following example shows the definition of an action for a button.
function myButton:action () local aux = self.fgcolor self.fgcolor = self.bgcolor self.bgcolor = aux end
Or you can do
function myButton_action(self) ... end myButton.action = myButton_action