|  |  | 14.3 Ipe object elements

## 14.3 Ipe object elements

In the following, we explain the Ipe object elements currently understood by Ipe.

A "top-level" Ipe object, that is an object directly inside a `<page>` element, can take the optional `layer` attribute. This attribute indicates into which layer the object goes. If it is missing, the object goes into the same layer as the preceding object. If the first object has no layer attribute, it goes into the layer defined first in the page, or the default "alpha" layer.

Any Ipe object can take the optional attributes `stroke` and `matrix`. The value of `stroke` is a color--either a symbolic name defined in one of the style sheets of the document, one of the predefined names "void", "black", or "white", a single real number between 0 (black) and 1 (white) indicating a gray level, or three real numbers in the range [0,1] indicating the red, green, and blue component (in this order), separated by white space.

The value of `matrix` is a sequence of six real numbers, separated by white space, indicating a transformation matrix for all coordinates inside the element (including embedded elements if this is a `<group>` element). A missing `matrix` attribute is interpreted as the identity matrix.

### 14.3.1 The `<mark>` element

The `<mark>` element defines a mark object. It takes the required attributes `size` (a real number or symbolic name), `type` (an integer, see `IpeMark`), and `<pos>` (two real numbers, separated by white space).

### 14.3.2 The `<ref>` element

The `<ref>` element refers to an Ipe object defined in the style sheet. It has one required attribute `name`, which must be a name of a `<template>` defined in the style sheet. The object will be reused at the position defined in the template, unless the `matrix` is set.

### 14.3.3 The `<image>` element

The `<image>` element defines a bitmap object. The tag takes the required attributes `bitmap` (the value is an integer referring to a bitmap defined in a `<bitmap>` element in the document), and `rect` (four real coordinates separated by white space, in the order x1, y1, x2, y2, indicating two opposite corners of the image in Ipe coordinates), The optional `matrix` attribute can be used to transform the image into a non-rectangular shape.

It is also possible to embed a bitmap directly, without first creating a `<bitmap>` element. In that case, the `bitmap` attribute must be omitted, and instead the `<image>` element must carry all the attributes of the `<bitmap>` element, with the exception of `id`. The element contents is then the bitmap data, as described for `<bitmap>`.

### 14.3.4 The `<text>` element

The `<text>` element takes the required attributes `size` (the font size--either a symbolic name defined in a style sheet, or a real number) and `pos` (two real numbers separated by white space, defining the position of the text on the paper).

The required attribute `type`, with the possible values label, minipage, textbox, and title determines the type of object, and the attributes `width`, `height`, and `depth` give its dimensions. Note that these dimensions are recomputed by Ipe when running LaTeX, with the exception of `width` for minipage objects whose width is fixed. If the dimensions are missing, Ipe uses some default values until LaTeX has been run. (Obviously, `width` must not be missing for a minipage object.) If `type` is missing, the object is a minipage if `width` is present, otherwise a label.

The optional attributes `valign` (with values top (default for a minipage object), bottom (default for a label object), center, and baseline) and `halign` (with values left, right, and center, with left the default) determine the position of the reference point with respect to the text box.

The optional attribute `transformable` (possible values are yes and no, the latter is the default) determines whether the text object can be transformed, that is, stretched and rotated. Moving, of course, is always allowed.

The contents of the element must be a legal LaTeX fragment that can be interpreted by LaTeX inside `\hbox`, possibly using the macros or packages defined in the preamble.

### 14.3.5 The `<path>` element

The `<path>` element is the most complex element, and represents any filled and/or stroked PDF path, that is, any sequence of Postscript moveto/lineto/curveto/closepath operations, followed by a single fill/stroke operation. In particular, paths consisting of more than one closed loop are allowed, and so is any mix of straight segments and Bezier curves in the paths.

The `<path>` element takes the following optional attributes: `stroke`, `fill`, `dash`, `pen`, `cap`, `join`, `fillrule`, `matrix`, `arrow`, `backarrow`.

The value of `dash` is either the predefined name "solid", a symbolic name defined in a style sheet, or a dash pattern in PDF format, such as "[3 1] 0" for "three pixels on, one off, starting with the first pixel".

The value of `pen` is the line width, either symbolic (defined in a style sheet), or as a single real number.

The values of `cap`, `join` are the line cap and line join settings of PDF, as integers.

The value of the `fillrule` attribute selects one of two algorithms for determining whether a point lies inside a filled object. Possible values are `wind` and `eofill` (the latter is the default if the attribute is missing).

The value of the `<arrow>` and `<backarrow>` attributes is the size of an arrow, either a symbolic name defined in a style sheet, or a real number. If the attribute is missing, no arrow is drawn.

The contents of the `<path>` element describes a path using a series of "path construction operators" with arguments. This generalizes the PDF path construction syntax.

Each operator follows its arguments. The operators are

### 14.3.6 The `<group>` element

The `<group>` element allows to group objects together, so that they appear as one in the user interface. The contents of the element consists of a series of Ipe object elements.

The `<group>` element takes all the possible attributes of the `<path>` element (with the exception of the two arrow attributes), as well as `textsize`, `marksize`, and `markshape`.

If one of these attributes has been set, its value overrides the corresponding attribute of the elements inside the group. In other words, the attribute of an object is meaningful only if none of its parents in the tree structure formed by the grouped objects has this attribute set.

|  |  | 14.3 Ipe object elements