# 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)
    obj = ipe.Group(elements)               -- elements is a table of objects

Here, `attributes` is a table defining the desired attributes, see below. `shape` is a table defining a shape, see below.

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, stroke, fill) -- see below
    obj:get(property)                -- see below

    obj:xml()                        -- return XML representation
    obj:matrix()
    obj:setMatrix(m)
    obj:addToBBox(r, m)

    -- 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

## 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
    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,

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.

The arguments stroke and fill for set are only used if the property is `pathmode`. When the pathmode newly adds stroking or filling to an object, then it takes the stroke and/or fill color from this argument.

## 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", "quad", "bezier", or "spline". 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.