|
Ipelib
|
These are the Lua methods provided by the Ipe program itself. They are only available to Lua code running inside Ipe.
The application user interface object provides the GUI for the Ipe program. Ipelets reach it as model.ui; the manual explains the ipelet model with examples.
-- model is a Lua table containing methods that will be called -- by the ui when events occur ui = AppUi(model) -- returns window id of window -- (to be used as parent for dialogs) id = ui:win() ui:close() -- close window ui:setActionState(name, t) -- set whether action is checked t = ui:actionState(name) -- is action checked? -- return info about action: id, and whether it's always on id, alwaysOn = actionInfo(name) ui:explain(text) -- show message in status bar for a few seconds ui:setWindowTitle(caption) -- make a tool visible or invisible -- tool is one of "layers", "properties", "bookmarks", "notes" -- t is true or false ui:showTool(tool, t) ui:setNotes(n) -- set string for Notes tool -- set the list of recent files in the file menu (table of file names) ui:setRecentFiles(files) -- put the window in a screen mode: "normal", "maximized", or "full" ui:setScreen(mode) -- set the text of the snap indicator in the status bar ui:setSnapIndicator(text) -- set grid size and angle size selectors; both are numbers or symbolic names ui:setGridAngleSize(gridsize, anglesize) -- set the order in which symbolic names of this kind are shown in the -- selectors (kind as for stylesheets, names is a table of strings) ui:setPreferredOrder(kind, names) -- return the Windows menu id of an action and whether the action is -- always enabled (only used on Windows, to compute keyboard shortcuts) id, alwaysOn = ui:actionInfo(name) -- set contents of attribute selectors from style sheet ui:setupSymbolicNames(styleSheet) -- set attribute values displayed in user interface -- 'attributes' table see below ui:setAttributes(styleSheet, attributes) -- set layer list from page ui:setLayers(page, view) ui:setNumbers(?) ui:setBookmarks(?) -- page/view selector tool: -- select one page and return page number (or nil if canceled) pno = ui:selectPage(doc) -- select one view and return view number (or nil if canceled) vno = ui:selectPage(doc, page_no) ui:pageSorter(?) ui:setClipboard(text) -- store text on system clipboard -- get text or image from system clipboard -- if allowBitmap is false, only text is retrieved -- returns: -- "text", string if clipboard contains text -- "path", string if clipboard contains name of an image file -- "image", bitmap if clipboard contains actual pixel data format, value = ui:getClipboard(allowBitmap)
On GTK and in the JS version, the method is called getClipboardAsync and delivers its result to the coroutine passed as an additional argument. Use model:clipboard instead, which hides this difference.
The following methods work on the canvas inside the UI:
ui:setPage(page, pgno, view, styleSheet) -- set page shown on canvas
ui:setSnap(snap) -- for the 'snap' table see the manual
-- (chapter "Scripts and ipelets", "The snap settings")
ui:setFontPool(p) -- an opaque object obtained from an ipe.Document
-- 'pan' is a vector indicating the user coordinates at canvas center
v = ui:pan()
ui:setPan(v)
zoom = ui:zoom() -- a number
ui:setZoom(zoom)
v = ui:pos() -- current mouse position, after snapping
v = ui:unsnappedPos() -- current mouse position, before snapping
v = ui:simpleSnapPos() -- same, but ignoring angular snap
v = ui:globalPos() -- mouse position on screen
v, dpi = ui:canvasSize() -- size of canvas in pixels, monitor resolution
ui:setNumbering(t) -- true or false
ui:setFifiVisible(t) -- true or false
ui:setInkMode(t) -- true or false: mouse/pen input is freehand drawing
-- the canvas looks for external images relative to this folder
ui:setImageFolder(folder)
-- use the PDF resources (fonts) of this document for rendering text
ui:setResources(doc)
-- has the canvas encountered a Type 3 font since the last call?
-- (the flag is reset by this call)
t = ui:type3Font()
-- enable automatic angular snapping with this origin (a vector)
ui:setAutoOrigin(v)
ui:setSelectionVisible(t) -- true or false
ui:setPretty(t) -- true or false
ui:setVisibleVariant(variant) -- which variant is shown in the canvas
-- setCursor only implemented on Qt.
-- Windows 8 switches to a dot cursor automatically when using the pen.
ui:setCursor(name) -- name in "standard", "hand", "cross"
ui:setCursor(width, color) -- sets a colored dot cursor (on Qt)
ui:update() -- update canvas and tool
ui:update(false) -- update tool only
ui:finishTool()
ui:panTool()
ui:selectTool()
ui:transformTool()
ui:shapeTool()
-- tool for pasting an object (usually a group): obj is an object,
-- tool is a Lua tool table, which gets the additional methods
-- tool.setColor(r, g, b) and tool.setMatrix(m)
ui:pasteTool(obj, tool)
A view of a page can be rendered to a file or, for PNG, into a bitmap in memory. The document does not need to be the one shown in the UI.
-- format is one of "svg", "png", "eps", "pdf"
-- dest is the name of the output file, or nil (only for "png")
-- zoom is the number of pixels per point (only used for "png")
-- transparent: if true, the background of a PNG is transparent
-- instead of white (only used for "png")
-- nocrop: if true, the whole paper is rendered, including background
-- and title, instead of the bounding box of the page
result = ui:renderPage(doc, pageno, viewno, format, dest, zoom,
transparent, nocrop)
If dest is a file name, the result is true if the file was written, and false otherwise.
If dest is nil, format must be "png", and the result is nil if the page is empty or the bitmap would be too large, and otherwise a table with 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)
This is exactly the format of the bitmap field of an image element in an ipeui dialog. For example:
local bitmap = ui:renderPage(doc, 1, 1, "png", nil, 2.0, true, false)
d:set("preview", { bitmap=bitmap, zoom=2.0 })
These methods create files for the HTML presentation (reveal.js), and partially for export to PPTX (the json file will then be read by JS code that creates the final PPTX presentation).
Page and view numbers start from 1. Both methods return true if the file was written.
-- write a presentation of pages from_page to to_page, based on an HTML template ok = ui:createPresentation(doc, filename, html_template, from_page, to_page) -- write the JSON description of the document's views; -- if only_marked is true, only marked views are included ok = ui:createJson(doc, filename, only_marked)
In the JS version of Ipe (running in a browser or as a VS Code extension), Lua code can call methods of the JavaScript user interface object. Note that this is a function, not a method. Intended for internal use.
ui.js(method, arg1, ...) -- at most four arguments
This dialog is for running an external program (that is, latex or a text editor). The dialog is modal, so that the program refreshes but otherwise waits for the running command.
ui:waitDialog(command, text)
Here, 'command' is a string that is passed to a shell to run the command. The argument 'text' appears in the dialog.
The behaviour is different on differen platforms: