Guide

Getting Started

IUP has four important concepts that are implemented in a very different way from other toolkits.

First is the control creation timeline. When a control is created it is not immediately mapped to the native system. So some attributes will not work until the control is mapped. The mapping is done when the dialog is shown or manually calling IupMap for the dialog. You can not map a control without inserting it into a dialog.

Second is the attribute system. IUP has only a few functions because it uses string attributes to access the properties of each control. So get used to IupSetAttribute and IupGetAttribute, because you are going to use them a lot.

Third is the abstract layout positioning. IUP controls are never positioned in a specific (x,y) coordinate inside the dialog. The positioning is always calculated dynamically from the abstract layout hierarchy. So get used to the IupFill, IupHbox and IupVbox controls that allows you to position the controls in the dialog.

Fourth is the callback system. Because of the LED resource files IUP has an indirect form to associate a callback to a control. You associate a C function with a name using IupSetFunction, and then associate the callback attribute with that name using IupSetAttribute. But applications now should use the IupSetCallback function to directly associate a callback for a control. 

LED is the original IUP resource file which has been replaced in favor of Lua files, although it is still supported. But keep in mind that you can use IUP without using LED or Lua, by just using the C API.

Building Applications

To compile programs in C, simply include file iup.h. If the application only uses functions from IUP and other cross-platform libraries that have the same API in all platforms, then the application immediately becomes platform independent. The implementation of the IUP functions is different in each platform and the linker is in charge of solving the IUP functions using the library specified in the project/makefile. For further information on how to link your application, please refer to the specific driver documentation.

IUP can also work together with other interface toolkits. The main problem is the IupMainLoop function. If you are going to use only Popup dialogs, then it is very simple. But to use non modal dialogs without the IupMainLoop you must call IupLoopStep from inside your own message loop. Also it is not possible to use Iup controls with dialogs from other toolkits and vice-versa.

The generation of applications is highly dependent on each system, but at least the iup library must be linked.

To use the additional controls you will need the iupcontrols and iupcd libraries and the CD library cd.

Other controls are available in secondary libraries, they also may have other external dependencies, check the documentation of the control.

If you are using IUP libraries in Windows DLLs or in Posix SOs dynamic libraries, then it is not necessary to worry about secondary dependencies, only specify the libraries you directly use. If you link to the static libraries then you must include all the secondary dependencies.

To use the Lua Binding, you need to link the program with the iuplua library and with the lua library. The other secondary libraries also have their Lua binding libraries that must be linked to use the control in Lua.

The download files list includes the Tecgraf/PUC-Rio Library Download Tips document, with a description of all the available binaries.

Windows

In Windows, if you statically link the application with IUP you must link also with the libraries ole32.lib and comctl32.lib (provided with the compilers). The iup.rc resource file (or a custom version) should be included in the application's project/makefile so that some icons and cursors can be used when not using the DLLs and to enable Windows Visual Styles. iup.rc is located in "/etc" folder of the distribution.

There is also guides for using some IDEs: C++ Builder XDev-C++ OpenWatcom C++, Visual C++ 7 (Visual Studio 2003), Visual C++ 8 (Visual Studio 2005), Code Blocks and Eclipse for C++.

In Windows, when using Gcc to link an application the libraries order are as important as in UNIX. Always put the less dependent library at the end, for example:

-liup -lgdi32 -lcomdlg32 -lcomctl32 -luuid -loleaut32 -lole32

Motif

In Motif, IUP uses the Motif (Xm), the Xtoolkit (Xt) and the Xlib (X11) libraries. To statically link an application with IUP, use the following options in the linker call (in the same order):

-liup -lXm -lXmu -lXt -lX11 -lm

Though these are the minimum requirements, depending on the platform other libraries might be needed. Typically, they are X extensions (Xext), needed in SunOS, and Xpm (needed in Linux only). They must be listed after Xt and before X11. For instance:

-liup -lXm -lXpm -lXmu -lXt -lXext -lX11 -lm

Usually these libraries are placed in default directories, but you may require additional options:

Linux -L/usr/X11R6/lib -I/usr/X11R6/include
IRIX -L/usr/lib32 (X11)
-L/usr/Motif-2.1/lib32 -I/usr/Motif-2.1/include (Motif)
SunOS -L/usr/openwin/lib -I/usr/openwin/share/include (X11)
-L/usr/dt/lib -I/usr/dt/share/include (Motif)

GTK+ (since 3.0)

In UNIX it will need the X-Windows libraries just like the Motif driver. And in UNIX or in Windows it will need the "iupgtk" library and the following GTK+ libraries:

gtk-win32-2.0/gtk-3 gdk-win32-2.0/gdk-3 gdk_pixbuf-2.0 pango-1.0 pangowin32-1.0 gobject-2.0 gmodule-2.0 glib-2.0
   or
gtk-x11-2.0/gtk-3 gdk-x11-2.0/gdk-3 gdk_pixbuf-2.0 pango-1.0 pangox-1.0 gobject-2.0 gmodule-2.0 glib-2.0

In UNIX the following INCLUDES paths are necessary:

/usr/include/atk-1.0 /usr/include/gtk-2.0 /usr/include/cairo /usr/include/pango-1.0 /usr/include/glib-2.0 
and eventually:   /usr/lib/glib-2.0/include /usr/lib/gtk-2.0/include
             or   /usr/lib64/glib-2.0/include /usr/lib64/gtk-2.0/include

To build the driver with GTK 3.x support define USE_GTK3=Yes before calling make in the "iup/src" folder. Just the main library must be rebuilt.

Multithread

User interface is usually not thread safe and IUP is not thread safe. The general recommendation when you want more than one thread is to build the application and the user interface in the main thread, and create secondary threads that communicates with the main thread to update the interface. The secondary threads should not directly update the interface.

Dynamic Loading

Although we have dynamic libraries we do not recommend the dynamic loading of the main IUP library in Motif. This is because it depends on Motif and X11, you will have to load these libraries first. So it is easier to build a base application that already includes X11, Motif and the main IUP library than trying to load them all. In Windows this is not a problem.

The IUP secondary libraries can be easily dynamic loaded regardless of the system.

Building The Library

In the Downloads you will be able to find pre-compiled binaries for many platforms, all those binaries were built using Tecmake. Tecmake is a command line multi compiler build tool based on GNU make, available at http://www.tecgraf.puc-rio.br/tecmake. Tecmake is used by all the Tecgraf libraries and many applications.

You do not need to install Tecmake, scripts for Posix and Windows systems are already included in the source code package. Just type "make" in the command line on the main folder and all libraries and executables will be build.

In Linux, check the "Building Lua, IM, CD and IUP in Linux" guide.

In Windows, check the "Building Lua, IM, CD and IUP in Window" guide.

If you decide to install Tecmake, the Tecmake configuration files (*.mak) are available at the "src*" folders, and are very easy to understand. In the main folder, and in each source folder, there are files named make_uname.bat that build the libraries using Tecmake. To build for Windows using Visual C 9.0 (2008) for example, just execute "make_uname vc9" in the iup main folder, or for the DLLs type "make_uname dll9". The Visual Studio workspaces with the respective projects available in the source package is for debugging purposes only.

IUP runs on many different systems and interact with many different libraries such as Motif, OpenGL, Canvas Draw (CD) and Lua. You have to install some these libraries to build the secondary IUP libraries. Make sure you have all the dependencies for the library you want installed, see the documentation below.

If you are going to build all the libraries, the makefiles and projects expect the following directory tree:

/mylibs/
        iup/
        cd/
        im/
        lua5.1/

To control that location set the TECTOOLS_HOME environment variable to the folder were the CD, IM and Lua libraries are installed.

IUP_ASSERT can be defined to enable some runtime checks for the main API.

Libraries Dependencies

iupwin* -> gdi32 user32 comdlg32 comctl32 uuid ole32 (system - Windows)
iupmot* -> [Xpm Xmu Xext] Xt X11 (system - UNIX)
iupgtk* -> gtk-win32-2.0 gdk-win32-2.0 pangowin32-1.0(system - Windows)
        -> gtk-x11-2.0 gdk-x11-2.0 pangox-1.0 (system - UNIX)
        -> gdk_pixbuf-2.0 pango-1.0 gobject-2.0 gmodule-2.0 glib-2.0 (system - Windows/UNIX)
iupgl -> iup
      -> opengl32 glu32 glaux (system - Windows)
      -> GLU GL (system - UNIX)
iupcd -> iup
      -> cd
iupcontrols -> iupcd
iup_pplot -> iupcd
          -> PPlot (included)
iupim -> iup
      -> im
iupimglib -> iup
iuplua51 -> iup
         -> lua5.1
iupluacd51 -> iuplua51
           -> cdlua51
           -> iupcd
iupluacontrols51 -> iuplua51
                 -> iupcontrols
iupluagl51 -> iuplua51
           -> iupgl
iupluaim51 -> iuplua51
           -> imlua51
           -> iupim
iupluaole51 -> iuplua51
           -> iupole
iuplua_pplot51 -> iuplua51
               -> iup_pplot
iupole -> iup
iupweb -> iupole (Windows)
       -> webkit-1.0 (Linux)

(*) In Windows, "iupwin" is called "iup". 
    In Linux and BSD "iupgtk" is called "iup". 
    In IRIX, AIX and SunOS "iupmot" is called "iup".

As a general rule (excluding system dependencies): IUP depends on CD and IM, and IUPLua depends on Lua, CDLua and IMLua. Notice that not all IUP libraries depend on CD and IM.

Instead of building all the libraries, try building only the libraries you are going to use. The Makefile on the root folder will build all the libraries, but in each source folder there are secondary Makefiles. We use the following source code structure:

iup/
    src/         - The core library. Motif, GTK and Windows code
    srccd/       - CD_IUP canvas driver for the CD library
    srcconsole/  - Lua interpreter executable with pre-loaded IUP, CD and IM libraries
    srcgl/       - IupGLCanvas
    srcim/       - IUP/IM utilities
    srcimglib/   - Image Libraries with Icons, Logos and Bitmaps
    srcledc/     - ledc executable
    srclua3      - Lua3 binding, used internally at Tecgraf by some applications
    srclua5/     - Lua 5 binding
    srcole/      - IupOleControl
    srcpplot/    - IupPPlot
    srctuio/     - IupTuioClient
    srcweb/      - IupWebBrowser
    srcview/     - IupView executable

The Lua bindings for IUP, CD and IM (Makefiles and Pre-compiled binaries) depend on the LuaBinaries distribution. So if you are going to build from source, then use the LuaBinaries source package also, not the Lua.org original source package. If you like to use another location for the Lua files define LUA_SUFFIX, LUA_INC, LUA_LIB and LUA_BIN before using Tecmake.

In Ubuntu you will need to install the following packages and their dependencies (they are not installed by default):

libgtk2.0-dev (for the GTK driver)
    libmotif-dev and x11proto-print-dev (for the Motif driver, if used)
libgl1-mesa-dev (for the IupGLCanvas)
libglu1-mesa-dev (for the IupGLCanvas)
libwebkitgtk-dev (for the IupWebBrowser)

Using IUP in C++

IUP is a low level API, but at the same time a very simple and intuitive API. That's why it is implemented in C, to keep the API simple. But most of the actual IUP applications today use C++. To use C callbacks in C++ classes, you can declare the callbacks as static members or friend functions, and store the pointer "this" at the "Ihandle*" pointer as an user attribute. For example, you can create your dialog by inheriting from the following dialog.

class iupDialog
{
private:
  Ihandle *hDlg;
  int test;

  static int ResizeCB (Ihandle* self, int w, int h); 
  friend int ShowCB(Ihandle *self, int mode); 

public:
  iupDialog(Ihandle* child)
  { 
    hDlg = IupDialog(child); 
    IupSetAttribute(hDlg, "iupDialog", (char*)this); 
    IupSetCallback(hDlg, "RESIZE_CB", (Icallback)ResizeCB);
    IupSetCallback(hDlg, "SHOW_CB", (Icallback)ShowCB);
  }

  void ShowXY(int x, int y) { IupShowXY(hDlg, x, y); }

protected:

  // implement this to use your own callbacks
  virtual void Show(int mode) {};
  virtual void Resize (int w, int h){}; 
};

int iupDialog::ResizeCB(Ihandle *self, int w, int h)
{
  iupDialog *d = (iupDialog*)IupGetAttribute(self, "iupDialog");
  d->test = 1; // private members can be accessed in private static members
  d->Resize(w, h);
  return IUP_DEFAULT;
}

int ShowCB(Ihandle *self, int mode)
{
  iupDialog *d = (iupDialog*)IupGetAttribute(self, "iupDialog");
  d->test = 1; // private members can be accessed in private friend functions
  d->Show(mode);
  return IUP_DEFAULT;
}

This is just one possibility on how to write a wrapper class around IUP functions. Some users contributed with C++ wrappers, see next on Contributions.

Contributions

All the contributions use the same license terms of the IUP license.

C++ Wrappers

RSSGui by Danny Reinhold. (RSS_GUI_0_5.zip)

Described by his words:
- It works fine with the C++ STL and doesn't define a set of own string, list, vector etc. classes like many other toolkits do (for example wxWidgets).
- It has a really simple event handling mechanism that is much simpler than the system that is used in MFC or in wxWidgets and that doesn't require a preprocessor like Qt. (It could be done type safe using templates as in a signal and slot library but the current way is really, really simple to understand and to write.)
- It has a Widget type for creating wizards.
- It is not complete, some things are missing. It was tested only on the Windows platform.

IupTreeUtil by Sergio Maffra and Frederico Abraham. (IupTreeUtil3.zip or IupTreeUtil3.tar.gz)

 It is an utility wrapper for the IupTree control. It has several limitations, including to add leaves only after all branches inside a branch. It uses the STL.

IUP with C++ 11 and variadic templates (IUP++) by PulkoMandy

The IUP++ class registers itself as an IUP callback (with any arguments) and forwards the call to a C++ object and method. 

Tools

IupAsync by Ross Berteig

Described by his words:
IUP is not designed to be accessed from multiple threads, but occasionally there is a need (especially in a multi-threaded application) for the UI to update a display or dispatch an action in response to messages from other threads or from an OS component. To address this need, we designed an IUP control that translates calls from any application thread into a callback function guaranteed to be running in IUP's thread.
The IupAsync control is presently an alpha release proving the concept for the Windows platform only. It is intended that it be ported to the other platforms supported by IUP (GTK and Motif for Linux and OSX).

Drivers

IUP 3 MacOSX Driver by Heesob Park

A native driver for MacOSX using Cocoa. On going work. Help needed!

Language Bindings

A Basic Guide to using IupLua by Steve Donovan

A very nice introductory tutorial for IupLua.

Ruby-IUP by Heesob Park

ruby-iup is an extension module for Ruby that provides an interface to the IUP GUI toolkit. The source is hosted on github.com at http://github.com/phasis68/ruby-iup.

EuIup by Jeremy Cowgar

Iup wrapped for Euphoria.

FreeBasic Binding by AGS

The first release of FreeBASIC bindings for IUP 3. See the Forum post Portable GUI toolkit (IUP) version 3.0 (RC2)

Perl Binding by Kmx

Perl binding for IUP and related libraries.

Go-iup by Jeremy Cowgar

Iup wrapped for Go.

ScriptBasic Binding by John Spikowski

ScriptBasic binding for IUP. See the Forum posts about the Extension Module at IUP.

Component Pascal Binding by Boris Ilov

Component Pascal binding for IUP and CD, part of the BlackBox Framework.