Ipelib
Lua bindings for objects and attributes

The five Ipe objects are ipe::Group, ipe::Path, ipe::Text, ipe::Image, and ipe::Reference. They can be constructed from Lua as follows:

obj = ipe.Reference(attributes, name, pos)
obj = ipe.Text(attributes, text, pos)          -- Text of type label
obj = ipe.Text(attributes, text, pos, width)   -- Text of type minipage
obj = ipe.Path(attributes, shape, with_arrows)   
obj = ipe.Group(elements)       -- elements is a table of objects
obj = ipe.Image(rect, bitmap)   -- where bitmap is another Image object 

Here, attributes is a table defining the desired attributes, see below. shape is a table defining a shape, see below. To create path with arrows, you need to set with_arrows to true (it defaults to false). The arrow settings are then used from the attributes.

A bitmap can be created by reading from an image file:

bitmap, res = ipe.readImage(fname, format)

where format is one of "png" or "jpeg". If reading the bitmap fails, then bitmap is nil and res is an error message. Otherwise, bitmap is an Image object and res is the resolution in dots per inch. This will be (0,0) if the file does not contain that information.

Objects have the following methods:

obj:type()    -- return type as string: group, text, path, image, reference
obj:clone()   -- clone the object

obj:set(property, value)    -- see below
obj:get(property)           -- see below

obj:xml()                   -- return XML representation
obj:matrix()
obj:setMatrix(m)
obj:addToBBox(r, m)         -- including control points
obj:addToBBox(r, m, false)  -- without control points

-- text and reference objects only:
v = obj:position()
-- text objects only:
obj:setText(str)
str = obj:text()
-- path objects only:
shape = obj:shape()                      
obj:setShape(shape)            
-- group objects only:
n = obj:count()                  
shape = obj:clip()           -- nil if no clipping
obj:setClip(shape)
-- image objects only:
obj:info()                   -- returns table about bitmap
-- group objects only:
elements = obj:elements()    -- returns table with clones of elements 
element = obj:element(i)     -- returns clone of element #i
obj:elementType(i)           -- returns type of element #i

Attributes

Attributes are represented in Lua as follows:

The attributes argument to the object constructors is a table defining all desired attributes. Keys in the table are as follows. If a key is not present, the default value is used.

pathmode -- "stroked", "strokedfilled", "filled"
stroke   -- symbolic or color
fill     -- symbolic or color
dashstyle -- symbolic or absolute string
pen      -- symbolic or number
farrow   -- boolean
rarrow   -- boolean
farrowshape -- symbolic
rarrowshape -- symbolic
arrowsize  -- symbolic or number
symbolsize -- symbolic or number
symbolshape -- symbolic
textsize   -- symbolic or number
transformableText -- boolean
textstyle  -- symbolic
opacity    -- symbolic
tiling     -- symbolic
decoration -- symbolic ("normal" means no decoration)
minipage   -- boolean      
width      -- number
horizontalAlignment -- "left", "right", "hcenter"
verticalAlignment   -- "bottom", "baseline", "top", "vcenter"
linejoin            -- "normal", "miter", "round", "bevel"
linecap             -- "normal", "butt", "round", "square"
fillrule            -- "normal", "wind", "evenodd"
pinned              -- "none", "horizontal", "vertical", "fixed"
transformations     -- "translations", "rigid", "affine"

Properties

The set() and get() methods allow to access the attributes of objects. The property names are

    pen, symbolsize, 
    farrow, rarrow, farrowsize, rarrowsize, farrowshape, rarrowshape, 
    stroke, fill, markshape,
    pathmode, dashstyle, 
    textsize, textstyle, minipage, width, 
    opacity, tiling, gradient, 
    horizontalalignment, verticalalignment,
    linejoin, linecap, fillrule, 
    pinned, transformations,
    decoration

It is okay to set a property on objects that do not support them (for instance, "textsize" on a path object). Reading such properties results in an "undefined" return value.

Shape

The geometry of a path object and the clipping path of a group object is an ipe::Shape. This is represented in Lua as a pure Lua object, namely an array with one entry per subpath.

Each subpath is again a table with a type field whose value must be one of "ellipse", "closedspline", or "curve".

For an ellipse, element 1 of the table is the matrix.

For a closed spline, the table contains the control points.

For a curve, the table has a second field closed, which is either true or false. The table also has an entry for each segment of the curve. Each segment is again a table with a type field, whose value is one of "arc", "segment", "spline", or "oldspline". The segment table contains the control points of the segment. For arc segments, there is an additional arc field in the segment table that contains the arc as an ipe.Arc object.