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:

- Symbolic names are strings

- Absolute string values (e.g. dash style) are strings

- Absolute numeric values are numbers

- Absolute colors are tables with three entries with keys `r`, `g`, `b`

- Boolean values (for `minipage`, `farrow`, `rarrow`) are booleans (but the strings "true" and "false" can be used to set them)

- Transformations, Pinned, Linejoin, Linecap, Fillrule, Horizontal alignment, and Vertical alignment are represented by fixed strings, see table below.

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.