Ipe Manual -- 10.3 Ipe object elements

10.3 Ipe object elements

Common attributes

layer: (optional) Only allowed on "top-level" objects, that is, objects directly inside a <page> element. The value indicates into which layer the object goes. If the attribute 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.
matrix: (optional) 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.
pin: (optional) 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). The default is no pinning.
transformations: (optional) This attribute determines how objects can be deformed by transformations. Possible values are affine (the default), rigid, and translations.

Color attribute values

A color attribute value is 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.

Path construction operators

Graphical shapes in Ipe are described using a series of "path construction operators" with arguments. This generalizes the PDF path construction syntax.

Each operator follows its arguments. The operators are

m (moveto) (1 point argument): begin new subpath.
l (lineto) (1 point argument): add straight segment to subpath.
c (cubic B-spline) (n point arguments): add a uniform cubic B-spline with n+1 control points (the current position plus the n arguments). If n = 3, this is equivalent to a single cubic Bézier spline, if n = 2 it is equivalent to a single quadratic Bézier spline.
q (deprecated) (2 point arguments): identical to 'c'.
e (ellipse) (1 matrix argument): add a closed subpath consisting of an ellipse, the ellipse is the image of the unit circle under the transformation described by the matrix.
a (arcto) (1 matrix argument, 1 point argument): add an elliptic arc, on the ellipse describe by the matrix, from current position to given point.
s (deprecated) (n point arguments): add an "old style" uniform cubic B-spline as used by Ipe up to version 7.1.6.
C (n point arguments plus one tension argument): add a cardinal cubic spline through the given points and the given tension. (The definition of the tension in the literature varies. Ipe's tangent is the factor by which the vector from previous to next point is multiplied to obtain the tangent vector at this point. So 0.5 corresponds to the Catmull-Rom spline.)
L (n point arguments): add a clothoid spline as computed by the libspiro library by Raph Levien. When Ipe writes clothoid splines, it includes the control points of the computed Bezier approximation in the path description, separated from the defining points by a *.
u (closed spline) (n point arguments): add a closed subpath consisting of a closed uniform B-spline with n control points,
h (closepath) (no arguments): close the current subpath. No more segments can be added to this subpath, so the next operator (if there is one) must start a new subpath.

Paths consisting of more than one closed loop are allowed. A subpath can consist of any mix of straight segments, elliptic arcs, and B-splines.

10.3.1 The <group> element

The <group> element allows to group objects together, so that they appear as one in the user interface.

Attributes

clip: (optional) The value is a sequence of path construction operators, forming a clipping path for the objects inside the group.
url: (optional) The value is a link action (and the attribute name is somewhat of a misnomer, as actions do not need to be URLs—see the description of group objects).
decoration: (optional) The name of a decoration symbol. The default is normal, meaning no decoration.

The contents of the <group> element is a series of Ipe object elements.

10.3.2 The <image> element

Attributes

bitmap: (required) Value is an integer referring to a bitmap defined in a <bitmap> element in the document,
rect: (required) Four real coordinates separated by white space, in the order x₁, y₁, x₂, y₂, indicating two opposite corners of the image in Ipe coordinates).

The image element is normally empty. However, it is allowed to omit the bitmap attribute. In this case, the <image> 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>.

10.3.3 The <use> element

The <use> element refers to a symbol (an Ipe object) defined in the style sheet. The attributes stroke, fill, pen, and size make sense only when the symbol accepts these parameters.

Attributes

name: (required) The name of a symbol defined in a style sheet of the document.
pos: (optional) Position of the symbol on the page (two real numbers, separated by white space). This is the location of the origin of the symbol coordinate system. The default is the origin.
stroke: (optional) A stroke color (used whereever the symbol uses the symbolic color "sym-stroke"). The default is black.
fill: (optional) A fill color (used whereever the symbol uses the symbolic color "sym-fill"). The default is white.
pen: (optional) A line width (used whereever the symbol uses the symbolic value "sym-pen"). The default is "normal".
size: (optional) The size of the symbol, either a symbolic size (of type "symbol size"), or an absolute scaling factor. The default is 1.0.

The <use> element must be empty.

10.3.4 The <text> element

Attributes

stroke: (optional) The stroke color. If the attribute is missing, black will be used.
type: (optional) Possible values are label (the default) and minipage.
size: (optional) The font size—either a symbolic name defined in a style sheet, or a real number. The default is "normal".
pos: (required) Two real numbers separated by white space, defining the position of the text on the paper.
width: (required for minipage objects, optional for label objects) The width of the object in points.
height: (optional) The total height of the object in points.
depth: (optional) The depth of the object in points.
valign: (optional) Possible values are top (default for a minipage object), bottom (default for a label object), center, and baseline.
halign: (optional) Possible values are left, right, and center. left is the default. This determines the position of the reference point with respect to the text box.
style: (optional) Selects a LaTeX "style" to be used for formatting the text, and must be a symbolic name defined in a style sheet. There are separate definitions for minipages and for labels. For minipages, the standard style sheet defines the styles "normal", "center", "itemize", and "item". If the attribute is not present, the "normal" style is applied.
opacity: (optional) Opacity of the element. This must be a symbolic name. The default is "normal", meaning fully opaque.

The dimensions are recomputed by Ipe when running LaTeX, with the exception of width for minipage objects whose width is fixed.

The contents of the <text> 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.

10.3.5 The <path> element

Attributes

stroke: (optional) The stroke color. If the attribute is missing, the shape will not be stroked.
fill: (optional) The fill color. If the attribute is missing, the shape will not be filled.
dash: (optional) Either 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". If the attribute is missing, a solid line is drawn.
pen: (optional) The line width, either symbolic (defined in a style sheet), or as a single real number. The default value is "normal".
cap: (optional) The line cap setting of PDF as an integer. If the argument is missing, the setting from the style sheet is used.
join: (optional) The line join setting of PDF as an integer. If the argument is missing, the setting from the style sheet is used.
fillrule: (optional) Possible values are wind and eofill, selecting one of two algorithms for determining whether a point lies inside a filled object. If the argument is missing, the setting from the style sheet is used.
arrow: (optional) The value consists of a symbolic name, say "triangle" for an arrow type (a symbol with name "arrow/triangle(spx)"), followed by a slash and the size of the arrow. The size is either a symbolic name (of type "arrowsize") defined in a style sheet, or a real number. If the attribute is missing, no arrow is drawn.
rarrow: (optional) Same for an arrow in the reverse direction (at the beginning of the first subpath).
opacity: (optional) Opacity of the element. This must be a symbolic name. The default is "normal", meaning fully opaque.
tiling: (optional) A tiling pattern to be used to fill the element. The default is not to tile the element. If the element is not filled, then the tiling pattern is ignored.
gradient: (optional) A gradient pattern to be used to fill the element. If the element is not filled, then the gradient pattern is ignored. If gradient is set, then tiling is ignored.

The contents of the <path> element is a sequence of path construction operators. The entire shape will be stroked and/or filled with a single stroke and fill operation.