NAME

IUP - Cross-platform GUI toolkit for building graphical user interfaces

DESCRIPTION

The IUP module is a cross-platform GUI toolkit designed to run on MS Windows (incl. Cygwin), GTK+ and Motif/X11. On all platform it uses native GUI widgets.

GTK	Windows Vista

Motif	Windows Classic

Source code: see 1-apps/app-sample1.pl

IUP's Strengths

Portability: The same GUI application written in perl works on Windows and UNIX systems.
Small and Simple API: This is rare. Many libraries assume that a GUI toolkit is also a synonymous with a system abstraction and accumulate a bunch of extra functions and/or classes that are not related to User Interface.
Easy to Learn: The learning curve for a new IUP user is often faster due to the small number of functions and to IUP's attributes concept which makes a lot of things more elegant and simpler to understand.
Native Look & Feel: Many toolkits draw their own controls. This gives an uniformity among systems, but also a disparity among the available applications in the same system. Native controls are also faster because they are drawn by the system.
Exhaustive Documentation: Which is not so common by other perl GUI toolkits. Good starting points are IUP and IUP::Manual::01_Introduction.
Advanced Visualization Elements: Thanks to IUP'S academic origin it has several fairly advanced GUI elemts handy for visualisation of scientific data (IUP::PPlot, IUP::Matrix) and 2D drawing (IUP::Canvas).

IUP's Background

IUP perl module is based on the following libraries delivered by Tecgraf - Computer Graphics Technology Group, PUC-Rio, Brazil http://www.tecgraf.puc-rio.br/iup:

iup library - see http://www.tecgraf.puc-rio.br/iup/
im library - see http://www.tecgraf.puc-rio.br/im/
cd library - see http://www.tecgraf.puc-rio.br/cd/

There is no need to install them before installing IUP module; they are handled by separate Alien::IUP module.

QUICK START

At this point we show just basic ideas behind IUP based GUI applications. For more details see IUP::Manual::01_Introduction. Or if you wanna skip the theory you can go directly to examples directory of IUP distribution.

Simple GUI Dialogs

use IUP ':all';

my ($ret, $b, $i, $a, $s, $l, $f, $c) = IUP->GetParam(
  "Simple Dialog Title", undef,
  #define dialog controls
  "Boolean: %b[No,Yes]{Boolean Tip}\n".
  "Integer: %i[0,255]{Integer Tip 2}\n".
  "Angle: %a[0,360]{Angle Tip}\n".
  "String: %s{String Tip}\n".
  "List: %l|item1|item2|item3|{List Tip}\n".
  "File: %f[OPEN|*.bmp;*.jpg|CURRENT|NO|NO]{File Tip}\n".
  "Color: %c{Color Tip}\n",
  #set default values
  1, 100, 45, 'test string', 2, 'test.jpg', '255 0 128'
);

IUP->Message("Results",
  "Boolean:\t$b\n".
  "Integer:\t$i\n".
  "Angle:\t$a\n".
  "String:\t$s\n".
  "List Index:\t$l\n".
  "File:\t$f\n".
  "Color:\t$c\n"
) if $ret;

Application	After "OK"

All functions from this category: Alarm, GetFile, GetColor, GetParam, GetText, ListDialog, Message - see simple GUI dialogs section.

Pre-defined Dialogs

use IUP ':all';

my $dlg = IUP::ColorDlg->new( VALUE=>"128 0 255", ALPHA=>"142",
                              SHOWHEX=>"YES", SHOWCOLORTABLE=>"YES",
                              TITLE=>"IUP::ColorDlg Test" );

$dlg->Popup(IUP_CENTER, IUP_CENTER); 

IUP->Message("Chosen color", "Color:\t" . $dlg->VALUE) if $dlg->STATUS;

Application	After "OK"

All pre-defined dialogs supported by IUP: IUP::ColorDlg, IUP::FileDlg, IUP::FontDlg, IUP::MessageDlg.

Custom Dialogs

use IUP ':all';

# demo callback handler
sub my_cb {
  my $self = shift;
  IUP->Message("Hello from callback handler");
}

# create the main dialog
sub init_dialog {
  my $menu = IUP::Menu->new( child=>[
               IUP::Item->new(TITLE=>"Message", ACTION=>\&my_cb ),
               IUP::Item->new(TITLE=>"Quit", ACTION=>sub { IUP_CLOSE } ),
             ]);

  my $frm1 = IUP::Frame->new( TITLE=>"IUP::Button", child=>
               IUP::Vbox->new( child=>[
                 IUP::Button->new( TITLE=>"Test Me", ACTION=>\&my_cb ),
                 IUP::Button->new( ACTION=>\&my_cb, IMAGE=>"IUP_Tecgraf", TITLE=>"Text" ),
                 IUP::Button->new( ACTION=>\&my_cb, IMAGE=>"IUP_Tecgraf" ),
                 IUP::Button->new( ACTION=>\&my_cb, IMAGE=>"IUP_Tecgraf", IMPRESS=>"IUP_Tecgraf" ),
               ])
             );

  my $frm2 = IUP::Frame->new( TITLE=>"IUP::Label", child=>
               IUP::Vbox->new( child=>[
                 IUP::Label->new( TITLE=>"Label Text" ),
                 IUP::Label->new( SEPARATOR=>"HORIZONTAL" ),
                 IUP::Label->new( IMAGE=>"IUP_Tecgraf" ),
               ])
             );

  my $frm3 = IUP::Frame->new( TITLE=>"IUP::Radio", child=>
               IUP::Vbox->new( child=>
                 IUP::Radio->new( child=>
                   IUP::Vbox->new( child=>[
                     IUP::Toggle->new( TITLE=>"Toggle Text", ACTION=>\&my_cb ),
                     IUP::Toggle->new( TITLE=>"Toggle Text", ACTION=>\&my_cb ),
                   ])
                 )
               )
             );

  my $frm4 = IUP::Frame->new( TITLE=>"IUP::Val", child=>IUP::Val->new( MIN=>0, MAX=>100 ) );

  my $frm5 = IUP::Frame->new( TITLE=>"IUP::ProgressBar", child=>IUP::ProgressBar->new( MIN=>0, MAX=>100, VALUE=>50 ) );

  my $hbox1 = IUP::Hbox->new( child=>[ $frm1, $frm2, $frm3 ] );
  my $hbox2 = IUP::Hbox->new( child=>[ $frm4, $frm5 ] );
  my $vbox1 = IUP::Vbox->new( child=>[ $hbox1, $hbox2 ], MARGIN=>"5x5", ALIGNMENT=>"ARIGHT", GAP=>"5" );

  return IUP::Dialog->new( MENU=>$menu, TITLE=>"Custom Dialog Sample", child=>$vbox1 );
}

# main program
my $dlg = init_dialog();
$dlg->Show();
IUP->MainLoop();

Application	After clicking "Test Me"

The main GUI element (the main application window) is always IUP::Dialog - for more info see IUP::Manual::05_DialogLayout.

USING IUP

What is included in IUP's interface ?

IUP Global Function

These functions are placed directly in IUP module - see GLOBAL FUNCTIONS. They are never exported from IUP module, you have to call them via IUP->FunctionName().

use IUP;
my $s = IUP->GetGlobal('SCREENSIZE');
my $d = IUP->GetGlobal('DRIVER');
print "GUI driver=$d\nScreen resolution=$s\n";

Global funtions cover:

handling IUP event loop
accessing global attributes
simple GUI dialogs
other helper functions

IUP Global Constants

All IUP related constants (e.g. IUP_CLOSE, IUP_ERROR, ...) are defined in IUP::Constants. Please note that:

all constants are defined via use constant pragma

constants are usable as barewords therefore they do not interpolate in interpolation contexts such as double-quoted strings

use IUP::Constants;

# beware!!!
print "color is - IUP_GREEN";    # prints: color is - IUP_GREEN

# this is probably what you want
print "color is - " . IUP_GREEN; # prints: color is - 0 255 0

IUP Elemenets

Currently available IUP elements:

The most important GUI element used for the main applications window:

IUP::Dialog
GUI elements:

IUP::Button, IUP::CanvasGL, IUP::Canvas, IUP::Cbox, IUP::Cells, IUP::ColorBar, IUP::ColorBrowser, IUP::Dialog, IUP::Dial, IUP::Expander, IUP::Fill, IUP::Frame, IUP::Gauge, IUP::GridBox, IUP::Hbox, IUP::Image, IUP::Item, IUP::Label, IUP::Link, IUP::List, IUP::MatrixList, IUP::Matrix, IUP::Menu, IUP::MglPlot, IUP::Normalizer, IUP::Ole, IUP::PPlot, IUP::ProgressBar, IUP::Radio, IUP::Scintilla, IUP::Sbox, IUP::ScrollBox, IUP::Separator, IUP::SpinBox, IUP::Spin, IUP::Split, IUP::Submenu, IUP::Tabs, IUP::Text, IUP::Toggle, IUP::Tree, IUP::Val, IUP::Vbox, IUP::Zbox
Pre-defined dialogs:

IUP::ColorDlg, IUP::FileDlg, IUP::FontDlg, IUP::MessageDlg, IUP::ProgressDlg
Special non-GUI elements:

IUP::Clipboard, IUP::Timer, IUP::User

All IUP elements are perl classes with new() constructor. The are used in this way:

my $button = IUP::Button->new( TITLE=>'Hello' ); # creating
$button->SetAttribute('FGCOLOR', '255 128 128'); # calling a method

For more info see IUP::Manual::02_Elements.

Using IUP in your perl program

By default, IUP doesn't import any other IUP related modules:

# import IUP but don't import other modules
use IUP;

You may, however, instruct IUP to import all modules by using the following syntax:

# import IUP + all IUP::* modules - short, easy but memory consuming
use IUP ':all';

Or you can import just basic elements (all except Matrix, Cells, Canvas, CanvasGL, PPlot, LayoutDialog, ElementPropertiesDialog)

use IUP ':basic';

Or you can import just selected modules by using:

# import IUP + IUP::Button and IUP::Menu
use IUP qw(Button Menu);

Which is equivalent to:

use IUP;
use IUP::Button;
use IUP::Menu;

IMPORTANT NOTE: If you are the first time reader of this document at this point you might wanna jumt to IUP::Manual::01_Introduction. The rest of this document is just the reference list of all functions available in the main IUP module.

GLOBAL FUNCTIONS

Handling IUP event loop

MainLoop()

Executes the user interaction until a callback returns IUP_CLOSE, IUP->ExitLoop is called, or hiding the last visible dialog.

IUP->MainLoop();

Returns: Always IUP_NOERROR

Notes:

When this function is called, it will interrupt the program execution until a callback returns IUP_CLOSE, IUP->ExitLoop is called, or there are no visible dialogs.

If you cascade many calls to IUP->MainLoop there must be a return IUP_CLOSE or IUP->ExitLoop call for each cascade level, hidding all dialogs will close only one level. Call IUP->MainLoopLevel to obtain the current level.

If IUP->MainLoop is called without any visible dialogs and no active timers, the application will hang and will not be possible to close the main loop. The process will have to be interrupted by the system.

When the last visible dialog is hidden the IUP->ExitLoop function is automatically called, causing the IUP->MainLoop to return. To avoid that set global attribute LOCKLOOP to "YES" before hiding the last dialog.

See Also: Open (global method), Close (global method), LoopStep (global method), ExitLoop (global method), IDLE_ACTION (callback), LOCKLOOP (attribute).

MainLoopLevel()

Returns the current cascade level of IUP->MainLoop. When no calls were done, return value is 0.

IUP->MainLoopLevel();

Returns: the cascade level

Notes:

You can use this function to check if IUP->MainLoop was already called and avoid calling it again.

A call to $element->Popup will increase one level.

See Also: Open (global function), Close (global function), LoopStep (global function), IDLE_ACTION (callback), LOCKLOOP (attribute).

LoopStep()

IUP->LoopStep();

See LoopStepWait.

LoopStepWait()

Runs one iteration of the message loop.

IUP->LoopStepWait();

Returns: IUP_CLOSE or IUP_DEFAULT

Notes:

This function is useful for allowing a second message loop to be managed by the application itself. This means that messages can be intercepted and callbacks can be processed inside an application loop.

IUP->LoopStep returns immediately after processing any messages or if there are no messages to process. IUP->LoopStepWait put the system in idle until a message is processed .

If IUP_CLOSE is returned the IUP->MainLoop will not end because the return code was already processed. If you want to end IUP->MainLoop when IUP_CLOSE is returned by IUP->LoopStep then call IUP->ExitLoop after IUP->LoopStep returns.

An example of how to use this function is a counter that can be stopped by the user. For such, the user has to interact with the system, which is possible by calling the function periodically.

This way, this function replaces old mechanisms implemented using the Idle callback.

Note that this function does not replace IUP->MainLoop.

See Also: Open (global function), Close (global function), MainLoop (global function), ExitLoop (global function), IDLE_ACTION (callback).

ExitLoop()

Terminates the current message loop. It has the same effect of a callback returning IUP_CLOSE.

IUP->ExitLoop();

Flush()

Processes all pending messages in the message queue.

IUP->Flush();

Notes:

When you change an attribute of a certain element, the change may not take place immediately. For this update to occur faster than usual, call IUP->Flush after the attribute is changed.

Important: A call to this function may cause other callbacks to be processed before it returns.

In Motif, if the X server sent an event which is not yet in the event queue, after a call to IUP->Flush the queue might not be empty.

SetIdle()

Setting global IDLE_ACTION callback ("idle callback") handler.

sub idle_cb {
  #...
}

IUP->SetIdle(\&idle_cb);  #set idle callback handler

#at some point later
IUP->SetIdle(undef);      #unset idle callback handler

See Also: IDLE_ACTION (callback).

Accessing global attributes

GetGlobal()

Returns an attribute value from the global environment. The value can be returned from the driver or from the internal storage.

IUP->GetGlobal($name);

$name: name of the attribute - see global attributes.

Returns: the attribute value. If the attribute does not exist undef is returned.

Notes:

This function's return value is not necessarily the same one used by the application to define the attribute's value.

See Also: SetGlobal (global function).

SetGlobal()

Defines an attribute for the global environment. If the driver process the attribute then it will not be stored internally.

IUP->SetGlobal($name, $value);

$name: name of the attribute - see global attributes.

$value: value of the attribute. If it equals undef the attribute will be removed.

Notes:

The value stored in the attribute is not duplicated. Therefore, you can store your private attributes, such as a structure of data to be used in a callback.

See Also: GetGlobal (global function).

GetLanguage()

Returns the value of global attribute LANGUAGE.

IUP->GetLanguage();

Returns: string with the language name - e.g. "ENGLISH".

See Also: SetLanguage (global function), LANGUAGE (attribute).

SetLanguage()

Defines the language used by some pre-defined dialogs. This is an old function, it just sets the global attribute LANGUAGE.

IUP->SetLanguage($lng);

$lng: Language to be used. Can have one of the following values:

"ENGLISH"
"PORTUGUESE"

Default: "ENGLISH"

Examples:

use IUP;
IUP->SetLanguage("ENGLISH"); 
IUP->Message("IUP Language", IUP->GetLanguage());

See Also: GetLanguage (global function), LANGUAGE (attribute).

Version()

Returns the value of global attribute VERSION.

my $verstring = IUP->Version();

Returns: the version of underlaying iup library - for example: "3.3".

VersionNumber()

Returns numeric represenatation of underlaying iup library version. The return value can be used for numeric comparison.

my $vernumger = IUP->VersionNumber();

Returns: the version number - for example: 303000 for version "3.3".

VersionDate()

Returns a release date of underlaying iup library.

my $vernumger = IUP->VersionDate();

Returns: date string - for example: "2010/11/09".

SetClassDefaultAttribute()

Changes the default value of an attribute for a class. It can be any attribute, i.e. registered attributes or user custom attributes.

IUP->SetClassDefaultAttribute($classname, $name, $value);

$classname: name of the class - BEWARE: this is IUP internal class name e.g. "dialog", "image" or "button"; not a perl class name:

"button" corresponds to IUP::Button
"canvas" corresponds to IUP::Canvas
"dialog" corresponds to IUP::Dialog
etc.

$name: name of the attribute

$value: new default value.

Notes:

If the value is "DEFAULTFONT", "DLGBGCOLOR", "DLGFGCOLOR", "TXTBGCOLOR", "TXTFGCOLOR" or "MENUBGCOLOR" then the actual default value will be the global attribute of the same name consulted at the time the attribute is consulted.

Attributes that are not strings and attributes that have variable names, like those which has a complementary number, can NOT have a default value. Some attributes can NOT have a default value by definition.

If the new default value is -1, ZZZ-test-this then the default value is set to be the system default if any is defined.

See Also: GetClassName (element method), GetClassType (element method), GetAllAttributes (element method).

Simple GUI dialogs

Alarm()

Shows a modal dialog containing a message and up to three buttons.

my $buttonA = IUP->Alarm($t, $m, $b1);  # message box with 1 button
#or
my $buttonB = IUP->Alarm($t, $m, $b1, $b2); # message box with 2 buttons
#or
my $buttonC = IUP->Alarm($t, $m, $b1, $b2, $b3); # message box with 3 buttons

$t: Dialog's title

$m: Message text

$b1: Text of the first button

$b2: Text of the second button (optional)

$b3: Text of the third button (optional)

Returns: the number of the button selected by the user (1, 2 or 3), or 0 if failed. It fails only if $b1 is not defined.

Notes:

This function shows a dialog centralized on the screen, with the message and the buttons. The \n character can be added to the message to indicate line change.

A button is not shown if its parameter is undef. This is valid only for $b2 and $b3.

Button 1 is set as the "DEFAULTENTER" and "DEFAULTESC". If Button 2 exists it is set as the "DEFAULTESC". If Button 3 exists it is set as the "DEFAULTESC".

The dialog uses a global attribute called "PARENTDIALOG" as the parent dialog if it is defined. It also uses a global attribute called "ICON" as the dialog icon if it is defined.

See Also: Message (global function), ListDialog (global function), GetFile (global function).

GetColor()

Shows a modal dialog which allows the user to select a color. Based on pre-defined dialog IUP::ColorDlg.

MS Windows
GTK

my ($r1, $g1, $b1) = IUP->GetColor($x, $y);
#or
my ($r2, $g2, $b2) = IUP->GetColor($x, $y, $r, $g, $b);

$x, $y: x, y values of the Popup function.

$r, $g, $b:Initialization values defining the color being selected when the dialog is shown.

Returns: List of three (R, G, B) values are returned if the OK button is pressed or three undef otherwise.

Notes:

The dialog uses a global attribute called "PARENTDIALOG" as the parent dialog if it is defined. It also uses a global attribute called "ICON" as the dialog icon if it is defined.

See Also: Message (global function), ListDialog (global function), Alarm (global function), GetFile (global function).

GetFile()

Shows a modal dialog of the native interface system to select a filename. Uses pre-defined dialog IUP::FileDlg.

MS Windows
GTK
Motif

my ($filename, $status) = IUP->GetFile($filename_spec);

$filename_spec: This parameter is used as an input value to define the default filter and directory. Example: "../docs/*.txt".

Returns: a list with 2 values: filename of chosen file; status code, whose values can be:

"1": New file.
"0": Normal, existing file.
"-1": Operation cancelled.

Notes:

The function will reuse the directory from one call to another, so in the next call will open in the directory of the last selected file.

The dialog uses a global attribute called "PARENTDIALOG" as the parent dialog if it is defined. It also uses a global attribute called "ICON" as the dialog icon if it is defined.

See Also: IUP::FileDlg (pre-defined dialog), Message (global function), ListDialog (global function), Alarm (global function), SetLanguage (global function).

GetParam()

Shows a modal dialog for capturing parameter values using several types of controls.

my ($status, @values) = IUP->GetParam($title, $action, $format, @initial_values);

$title: dialog title.

$action: user callback (reference to a perl function) to be called whenever a parameter value was changed, and when the user pressed the OK button. It can be undef.

$format: string describing the parameter

The format string must have the following format, notice the "\n" at the end:

"<text>%<x><extra>{<tip>}\n"

Where:

<text> is a descriptive text, to be placed to the left of the entry field in a label.

<x> is the type of the parameter (always a single character). The valid options are:

b = boolean (shows a True/False toggle)
i = integer (shows a integer number filtered text box)
r = real (shows a real number filtered text box, use "float" in C)
a = angle in degrees (shows a real number filtered text box and a dial)
s = string (shows a text box, BEWARE: there is hardcoded string size limitation 10240bytes)
m = multiline string (shows a multiline text box, BEWARE: there is hardcoded string size limitation 10240bytes)
l = list (shows a dropdown list box)
o = list (shows a list of toggles inside a radio)
t = separator (shows a horizontal line separator label, in this case text can be an empty string, not included in parameter count)
f = string (same as 's', but also show a button to open a file selection dialog box)
c = string (same as 's', but also show a color button to open a color selection dialog box)
n = string (same as 's', but also show a font button to open a font selection dialog box)
u = buttons names (allow to redefine the OK and Cancel button names, and to add a Help button, use [ok,cancel,help] as extra data, can omit one of them, it will use the default name, not included in parameter count) - BEWARE %u has to be the last item in $format string.

<extra> is one or more additional options for the given type

[min,max,step] are optional limits for integer and real types. The max and step values can be omitted. When min and max are specified a valuator will also be added to change the value. To specify step, max must be also specified. step is the size of the increment.
[false,true] are optional strings for boolean types to be displayed after the toggle. The strings can not have commas ',', nor brackets '[' or ']'.
mask is an optional mask for the string and multiline types. The dialog uses the MASK attribute internally. In this case we do no use the brackets '[' and ']' to avoid confusion with the specified mask.
|item0|item1|item2,...| are the items of the list. At least one item must exist. Again the brackets are not used to increase the possibilities for the strings, instead you must use '|'. Items index is zero based.
[dialogtype|filter|directory|nochangedir|nooverwriteprompt] are the respective attribute values passed to the IUP::FileDlg control when activated. All commas must exist, but you can let empty values to use the default values. No mask can be set.

<tip> is a string that is displayed in a TIP for the main control of the parameter.

There are no extra parameters for the color string. The mask is automatically set to capture 3 or 4 unsigned integers from 0 to 255 (R G B) or (R G B A) (alpha is optional).

The number of lines in the format string (number of '\n') will determine the number of required parameters. But separators will not count as parameters.

A integer parameter always has a spin attached to the text to increment and decrement the value. A real parameter only has a spin if a full interval is defined (min and max), in this case the default step is (max-min)/20. When the callback is called because a spin was activated then the attribute SPINNING of the dialog will be defined to a non undef and non zero value.

Examples of format strings:

my $format1 = "Real 2: %r[-1.5,1.5,0.05]\n";       # [min,max,step] example
my $format2 = "Numeric string: %s/d+\n";           # mask example
my $format3 = "Boolean: %b[No,Yes]{tip text}\n";   # [false,true] + tip text example
my $format4 = "List: %l|item0|item1|item2|item3|item4|item5|item6|\n"; # list example
my $format5 = "File: %f[OPEN|*.bmp;*.jpg|CURRENT|NO|NO]\n" # [dialogtype|filter|directory|nochangedir|nooverwriteprompt] example

@initial_values: list of variables with initial values for the parameters used in format string.

Returns: a $status code 1 if the "OK" button is pressed, 0 if the user canceled or if an error occurred + list of values corresponding to format string parameters, the values are returned by the function in the same order they were passed.

The function will abort if there are errors in the format string as in the number of the expected parameters.

Handling GetParam Callback:

This callback is called whenever a parameter value was changed, and when the user pressed the OK button.

sub getparam_cb {
  my ($dialog, $param_index) = @_;
  #...
}

$dialog: Reference to the dialog object (IUP::Dialog).

$param_index: Current parameter index (0 based) being changed. It is -1 if the user pressed the OK button. It is -2 after the dialog is mapped and just before it is shown. It is -3 if the user pressed the Cancel button. It is -4 if the user pressed the Help button, if any.

Returns: You can reject the change or the OK action by returning 0 in the callback, otherwise you must return 1.

The easiest way to retrieve a parameter inside the callback is via GetParamValue method:

sub getparam_cb {
  my ($dialog, $param_index) = @_;
  my $oldvalue = $dialog->GetParamValue(2); #get value of the element with index 2 (index is 0-based)
  my $newvalue;
  #...   
  $dialog->GetParamValue(2, $newvalue); #set value of the element with index 2 to $newvalue
  return 1;
}

BEWARE: You should not programmatically change the current parameter value (with index == $param_index) during the callback. On the other hand you can freely change the value of other parameters.

BEWARE: Programmatical changes are not filtered.

Handling GetParam Callback (even more advanced):

Use the $dialog method GetParamParam to get the reference to element representing given parameter:

my $parameter = $dialog->GetParamParam($n);

where $n is the parameter index in the order they are specified starting at 0, but separators and button names are not counted. Notice that this is not the actual control, which is internally stored in parameter's attribute "CONTROL".

Avaliable attributes of $parameter (do not try to use them from perl unless you know what can happen):

"LABEL" - returns an IUP Ihandle, the label associated with the parameter.
"CONTROL" - returns an IUP Ihandle, the real control associated with the parameter.
"AUXCONTROL" - returns an IUP Ihandle, the auxiliary control associated with the parameter (only for Valuators).
"INDEX" - returns an integer value associated with the parameter index.
"VALUE" - returns the parameter value as a string. It usually contains the new value of the control while the VALUE attribute of the control still has the old value.

GetText()

Shows a modal dialog to edit a multiline text.

my $text = IUP->GetText($title, $initial_text);

$initial_text: It contains the initial value of the text.

Returns: The text or undef if an error occured.

Notes:

The dialog uses a global attribute called "PARENTDIALOG" as the parent dialog if it is defined. It also uses a global attribute called "ICON" as the dialog icon if it is defined.

See Also: Message (global function), ListDialog (global function), Alarm (global function), SetLanguage (global function).

ListDialog()

Shows a modal dialog to select items from a simple or multiple selection list.

my $list = ["Blue", "Red", "Green", "Yellow", "Black", "White", "Gray", "Brown"];

#simple selection
my $status = IUP->ListDialog($title, $list, $mark, $max_lin, $max_col);

#multi selection
my $status = IUP->ListDialog($title, $list, [0, 1, 0, 0, 1, 1, 0, 0], $max_lin, $max_col);

$title: Text for the dialog's title

$list: A reference to array of list items.

$mark: Initial selected item. For simple selection - has to be a scalar value (0-based index into $list array). For multiple selection - has to be an arrayref (must have the same numer of elements as $list size) with values "1" for selected items, "0" for unselected items.

$max_col: Maximum number of columns in the list.

$max_lin: Maximum number of lines in the list.

Returns: When simple selection, the function returns the index of the selected option (starts at 0), or -1 if the user cancels the operation.

When multiple selection, the function returns -1 when the user cancels the operation. If the user does not cancel the operation the function returns arrayref with a list of values "1" for selected items, "0" for non-selected items.

Notes: The dialog uses a global attribute called "PARENTDIALOG" as the parent dialog if it is defined. It also uses a global attribute called "ICON" as the dialog icon if it is defined.

See Also: Message (global function), GetFile (global function), Alarm (global function).

Message()

Shows a modal dialog containing a message. It simply creates and popup a IUP::MessageDlg.

MS Windows
GTK
Motif

IUP->Message($message);
#or
IUP->Message($title, $message);

$title: dialog title

$message: text message contents

Notes:

The Message function shows a dialog centralized on the screen, showing the message and the "OK" button. The "\n" character can be added to the message to indicate line change.

The dialog uses a global attribute called "PARENTDIALOG" as the parent dialog if it is defined. It also uses a global attribute called "ICON" as the dialog icon if it is defined (used only in Motif, in Windows MessageBox does not have an icon in the title bar).

See Also: GetFile (global function), ListDialog (global function), Alarm (global function), IUP::MessageDlg (pre-defined dialog).

Recording and Re-playing User Input

PlayInput()

Reproduces all mouse and keyboard input from a given file.

my $ret = IUP->PlayInput($filename);

$filename: name of the file to be played. undef will stop playing. "" will pause and restart a file already being played.

Returns: IUP_NOERROR if successful, IUP_ERROR if failed to open the file for writing. If already playing

The file must had been saved using the RecordInput function. Record mode will be automatically detected.

This function will start the play and return the control to the application. If the file ends all internal memory used to play the file will be automatically released.

It uses the MOUSEBUTTON global attribute to reproduce the events.

IMPORTANT: See the documentation of the MOUSEBUTTON attribute for further details and current limitations.

The file must had been generated in the same operating system. Screen size differences can exist, but if different themes are used then mouse precision will be affected.

RecordInput()

Records all mouse and keyboard input in a file for later reproduction.

my $ret = IUP->RecordInput($filename, $mode);

$filename: name of the file to be saved. undef will stop recording.

$mode: flag for controlling the file generation. Can be: IUP_RECBINARY or IUP_RECTEXT.

Returns: IUP_NOERROR if successful, IUP_ERROR if failed to open the file for writing.

Notes:

Any existing file will be replaced.
Must stop recording before exiting the application.
It uses the global callbacks enabled by the INPUTCALLBACKS global attribute.
Mouse position is relative to the top left corner of the screen and it is independent from the controls and dialogs being manipulated.
The generated file can be used by PlayInput to reproduce the same events.

Other helper functions

CopyClassAttributes()

Copies all registered attributes from one element to another. Both elements must be of the same internal class (see GetClassName).

IUP->CopyClassAttributes($src_element, $dst_element);

$src_elem: reference of the source element.

$dst_elem: reference of the destination element.

See Also: GetClassAttributes (global function), GetClassName (element method), GetClassType (element method), GetAllAttributes (element method), SaveClassAttributes (element method).

GetAllClasses()

Returns the internal names of all registered classes.

my @list1 = IUP->GetAllClasses();
#or
my @list1 = IUP->GetAllClasses($max_n);

$max_n: maximum number of names we want to receive. Can be omitted.

Returns: The list of all names (or just $max_n first items). The names are internal iup library class names not perl class names:

"button" corresponds to IUP::Button
"canvas" corresponds to IUP::Canvas
"dialog" corresponds to IUP::Dialog
etc.

See Also: GetClassName (element method), GetClassType (element method), GetAllAttributes (element method).

GetAllDialogs()

Returns the names of all dialogs that have an associated name using $elem->SetName() or using LED - IUP->LoadLED(). Other existing dialogs (without assigned name) will not be returned.

my @list1 = IUP->GetAllDialogs();
#or
my @list1 = IUP->GetAllDialogs($max_n);

$max_n: maximum number of names we want to receive. Can be omitted.

Returns: The list of all names (or just $max_n first items).

See Also: SetName (element method), GetName (element method), GetByName (global function), GetAllNames (global function).

GetAllNames()

Returns the names of all interface elements that have an associated name using $elem->SetName() or using LED - IUP->LoadLED().

my @list1 = IUP->GetAllNames();
#or
my @list1 = IUP->GetAllNames($max_n);

$max_n: maximum number of names we want to receive. Can be omitted.

Returns: The list of all names (or just $max_n first items).

See Also: SetName (element method), GetName (element method), GetByName (global function), GetAllDialogs (global function).

GetClassAttributes()

Returns the names of all registered attributes of a class.

my @list1 = IUP->GetClassAttributes($classname);
#or
my @list2 = IUP->GetClassAttributes($classname, $max_n);

$classname: internal name of the class - e.g. "button", "image" or "dialog"; not a perl class name:

"button" corresponds to IUP::Button
"canvas" corresponds to IUP::Canvas
"dialog" corresponds to IUP::Dialog
etc.

$max_n: maximum number of names we want to receive. Can be omitted.

Returns: the list of all names (or just $max_n first items).

See Also: GetClassName (element method), GetClassType (element method), GetAllAttributes (element method).

GetClassCallbacks()

Returns the names of all registered callbacks of a class.

my @list1 = IUP->GetClassCallbacks($classname);
#or
my @list2 = IUP->GetClassCallbacks($classname, $max_n);

$classname: internal name of the class - e.g. "button", "image" or "dialog"; not a perl class name:

"button" corresponds to IUP::Button
"canvas" corresponds to IUP::Canvas
"dialog" corresponds to IUP::Dialog
etc.

$max_n: maximum number of names we want to receive. Can be omitted.

Returns: the list of all names (or just $max_n first items).

See Also: GetClassName (element method), GetClassType (element method), GetAllAttributes (element method).

GetFocus()

Returns the reference to a GUI element that has the keyboard focus, i.e. the element that will receive keyboard events.

my $elem = IUP->GetFocus();

See Also: SetFocus (element method).

GetIhClassName()

my $classname = GetIhClassName($elem->ihandle); 
# gives the same output as
$elem->GetClassName();

The same as element method GetClassName.

GetByIhandle()

Returns the reference to a GUI element that is associated with internal ihandle given as a parameter. (avoid this function if possible)

my $elem = IUP->GetByIhandle($ihandle);

$ihandle: In fact C pointer - be carefull.

GetByName()

Returns the reference to a GUI element that has an associated name using $elem->SetName() or using LED - IUP->LoadLED().

my $elem = IUP->GetByName($name);

$name: name of an GUI element

Notes:

This function is used for integrating IUP and LED. To manipulate an interface element defined in LED, first capture its reference using function GetByName, passing the name of the GUI element as parameter, then use this reference on the calls to IUP element methods - for example:

use IUP;
my $ledfile = 'file.led';
IUP->LoadLED($ledfile) or die "cannot load '$ledfile'\n";
my $button = IUP->GetByName('button1');
die "GetByName() failed\n" unless $button;
print "FGCOLOR=", $button->GetAttribute('FGCOLOR'), "\n";

See Also: SetName (element method), LoadLED (global function), IUP::Manual::08_UsingLED.

Help()

Opens the given URL. In UNIX executes Netscape, Safari (MacOS) or Firefox (in Linux) passing the desired URL as a parameter. In Windows executes the shell "open" operation on the given URL.

In UNIX you can change the used browser setting the environment variable IUP_HELPAPP or using the global attribute "HELPAPP".

It is a non synchronous operation, i.e. the function will return just after execute the command and it will not wait for its result.

IUP->Help($url);

$url: may be any kind of address accepted by the Browser, that is, it can include 'http://', or be just a file name, etc.

Returns: 1 if successfull, -1 if failed. In Windows can return -2 if file not found.

LoadLED()

Loads and compiles a LED specification from file.

my $rv1 = IUP->LoadLED($led_filename);
#or
my $rv2 = IUP->LoadLED(\$led_string); #passing as a reference

$led_filename: name of the file containing the LED specification.

$led_string: string with the LED specification

Returns: undef if the file was successfully compiled; otherwise it returns a string containing the error message.

Notes:

Each time the function loads a LED file, the elements contained in it are created. Therefore, the same LED file cannot be loaded several times, otherwise the elements will also be created several times.

isXkey()

Informs if a given key is an extended code (returns 1) or not (returns 0).

my $is_xkey = IUP->isXkey($code);

$code: Key code number e.g. value passed to K_ANY callback handler.

Returns: 1 or 0

isShiftXkey()

Informs if a given key is an extended code using the Shift modifier (returns 1) or not (returns 0).

my $is_shiftxkey = IUP->isShiftXkey($code);

$code: Key code number e.g. value passed to K_ANY callback handler.

Returns: 1 or 0

isCtrlXkey()

Informs if a given key is an extended code using the Ctrl modifier (returns 1) or not (returns 0).

my $is_ctrlxkey = IUP->isCtrlXkey($code);

$code: Key code number e.g. value passed to K_ANY callback handler.

Returns: 1 or 0

isAltXkey()

Informs if a given key is an extended code using the Alt modifier (returns 1) or not (returns 0).

my $is_altxkey = IUP->isAltXkey($code);

$code: Key code number e.g. value passed to K_ANY callback handler.

Returns: 1 or 0

isSysXkey()

Informs if a given key is an extended code using the Sys (on Windows WindowKey, on Mac AppleKey) modifier (returns 1) or not (returns 0).

my $is_sysxkey = IUP->isSysXkey($code);

$code: Key code number e.g. value passed to K_ANY callback handler.

Returns: 1 or 0

isPrintable()

Informs if a key can be directly used as a printable character (31 < ASCII code < 127).

my $is_printable = IUP->isPrintable($code);

$code: Key code number.

Returns: 1 (is printable) or 0 (otherwise)

isShift()

Checks the given mouse buttons and keyboard keys status string (see BUTTON_CB callback) whether Shift key was pressed at the time of mouse click event or not.

my $shift_pressed = IUP->isShift($status);