Library: iup.ew

• Description: Wrapper library for use with Eu3.1.1 and beyond
• Author: Charles Newbould (Bitbucket user: CANewbould)

This documentation needs to be read alongside the official Iup documentation, at http://webserver2.tecgraf.puc-rio.br/iup/

Issues (21 July 2016)

none

System routines

These elements act as the sandwich for all IUP programs:

include iup.ew
IupOpen()
...
IupClose()

IupOpen

include iup.ew
global procedure IupOpen()

Initializes the IUP toolkit. Must be called before any other IUP function.

Parameters: none

IupClose

include iup.ew
global procedure IupClose()

Ends the IUP toolkit and releases internal memory.

It will also automatically destroy all dialogs and all elements that have names.

Attributes

IupGetAttribute

include iup.ew
global function IupGetAttribute(atom widget, sequence attr)

Gets an interface element attribute.

Use only when the attribute value is a string.

(For other value types use the relevant procedure. For example: for an integer value use IupGetInt.)

Use upper-case for the attribute.

Returns: the attribute value or NULL, if the attribute is not set or does not exist.

IupGetInt

include iup.ew
global function IupGetInt(atom widget, sequence attr)

Gets the attribute value, where this is an integer.

Use upper-case for the attribute.

Returns: the integer value of an interface element attribute.

IupSetAttribute

include iup.ew
global procedure IupSetAttribute(atom widget, sequence attr, sequence val)

Sets an interface element attribute.

Use only when the attribute value is a string.

(For other value types use the relevant procedure. For example: for an integer value use IupSetInt.)

Use upper-case for the attribute and for many of the values.

Example:

-- See IUP documentation for relevent attributes for each widget type
IupSetAttribute(dlg, "TITLE", "Simple Dialog")
IupSetAttribute(dlg, "SIZE", "QUARTERxQUARTER")

IupSetAttributes

include iup.ew
global procedure IupSetAttributes(atom widget, sequence attrs)

Sets several attributes of an interface element.

Parameters: attrs is in the format "A1=V1, A2=V2, ...", where Ai is the name of an attribute and Vi is its value. Use upper-case for the attribute and for many of the values.

Example:

-- Values containing spaces can also be accommodated
IupSetAttributes(edit1, "EXPAND=YES, VALUE=\"Number 1\", TABTITLE = First," &
          "MULTILINE=YES")

IupSetInt

include iup.ew
global procedure IupSetInt(atom widget, sequence attr, integer val)

Sets the integer value of an interface element attribute.

Events

IupExitLoop

include iup.ew
global procedure IupExitLoop()

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

IupMainLoop

include iup.ew
global procedure IupMainLoop()

Executes the user interaction until one of the following occurs:

• a callback returns IUP_CLOSE;
• IupExitLoop is called; or
• the last visible dialog is hidden.

Must be included if a top-level-window (IupDialog) is included in the program.

IupSetCallback

include iup.ew
global procedure IupSetCallback(atom widget, sequence action, atom rid)

Associates a callback with an event. To define rid use the function Icallback.

IupSetCallbacks

include iup.ew
global function IupSetCallbacks(atom widget, sequence action, sequence rids)

Associates several callbacks to an event. To define each rid use the function Icallback. Returns: the same widget handle.

Icallback

include iup.ew
global function Icallback(atom rid)

"Converts" a routine_id to the appropriate form. For the library to work in all versions of Euphoria this function takes the routine_id, not the call-back routine's name.

Dialogs

IupDialog

include iup.ew
global function IupDialog(atom child)

Creates a dialog element. It manages user interaction with the interface elements. For any interface element to be shown, it must be encapsulated in a dialog.

Parameter: the identifier of an interface element. The dialog has only one child. It can be NULL.

Returns: the identifier of the created element, or NULL if an error occurs.

Example of IupDialog in action:

-- Example 6
-- A simple dialog

include iup.ew

IupOpen()
constant text = IupText(),
		dlg = IupDialog(text)
IupSetAttribute(text, "EXPAND", "YES")
IupSetAttribute(text, "MULTILINE", "YES")
IupSetAttribute(dlg, "TITLE", "Simple Dialog")
IupSetAttribute(dlg, "SIZE", "QUARTERxQUARTER")
IupShow(dlg)
IupMainLoop()    -- needed for IupDialog to work
IupClose()

IupHide

include iup.ew
global procedure IupHide(atom dlg)

Hides an interface element. This function has the same effect as attributing the value "NO" to the interface element's VISIBLE attribute.

IupPopup

include iup.ew
global procedure IupPopup(atom widget, integer x, integer y)

Shows a dialog or menu and restricts user interaction only to the specified element. It is equivalent to creating a Modal dialog in other toolkits.

If another dialog is shown after IupPopup using IupShow, then its interaction will not be inhibited. Every IupPopup call creates a new popup level that inhibits all previous dialogs interactions, but does not disable new ones (even if they were disabled by the Popup, calling IupShow will re-enable the dialog because it will change its popup level). IMPORTANT: The popup levels must be closed in the reverse order they were created or unpredictable results will occur.

For a dialog this function will only return the control to the application after a callback returns IUP_CLOSE, IupExitLoop is called, or when the popup dialog is hidden, for example using IupHide. For a menu it returns automatically after a menu item is selected. IMPORTANT: If a menu item callback returns IUP_CLOSE, it will also ends the current popup level dialog.

Parameters: the position of the popup item is determined by the co-ordinates (x, y), relative to the origin of the main screen.

Returns: IUP_NOERROR if successful. Returns IUP_INVALID if not a dialog or menu. If there was an error returns IUP_ERROR.

IupShow

include iup.ew
global procedure IupShow(atom dlg)

Displays a dialog in the current position, or changes a control VISIBLE attribute.

IupShowXY

include iup.ew
global procedure IupShowXY(atom dlg, integer x, integer y)

Displays a dialog in a given position on the screen. The values x and y give the horizontal and vertical positions respectively of the top left corner of the window, relative to the origin of the main screen.

Parameters: dlg - identifier of the dialog; x, y - co-ordinates from the top left corner of the window, relative to the origin of the main screen.

The following definitions can also be used for x:

• IUP_LEFT: Positions the dialog on the left corner of the main screen
• IUP_CENTER: Horizontally centralizes the dialog on the main screen
• IUP_RIGHT: Positions the dialog on the right corner of the main screen
• IUP_MOUSEPOS: Positions the dialog on the mouse position
• IUP_CENTERPARENT: Horizontally centralizes the dialog relative to its parent (Since 3.0)
• IUP_CURRENT: use the current position of the dialog. This is the default value in Lua if the parameter is not defined. (Since 3.0)

The following definitions can also be used for y:

• IUP_TOP: Positions the dialog on the top of the main screen
• IUP_CENTER: Vertically centralizes the dialog on the main screen
• IUP_BOTTOM: Positions the dialog on the base of the main screen
• IUP_MOUSEPOS: Positions the dialog on the mouse position
• IUP_CENTERPARENT: Vertically centralizes the dialog relative to its parent (Since 3.0)
• IUP_CURRENT: use the current position of the dialog. This is the default value in Lua if the parameter is not defined.(Since 3.0)

Dialogs (predefined)

IupAlarm

include iup.ew
global function IupAlarm(sequence title, sequence mess, sequence b1, object b2, object b3)

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

Parameters: the first button is obligatory and is named by b1. To set the second button set b2 to a text string; ditto for b3. (Note: you cannot set b3 and not b2!)

Returns: an integer - 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.

Example:

-- Example 2

include iup.ew
IupOpen()

constant b = IupAlarm("IupAlarm Example", "File not saved! Save it now?" ,"Yes" ,"No" ,"Cancel")
-- Shows a message for each selected button
if b = 0 then
        IupMessage("Save file", "Dialog closed, without selection")
elsif b = 1 then
        IupMessage("Save file", "File saved sucessfully - leaving program")
elsif b = 2 then
        IupMessage("Save file", "File not saved - leaving program anyway")
elsif b = 3 then
        IupMessage("Save file", "Operation cancelled")
end if
IupClose()

IupColorDlg

include iup.ew
global function IupColorDlg()

Creates the Colour Dialog element. It is a predefined dialog for selecting a color.

There are 3 versions of the dialog. One for Windows only, one for GTK only and one for all systems, but it is based on the IupColorBrowser control that depends on the CD library.

The Windows and GTK dialogs can be shown only with the IupPopup function. The IupColorBrowser based dialog is an IupDialog that can be shown as any regular IupDialog.

Returns: the identifier of the created element, or NULL if an error occurs.

Example:

--colordlg.exw

include iup.ew

IupOpen()

constant colordlg = IupColorDlg(),
       title = "IupColorDlg"

IupPopup(colordlg, 10, 10)

object res res = IupGetAttribute(colordlg, "VALUE")

if sequence(res) then
        IupMessage(title, "You chose: '" & res & "'")
else
        IupMessage(title, "You cancelled") 
end if

IupClose()

IupFileDlg

include iup.ew
global function IupFileDlg()

Creates the File Dialog element. It is a predefined dialog for selecting files or a directory. The dialog can be shown with the IupPopup function only.

Returns: the identifier of the created element, or NULL if an error occurs.

Example:

-- filedlg.exw

include iup.ew

IupOpen()

constant filedlg = IupFileDlg(),
        title = "IupFileDlg"

IupPopup(filedlg, 10, 10)

object res res = IupGetAttribute(filedlg, "VALUE")
if sequence(res) then
        IupMessage(title, "You chose: '" & res & "'")
else
        IupMessage(title, "You cancelled") 
end if

IupClose()

IupFontDlg

include iup.ew
global function IupFontDlg()

Creates the Font Dialog element. It is a predefined dialog for selecting a font. The dialog can be shown with the IupPopup function only.

Returns: the identifier of the created element, or NULL if an error occurs.

IupGetFile

include iup.ew
global function IupGetFile(sequence filename)

Shows a modal dialog of the native interface system to select a filename. Uses the IupFileDlg element.

Returns: a sequence containing:

1. a status code, whose values can be:
   • "1": New file.
   • "0": Normal, existing file.
   • "-1": Operation cancelled.
2. the name of the file selected.

Example:

--Example 3

include iup.ew

IupOpen()
sequence name, res
name = "*.txt"  -- name holds prompt
res = IupGetFile(name)
name = res[2]    -- name now holds chosen name

integer ret = res[1] -- status code
if ret = 1 then
  IupMessage("New file", name)
elsif ret = 0 then
  IupMessage("File already exists", name)
elsif ret = -1 then
  IupMessage("IupGetFile", "Operation cancelled")
end if
IupClose()

IupGetParam

include iup.ew
global function IupGetParam(sequence title, integer rid, object data, sequence format,
        sequence args)

Shows a modal dialog for capturing parameter values using several types of controls. The dialog uses the IupParam and IupParamBox controls internally.

Parameters: title - the dialog's title; rid - user callback to be called whenever a parameter value was changed, and when the user pressed the OK button. It can be NULL; data - user pointer passed to the user callback; format - a string describing all the parameters. It is a sequence of format strings for each parameter, see IupParam. (It is a list of variables address with initial values for the parameters. The number of lines in the format string (number of '\n') will determine the number of required parameters. The separators will not count as parameters. There is no maximum number of parameters (since 3.13), and this is now also the same in the Euphoria implementation; args - a sequence holding place-markers for the return data value defined in format.

Returns: a sequence containing to elements:

• a status code 1 if the button 1 was pressed, 0 if the button 2 was pressed or if an error occurred;
• the [1-length(args)] returned values, in the order set by format.

Example:

--Example 5b
--Asking for a Single String, or Number
include std/dll.e
include std/types.e
include iup.ew

IupOpen()
string name = "Give your profession"
sequence list, res
list = {"Teacher", "Explorer", "Engineer", "None of these"}
res = IupGetParam(name, NULL, NULL,
    "List: %l|Teacher|Explorer|Engineer|None of these|\n",
    {0})   -- place-holder for return value (res[2])
IupMessage("Choice!", list[res[2] + 1])	-- Lists are zero referenced
IupClose()

IupGetText

include iup.ew
global function IupGetText(sequence title, sequence text)

Shows a modal dialog to edit a multiline text. The parameter text defines the initial value displayed in the dialog. The C function called uses text to hold the returned text. Therefore it must have room for the edited string with at least maxsize length.

Returns: a sequence containing:

1. a status code; a non zero value if successful.
2. the full text in the modal dialog.

Example:

-- Example 4
-- Asking for Multiline Text

include iup.ew

procedure main()
    sequence resp
    IupOpen()
    resp = IupGetText("Name", "")
    if resp[1] = 1 then
        IupMessage("Thanks!", resp[2])
    end if
    IupClose()
end procedure

main()

IupMessage

include iup.ew
global procedure IupMessage(sequence title, sequence mess)

Shows a modal dialog containing a message. It simply creates and pops-up an IupMessageDlg.

Example:

--Example 1
include iup.ew
IupOpen()
IupMessage("YourApp", "Finished Successfully!")
IupClose()

IupMessageDlg

include iup.ew
global function IupMessageDlg()

Creates the Message Dialog element. It is a predefined dialog for displaying a message. The dialog can be shown with the IupPopup function only.

Returns: the identifier of the created element, or NULL if an error occurs.

IupProgressBar

include iup.ew
global function IupProgressBar()

Creates a progress dialog element. It is a predefined dialog for displaying the progress of an operation. The dialog is meant to be shown with the show functions IupShow or IupShowXY.

Returns: the identifier of the created element, or NULL if an error occurs.

Example:

...
gauge = IupProgressBar()
...
function timer_cb()
    if val < 1 then
        val += .05
        IupSetAttribute(gauge, "VALUE", sprint(val))
    else
        IupDestroy(timer)
        IupSetAttribute(btn, "TITLE", "Ended")
    end if
    return IUP_DEFAULT
end function
...

IupProgressDlg

include iup.ew
global function IupProgressDlg()

Creates a progress dialog element. It is a predefined dialog for displaying the progress of an operation. The dialog is meant to be shown with the show functions IupShow or IupShowXY.

Returns: the identifier of the created element, or NULL if an error occurs.

Layout (hierarchy)

IupGetBrother

include iup.ew
global function IupGetBrother(atom ih)

Returns the brother of an element.

Layout (management)

IupDestroy

include iup.ew
global procedure IupDestroy(atom widget)

Destroys an interface element and all its children. Only dialogs, timers, popup menus and images should be normally destroyed, but detached controls can also be destroyed.

Parameter: widget - identifier of the interface element to be destroyed.

Controls (containers)

IupFill

include iup.ew
global function IupFill()

Creates void element, which dynamically occupies empty spaces always trying to expand itself. Its parent should be an IupHbox, an IupVbox or a IupGridBox, or else this type of expansion will not work. If an EXPAND is set on at least one of the other children of the box, then the fill expansion is ignored.

It does not have a native representation.

IupFrame

include iup.ew
global function IupFrame(atom child)

Creates a native container, which draws a frame with a title around its child.

IupHbox

include iup.ew
global function IupHbox(sequence children)

Creates a void container for composing elements horizontally. It is a box that arranges the elements it contains from left to right.

IupTabs

include iup.ew
global function IupTabs(sequence children)

Creates a native container for composing elements in hidden layers with only one layer visible (just like IupZbox), but its visibility can be interactively controlled. The interaction is done in a line of tabs with titles and arranged according to the tab type. Also known as Notebook in native systems.

Parameter: children - list of the elements that will be placed in the box.

Returns: the identifier of the created element, or NULL if an error occurs.

IupVbox

include iup.ew
global function IupVbox(sequence children)

Creates a void container for composing elements vertically. It is a box that arranges the elements it contains from top to bottom.

Controls (standard)

IupButton

include iup.ew
global function IupButton(sequence title)

Creates an interface element that is a button. When selected, this element activates a function in the application. Its visual presentation can contain a text and/or an image.

IupCalendar

include iup.ew
global function IupCalendar()

Creates a month calendar interface element, where the user can select a date.

IupCanvas

include iup.ew
global function IupCanvas()

Creates an interface element that is a canvas - a working area for your application.

IupDatePick

include iup.ew
global function IupDatePick()

Creates a date-editing interface element, which can displays a calendar for selecting a date.

In Windows it is a native element. In GTK and Motif it is a custom element. Motif is not capable of displaying the calendar.

IupLabel

include iup.ew
global function IupLabel(sequence title)

Creates a label interface element, which displays a separator, a text or an image.

IupList

include iup.ew
global function IupList()

Creates an interface element that displays a list of items. The list can be visible or can be dropped down. It also can have an edit box for text input. So it is a 4 in 1 element. In native systems the dropped down case is called Combo Box.

IupText

include iup.ew
global function IupText()

Creates an editable text field.

Resources (menus)

IupItem

include iup.ew
global function IupItem(sequence title)

Creates an item of the menu interface element. It is so created that to generate an action, when selected, a specific call-back function is needed.

IupMenu

include iup.ew
global function IupMenu(sequence items)

Creates a menu element, which groups 3 types of interface elements: item, submenu and separator. Any other interface element defined inside a menu will be an error.

IupSeparator

include iup.ew
global function IupSeparator()

Creates the separator interface element. It shows a line between two menu items.

IupSubmenu

include iup.ew
global function IupSubmenu(sequence title, atom menu)

Creates a menu item that, when selected, opens another menu.

Example, using all menu elements:

--menus.exw

include iup.ew

function selected_cb(atom self)
    IupMessage("IupMenu", "You selected: " & IupGetAttribute(self, "TITLE") & "!")
    return IUP_CONTINUE
end function

function exit_cb()
    return IUP_CLOSE
end function

IupOpen()

constant
	item_open = IupItem("&Open"),
	item_save = IupItem("&Save"),
	item_undo = IupItem("&Undo"),
	item_exit = IupItem("E&xit"),
	menu_file = IupMenu({item_open, item_save, item_undo, IupSeparator(), item_exit}),
	sub1_menu = IupSubmenu("File", menu_file),
	menu = IupMenu({sub1_menu})

IupSetHandle("mymenu", menu)

constant dlg = IupDialog(IupCanvas())

IupSetAttribute(item_undo, "ACTIVE", "NO")
IupSetCallback(item_exit, "ACTION", Icallback(routine_id("exit_cb")))
IupSetCallback(item_open, "ACTION", Icallback(routine_id("selected_cb")))
IupSetCallback(item_save, "ACTION", Icallback(routine_id("selected_cb")))
IupSetAttributes(dlg, "SIZE = HALFxHALF, TITLE = Menus, MENU = mymenu")

IupShow(dlg)
IupMainLoop()

IupClose()

Resources (handles)

IupGetHandle

include iup.ew
global function IupGetHandle(sequence title)

Returns the identifier of an interface element that has an associated name using IupSetHandle.

IupGetName

include iup.ew
global function IupGetName(atom element)

Returns a name of an interface element, if the element has an associated name using IupSetHandle.

IupSetHandle

include iup.ew
global procedure IupSetHandle(sequence title, atom ih)

Associates a name with an interface element.

Resources (other)

IupTimer

include iup.ew
global function IupTimer()

Creates a timer which periodically invokes a callback when the time is up. Each timer should be destroyed using IupDestroy.

Returns: the identifier of the created element, or NULL if an error occurs.