System Guide
Initialization
Before running any of IUP’s functions, function IupOpen must be run to initialize the toolkit.
After running the last IUP function, function IupClose must be run so that the toolkit can free internal memory and close the interface system.
Executing these functions in this order is crucial for the correct functioning of the toolkit.
Between calls to the IupOpen and IupClose functions, the application can create dialogs and display them.
Therefore, usually an application employing IUP will have a code in the main function similar to the following:
int main(int argc, char* argv[])
{
if (IupOpen(&argc, &argv) == IUP_ERROR)
{
fprintf(stderr, "Error Opening IUP.")
return;
}
...
IupMainLoop();
IupClose();
return 0;
}
LED
LED is a dialog-specification language whose purpose is not to be a complete programming language, but rather to make dialog specification simpler than in C.
In LED, attributes and expressions follow this form:
elem = element[attribute1=value1,attribute2=value2,...](...expression...)
The names of the elements must not contain the “iup” prefix. Attribute values are always interpreted as strings, but they need to be in quotes (“…”) only when they include spaces. The “IUP_” prefix must not be added to the names of the attributes and predefined values. Expressions contain parameters for creating the element.
In LED there is no distinction between upper and lower case, except for attribute names.
Though the LED files are text files, there is no way to interpret a text in memory – there is only the IupLoad function, which loads a LED file and creates the IUP elements defined in it. Naturally, the same file cannot be loaded more than once, because the elements would be created again. This file interpretation does not map the elements to the native system.
The LED files are dynamically loaded and must be sent together with the application’s executable. However, this often becomes an inconvenience. To deal with it, there is the LEDC compiler that creates a C module from the LED contents.
To simply view a LED file objects use the LED viewer application, see IupView in the applications included in the distribution.
Available at the Download.
IupLua
The Lua Binding is an interface between the Lua language and IUP, a portable user-interface system. The main purpose of this package is to provide facilities for constructing IUP dialogs using the Lua language. Abstractions were used to create a programming environment similar to that of object-oriented languages, even though Lua is not one of such languages. The concept of event-oriented programming is broadly used here, because the IUP library is based on this model. Most constructions used in IupLua were strongly based on the corresponding constructions in LED.
In IupLua, attributes and expressions follow this form:
elem = iup.element{...expression...; attribute1=value1,attribute2=value2,...}
The names of element creation functions are in lower case, since they are actually constructors of Lua tables.
Callbacks can be implemented directly in Lua see Events and Callbacks Guide.
Even though there are sintatic sugars used to handle callbacks and attributes in Lua, most of the functions defined in C are exported to Lua, such as IupSetAttribute, IupGetBrother among others.
In IupLua we follow the same organization of the Lua libraries using a namespace ("iup") before all the definitions.
- All exported functions are accessed only through iup.FunctionName, including control initialization like iup.label.
- All callbacks in are accessed through their exact name in the C API.
- Numeric definitions where kept in upper case without the IUP_ prefix, such as iup.DEFAULT.
- String definitions for values are no longer supported, always use "YES", "NO", "ACENTER", etc.
IUP’s binding for Lua was made a posteriori and completely replaces the LED files. Besides, Lua is a complete language, so a good deal of the application can be implemented with it. However, this means that the application must link its program to the Lua and to the IupLua libraries, as well as the IUP library.
The Lua files are dynamically loaded and must be sent together with the application’s executable. However, this often becomes an inconvenience. To deal with it, there is the LuaC compiler that creates a C module from the Lua contents. For example:
luac -o myfile.lo myfile.lua bin2c myfile.lo > myfile.loh
In C, you can used a define to interchanged the use of .LOH files:
#ifdef _DEBUG
ret_val = lua_dofile("myfile.lua");
#else
#include "myfile.loh"
#endif
The distribution files include two executables, one for Lua 3 (IupLua3) and one for Lua 5.1 (IupLua51), that you can use to test your Lua code. Both applications have support for all the addicional controls and are
available at the Download.
IupLua Initialization
Before running any function from the Lua Binding, you must run the iuplua_open function to initialize the toolkit. This function should be run after a call to function IupOpen. All this is done in C in Lua’s host program.
Example:
int main(int argc, char* argv[])
{
IupOpen(&argc, &argv);
IupControlsOpen();
/* Lua 5 initialization */
L = lua_open();
luaL_openlibs(L);
iuplua_open(L); /* Initialize Binding Lua */
iupcontrolslua_open(L); /* Initialize additional controls binding Lua */
/* do other things, like running a lua script */
lua_dofile(L, "myfile.lua");
IupMainLoop(); /* could be here or inside "myfile.lua" */
lua_close(L);
IupControlsClose();
IupClose();
return 0;
}
See the example iuplua51_init.c for Lua 5.1.
It is also allowed to call iuplua_open without calling IupOpen. Then IupOpen will be internally called. This enable you to dynamically load IUP using Lua 5 "loadlib". This is also valid for all the additional controls when IUP is dynamically loaded. To call IupClose in this way you must call iuplua_close.
Here is an example on how to dynamically load IUP in Lua 5.1:
local iuplua_open = package.loadlib("iuplua51.dll", "iuplua_open")
iuplua_open()
local iupcontrolslua_open = package.loadlib("iupluacontrols51.dll", "iupcontrolslua_open")
iupcontrolslua_open()
Lua 5.1 "require" can be used for all the IupLua libraries, but the full library name should be used. For example: require"iuplua51", require"iupluacontrols51", and so on. Additionally the LUA_CPATH in UNIX must add the prefix "lib" to the search path, for example:
LUA_CPATH = ./\?.so\;./lib\?.so\;$LIBPATH_ARCH/\?.so\;$LIBPATH_ARCH/lib\?.so
You can also use require"iuplua" and so on, but the LUA_CPATH must contains the "51" pattern. For example:
LUA_CPATH = ./\?.so\;./lib\?51.so\;$LIBPATH_ARCH/\?.so\;$LIBPATH_ARCH/lib\?51.so
The simplest form require"iup" and so on, can not be used because there are IUP dynamic libraries with names that will conflict with the names used by require during search.