Ipelib
|
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.
There are a few global methods in the ipeui module:
ipeui.closeAllWindows() -- sends all windows a close event (not on Win32) ipeui.startBrowser(url) -- on Win32 only ipeui.setClipboard(text) -- store text on system clipboard text = ipeui.clipboard() -- get text property from system clipboard dt = ipeui.currentDateTime() -- returns string with current date and time
The following are predefined dialogs. In all cases, parent
can either be nil
or a Window ID.
-- get a filename from user -- type is "open" or "save" -- filter e.g. "XML (*.xml);;PDF (*.pdf)" -- dir is nil or a starting directory -- selected is nil or the filter originally selected -- returns nil if the dialog is canceled -- or filename and selected filter ipeui.fileDialog(parent, type, caption, filter, dir, selected) -- 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) -- 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) -- this dialog only returns when the external editor has finished ipeui.WaitDialog(parent, command)
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) 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", row_number, stretch_factor) d:set(name, value) value = d:get(name) -- set whether escape should be ignored (true/false) d:set("ignore-escape", flag) -- returns true if dialog was accepted d:execute() d:execute(size) -- where size == { width, height }
name can be an arbitrary string. what must be one of
button, text, list, label, combo, checkbox, input
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" -- list and combo: array of list items (strings) -- checkbox: label="string" (Required!) action= Lua method (called when state changed) -- input:
The argument of set is:
The result value of get is:
Popup menus are constructed and shown as follows:
m = ipeui.Menu(parent) item, no, 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, 0, 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, the index into the submenu, 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 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