Ipelib
Lua bindings for dialogs and menus

The ipeui module provides dialogs and popup menus for Lua. It does not depend on any other Ipe component, and can be reused in other Lua projects. The manual shows dialogs in ipelets with a complete example.

Global methods

There are a few global methods in the ipeui module:

ipeui.startBrowser(url)   -- on Win32 and Cocoa only
dt = ipeui.currentDateTime() -- returns string with current date and time

Predefined dialogs

The following are predefined dialogs. In all cases, parent can either be nil or a Window ID.

File dialog

Ask the user to select a filename for opening or for saving. 'type' is "open" or "save". 'filter' is a table with the file name filters. Each filter has two entries in the table, one with the name of the filter and the extensions in parenthesis (this is used by Qt), one with the pure patterns separated by semicolons (this is also used by Windows). Here is an example:

filter_save = { "XML (*.ipe *.xml)", "*.ipe;*.xml",
                "PDF (*.pdf)", "*.pdf" }

'dir' is the initially selected directory, or nil.

'name' is an initial name (without path) to show as the filename, or nil.

'selected' is the number of the initally selected file name filter (where 1 is the first filter), or nil.

The funtion returns nil, or both a file name and the number of the selected filter.

ipeui.fileDialog(parent, type, caption, filter, dir, name, selected)

Color dialog

-- choose a color
-- r,g,b are in the range 0.0 to 1.0
-- returns nil or a (r,g,b) triple
ipeui.getColor(parent, title, r, g, b)

Message box

-- show a message box
-- type is one of "none" "warning" "information" "question" "critical"
-- details may be nil
-- buttons may be nil (for "ok") or one of 
-- "ok" "okcancel" "yesnocancel", "discardcancel", "savediscardcancel", 
-- return 1 for ok/yes/save, 0 for no/discard, -1 for cancel
ipeui.messageBox(parent, type, text, details, buttons)

Dialogs

Other dialogs can be constructed programmatically. A dialog consists of various elements layed out in a grid, and a row of buttons underneath. Create the dialog by adding elements using 'add', and filling the button row using 'addButton'. The 'action' for 'addButton' can be one of the strings "accept" or "reject", or a Lua method.

d = ipeui.Dialog(parent, window_title, language)

-- row == -1 means last row, row == 0 means start new row
d:add(name, what, options, row, column, row_span, column_span)
d:addButton(name, caption, action)

d:setStretch("row", row_number, stretch_factor)
d:setStretch("column", column_number, stretch_factor)

d:set(name, value)
value = d:get(name)

-- enable/disable elements
d:setEnabled(name, true_or_false)

-- set to ignore escape when the value of field is equal to originalValue
d:set("ignore-escape", field, originalValue)

-- show dialog modally
accepted = d:execute()
accepted = d:execute(size)   -- where size == { width, height }

-- close the dialog from a Lua method (such as the action of a button
-- or checkbox); d:execute() then returns accepted
d:accept(accepted)           -- true or false

Note that on some platforms (Qt and JS), d:execute may yield. Closing the dialog causes the Lua thread to be resumed.

name can be an arbitrary string. what must be one of

button, text, list, label, combo, checkbox, input, image, sorter

options is a table. Most fields are optional:

-- button:
label="string"  (Required!)
action="accept" or "reject" or a Lua method

-- label:
label="string"  (Required!)

-- text:
read_only=bool
syntax="logfile" or "xml" or "latex"
select_all=bool
spell_check=bool
language=str

-- list and combo:
array of list items (strings)
can also contain a Lua method with key "action" (called when an item
is activated).

-- checkbox:
label="string"  (Required!)
action= Lua method  (called when state changed)

-- input:

-- image:
value=table     (see below, default is an empty preview)
width=number    (preview area width in pixels, default 180)
height=number   (preview area height in pixels, default 80)

-- sorter:
array of items  (see below)
width=number    (width of the element in pixels, default 300)
height=number   (height of the element in pixels, default 200)
readonly=bool   (default false; only the user can select, see below)

An image element shows a preview of a bitmap inside a fixed-size area. It does not load or display an actual ipe::Image object. Its value is a table that has exactly one of the following fields:

text="string"     (a text message)
path="string"     (the name of a PNG or JPEG file)
bitmap=table      (a bitmap in memory)

and optionally

zoom=number       (default 1.0)

A bitmap file or bitmap in memory is displayed centered in the preview area, with each of its pixels divided by zoom, and scaled down to fit the preview area if necessary. Transparent parts show the background of the preview area. The bitmap table has the fields

width=number      (number of pixel columns)
height=number     (number of pixel rows)
pixels="string"   (RGBA values in row order, 4 * width * height bytes,
                   alpha is not premultiplied)

If the file cannot be loaded, or if the table is empty, a message "Preview unavailable" is shown instead. The value of an image element can be changed using set, using a table in the same format. Examples:

d:add("preview", "image", { width=100, height=100,
                            value={ text="No preview yet" } }, 1, 1)
d:set("preview", { path="/tmp/picture.png", zoom=2.0 })
d:set("preview", { bitmap={ width=2, height=1, pixels="\255\0\0\255\0\0\255\128" } })

A sorter element shows a list of icons, like Ipe's page sorter. The user can delete items, mark and unmark them, and rearrange them. Items are rearranged by dragging them (all selected items move together) to a new position, marked by a vertical bar; dropping them below the last line or after the last item moves them to the end. A context menu (right click) offers "Delete", "Mark", and "Unmark" for the selected items, and "Cut" and "Insert" as an alternative way to move items: cut items are inserted before the item that was clicked (or at the end, when clicking on empty space). An item can also be marked by clicking its checkbox. The options table is an array of items, where each item is a table with the optional fields

mark=boolean      (true or false: the item has a checkbox, marked or not;
                   nil: no checkbox)
label="string"    (text shown below the icon)
bitmap=table      (the icon, a bitmap in memory in the format described above
                   for images; items without bitmap have an empty icon)

All icons are shown in a cell of the size of the largest bitmap. The value of a sorter, as returned by get, is a table of integers that describes the current state of the list: for every item that is still present, in the current order, it contains the number of the item in the table that was originally passed to add or set (starting from 1), and that number is negated if the item is marked. For instance, if the original table had four items, then

{ 3, 2, -4 }

means that the first item has been deleted, that the third item is now first in the list, and that the fourth item is marked. Items without checkbox are never marked. set replaces the items of a sorter by those of a new table (and the numbers refer to the new table). Before the dialog is shown, get returns the numbers of all items in their original order, marked as given. Example:

local items = {
  { label="Page 1", mark=false, bitmap=bitmap1 },
  { label="Page 2", mark=true, bitmap=bitmap2 },
  { label="Page 3", bitmap=bitmap3 },
  width=500, height=300 }
d:add("pages", "sorter", items, 1, 1)
...
order = d:get("pages")    -- for instance { 2, 3, -1 }

A sorter that is created with readonly=true cannot be modified by the user: items cannot be dragged, deleted, or marked, there is no context menu, and checkboxes are only displayed. Users can still scroll through the items and select them (one item, or several items using Ctrl and Shift). For a readonly sorter, get returns the numbers (from 1, never negated) of the selected items, in the order of the list, for instance { 2, 5 }. Nothing is selected at first, and after set. Only the user is restricted: Lua code can still replace the items of a readonly sorter using set. The readonly option is fixed when the element is added. set accepts the same options table again (so the readonly field may be present), but cannot change it. This makes sorters usable to let the user pick one or several items, for instance a symbol from a stylesheet.

The sorter element is available in all versions of Ipe. The Windows version has no drag and drop: items are rearranged using "Cut" and "Insert before" / "Insert after" (or "Insert at end") in the context menu, and items can only be marked and unmarked using the context menu, not by clicking the checkbox.

The Lua method for button, checkbox, combo, and list is called with the dialog as an argument. Do not capture the dialog inside the method, as this would create a cyclic reference that would stop the dialog from being garbage collected! (It also causes a crash on Qt if the dialog is destroyed by Lua after the parent window has already deleted it.)

The argument of set is:

  • a string value for label, text, and input,
  • a table for image (see above),
  • an array of items for sorter,
  • either an integer, a string, or an array of string items for list and combo,
  • a boolean for checkbox.

The result value of get is:

  • a string for text and input,
  • an integer for list (or nil if there is no current item) and combo,
  • a boolean for checkbox,
  • a table of integers for sorter (see above): the current order of the items, or the selected items if the sorter is readonly.

Popup menus

Popup menus are constructed and shown as follows:

m = ipeui.Menu(parent)  
item, subitem = m:execute(global_position)

When the menu is cancelled, execute returns nil.

You can then add items to the menu one by one. A simple item is added like this:

m:add("name", "Label")

When this item is selected, execute returns name, and an empty string.

The following line adds an entire submenu:

m:add("name", "Submenu", { "alpha", "beta", "gamma" } )

When an item from this submenu is selected, execute returns name and the name of the submenu item.

When the strings in the table are not directly the visible labels for the submenu, a Lua function can be used to convert them:

m:add("name", "Submenu", { "alpha", "beta", "gamma" },
      function (i, item) return "select " .. item end )

The final argument can either be a string or a function. If it is a string, then all items are checkable, and the item whose name is identical to the final argument is checked. Otherwise, the function maps item number and name to a color (three numbers in the range 0.0 to 1.0). This is then used to display a color icon.

Timers

Timers are constructed as follows:

t = ipeui.Timer(table, "method")

When the timer times out, it will call the method named method in the Lua table table. The timer stores only a weak reference to the table, so the timer will not stop the table from being garbage collected.

The timer is controlled using the methods:

timer:setInterval(interval)     -- an integer in milliseconds
timer:setSingleShot(bool)       -- default is repeating timer
timer:start()   
timer:stop()
a = timer:active()              -- true if the timer is running