Binding Lua

IUP - Portable User Interface

IupLua Advanced Guide

Exchanging Values between C and Lua

Each binding to a version of Lua uses different features of the language in order to implement IUP handles (Ihandle) in Lua. Therefore, functions have been created to help exchange references between Lua and C.

To push an Ihandle in Lua's stack, use the function:

iuplua_pushihandle(lua_State *L, Ihandle *n);

In Lua 3.2, the lua_State parameter does not exist.

To receive an Ihandle in a C function called from Lua, just use one of the following functions according to which Lua you are using: lua_getuserdata (Lua 3.2),  lua_touserdata (Lua 4) or lua_unboxpointer in (Lua 5).

In order to bring IUP handles created in C to Lua, the user can give the IUP handle a name by means of IupSetHandle and call in Lua the function IupGetFromC.

Ex:

lua_ihandle = IupGetFromC{"element_name"}

where element_name is the name of the element previously defined with IupSetHandle.

Error Handling

Error handling differ between each Lua version. To keep IupLua's API as compatible as possible and to improve the error report, the following functions have been created to execute Lua code:

int iuplua_dofile(lua_State *L, char *filename);
int iuplua_dostring(lua_State *L, const char *string, const char *chunk_name);

If the these functions are used, in every IupLua version the errors will be reported through the _ERRORMESSAGE function. If _ERRORMESSAGE is not defined by the user, IUP will use its default implementation (shows a dialog with the error message.)

If the user chooses to use lua_dofile and lua_dostring, errors will be handled according to the version of Lua used.

The Architecture Behind IupLua

The Lua API for the IUP system was based on object classes representing the different interface elements. A hierarchy was built among these classes, with the main purpose of reusing code. Code inheritance was implemented precisely as described in the Lua user guide.

The root of this hierarchy is the WIDGET class. It contains the basic procedures for construction, parameter type verification, and allocation of structures for controlling IUP�s interface elements. This class also defines the basic parameters of all classes, such as handle (which stores the handle of the associated IUP element) and parent (used to implement the inheritance mechanism).

Even though almost all classes directly descend from the WIDGET class, some other classes serve as mediators in the tree. This is the case of the COMPOSITION class, located among the composition element classes: IUPHBOX, IUPVBOX and IUPZBOX.

Some classes use part of the code from other classes, when they are very similar. This happens to IUPITEM and IUPTOGGLE, which reuse the code related to the verification of parameter types and to the definition of the action callback in the IUPBUTTON class. Class IUPMULTILINE inherits several characteristics from IUPTEXT, such as the definition of the action callback and the verification of parameter types.

The complete class hierarchy can be represented as follows:

WIDGET
   IUPBUTTON
      IUPITEM
      IUPTOGGLE
   IUPCANVAS
   COMPOSITION
      IUPHBOX
      IUPVBOX
      IUPZBOX
   IUPDIALOG
   IUPFILL
   IUPFRAME
   IUPIMAGE
   IUPLABEL
   IUPLIST
   IUPMENU
   IUPRADIO
   IUPSEPARATOR
   IUPSUBMENU
   IUPTEXT
      IUPMULTILINE