14.4 The Ipe style sheet format14 The Ipe file format14.2 The page element14.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, pin, 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 "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. (Note that the stroke color is not allowed to be "void".)

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.

The value of pin indicates whether the object is "pinned" on the page. The possible values are yes (object is fixed on the page), h (object is pinned horizontally, but can move in the vertical direction), and v (the opposite).

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), and the optional attribute fill for the fill color.

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 type (with the possible values label and minipage), 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 optional attributes width, height, and depth give the dimensions of the text object. 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.)

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. Minipage objects only use vertical alignment.

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 optional attribute style selects a LaTeX "style" to be used for formatting the text. It is only used for minipage objects, and must be a symbolic name defined in a style sheet. The standard style sheet defines the styles "default", "center", "itemize", and "item". If the attribute is not present, the "default" style is applied.

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 one of the predefined names "void" or "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 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.4 The Ipe style sheet format14 The Ipe file format14.2 The page element14.3 Ipe object elements