1
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2
<html xmlns="http://www.w3.org/1999/xhtml">
4
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
5
<title>Ipelib: Ipelets written in Lua</title>
6
<link href="tabs.css" rel="stylesheet" type="text/css"/>
7
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
10
<!-- Generated by Doxygen 1.6.1 -->
11
<div class="navigation" id="top">
14
<li><a href="index.html"><span>Main Page</span></a></li>
15
<li><a href="modules.html"><span>Modules</span></a></li>
16
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
17
<li><a href="annotated.html"><span>Classes</span></a></li>
20
<div class="navpath"><a class="el" href="index.html">The Ipe library documentation</a> » <a class="el" href="ipelets.html">Ipelets</a>
23
<div class="contents">
26
<h1><a class="anchor" id="lua-ipelets">Ipelets written in Lua </a></h1><p>Ipelets written in Lua have access to the entire Ipe user interface, and can in principle do anything that Ipe can do.</p>
27
<p>An ipelet is a Lua script that is placed in Ipe's ipelet directory.</p>
28
<p>The script needs to define three global variables, namely <code>label</code>, <code>about</code>, and either <code>run</code> or <code>methods</code> (or both).</p>
30
<li><code>label</code> is a string containing the label (that is, the name) of the ipelet. It is shown in the Ipelet menu.</li>
33
<li><code>about</code> is a string containing an 'about' or copyright notice for the ipelet. Ipe displays this in the "About the ipelets" box.</li>
36
<li><code>run</code> is used if the ipelet contains only a single method. When the ipelet is invoked, the function <code>run</code> is called by Lua.</li>
39
<li><code>methods</code> is used if the ipelet contains more than one method. It is an array with an entry for each method. Each entry is a table with keys <code>label</code> (defining the label of the method) and <code>run</code> (a Lua function that will be called by Ipe to execute this method). If an entry does not have a <code>run</code> field, then the global <code>run</code> method is called instead.</li>
41
<p>If an ipelet defines no <code>label</code> variable, then the ipelet is not added to the Ipelet menu. Such ipelets can be used to customize Ipe.</p>
42
<p>When Ipe invokes an ipelet, the Lua method is called with two arguments: the first argument <em>model</em> is the active Ipe user interface, the second is the index of the method being invoked.</p>
43
<p>The "global" environment of the ipelet is a private environment for this ipelet only, so there is no need to fear polluting the global namespace - you can use names here freely. The commonly used names have been imported from Ipe's global namespace already, and you can access any others you may need through <code>_G</code>.</p>
44
<p>It is important that the ipelet does <em>not</em> directly modify the document. This would mess up the undo stack, and could cause Ipe to crash on undo or redo. Instead, to modify the document the ipelet needs to create an undo item <code>t</code> and call <code>model:register(t)</code>.</p>
45
<p>If all the ipelet does is to create a new object <code>obj</code>, then it can simply call </p>
46
<div class="fragment"><pre class="fragment">
47
model:creation("create new object", obj)
48
</pre></div><p>The following are some useful methods and data structures: </p>
49
<div class="fragment"><pre class="fragment">
50
model.doc -- the document
51
model.pno -- current page number
52
model.vno -- current view number
54
model:page() -- returns current page
56
model:register(t) -- register undo item and execute its redo method
57
model:creation("label", obj) -- register undo item for object creation
59
model.attributes -- attributes currently set in user interface
60
model.snap -- currently active snap settings
61
</pre></div><p>Look at the existing ipelets for inspiration. </p>
added
removed
build/doc/lua-ipelets.html
