User:Regina/MYDrafts5

Custom Shapes Work in progress.

Tutorial: Create Own Custom Shapes

Getting started

This chapter gives you an overview about the work flow and tools by creating a simple shape step by step.

New Document

Start with a new Draw document and insert a rectangle. Make sure you use the rectangle form the “Basic Shapes”. Name the shape “MyShape” and save the document to e.g. “Start.odg”. Close the document but not Apache OpenOffice.

Not starting from scratch but with an existing custom shape has some advantages: You need not take care about the document itself, about embedding the shape into a page and a layer, or about any styles.

It is useful to name a shape. Such named shape is listed in the Navigator and you can select it from the Navigator.

Such odg-document is actual a zip-container. So you first need to unzip the file. I use the application “7-Zip” for this task, because it does not look at the filename-extension, but can unzip the odg-file directly. Other unpacker might need, that you change the filename-extension from “.odg” to “.zip”.

The ODF specification knows a flat, not packed format too. It has the filename-extension “.fodg”, but Apache OpenOffice cannot yet read oder write it.

You see some sub-folders and some files with filename-extension “.xml”. The file content.xml is the file we are going to edit. You do not know anything about XML? Do not worry, you will learn all you need here.

Examine the File content.xml

You can use each editor, which is able to write UTF-8 and UNIX line ends. I work on WinXP and prefer the application “XML Notepad 2007”, an editor, which handles nodes, so I do not need to write the tag syntax.

First we will have a look at the file without editing it, to find the place where the custom shape is located. I'll comment the other parts shortly, but you need not knew any details.

You see, that it is a usual xml-file. The first line contains the prolog <?xml version="1.0" encoding="utf-8"?>.

Tbd:Picture

The second line is very, very long. It contains a list of namespaces. Each element or attribute identifier is prefixed with a namespace to make it unique. For custom shapes only the prefixes draw: and svg: are relevant.

The text <office:scripts /> in the third line is the place where macros would go, when they were included in the document.

The next part is enclosed in <office:automatic-styles> ... </office:automatic-styles>. It contains the description of all direct, anonymous formatting, which you made using the toolbars. Your style definitions from the “Styles and Formatting"-window are in the file styles.xml. You will not need to use this parts, because you can style your shapes easily using the user interface of Apache OpenOffice.

Now we come nearer to the shape. You see the tags <office:body> and then <office:drawing> and then <draw:page ... >. And then the tag <draw:custom-shape ...>. On target!

Tbd:Picture

Understanding the Element custom-shape

In contrast to OOXML with its abbreviations, ODF is very verbose, so you will understand a lot of parts immediately.

The element custom-shape has some attributes and some sub-elements. The attributes describe the relation to the draw page. That is nothing specific, you will find it for all drawing objects.

Tbd:Picture

draw:style-name="gr1"  

A reference to the graphic style, which is used for this shape. In that style you will find things like line width and fill color.

draw:text-style-name="P1" 

A reference to the text style, which is used for the text of the shape. In that style you will find the used font for example.

draw:layer="layout" 

A draw page consists of several layers, the default one for shapes in Draw is the layer “layout”. Other layers are “background” or “controls”, and you can define additional layers in Draw.

draw:name="MyShape" 

Do you recognize it? That is the name you have given to the rectangle.

svg:width="6cm" svg:height="6cm" 

This gives the size of the shape.

svg:x="3cm" svg:y="2cm" 

And this is the position of the left, top corner of the shape.

The last four attributes correspond to the settings, which you can make in the “Position and Size” dialog of the shape. They define the rectangle with the green handles, which you see, when you click the shape. This information can be extended by an attribute svg:transform for rotation, shearing or any linear transformation matrix.

The ODF specification does not create an own definition for these attributes, but uses the already well defined attributes of the SVG specification of the W3 consortium. When possible, the ODF specification uses SVG specifications or at least follow them close.

Now we reach the part, which is specific to custom-shapes, it is the childelement draw:enhanced-geometry. Here we made our changes. The rectangle is a very simple shape, so you see only a few things.

Tbd:picture

svg:viewBox 

This defines a local coordinate system, it does not define the size of the shape. The latter had already been defined above. The first two values are the minimum x- and y-value. They correspond to the left/top position, the third and forth value are width and height but now in local coordinates. If you omit this attribute, Apache OpenOffice uses min-x/min-y value 0 | 0 and width/height value 21600 | 21600. You can use smaller values if you like, because the coordinates of the points can be floating-point numbers. The specification would allow negative values for min-x/min-y, but because of Issue 121453 the coordinate system has to always start in 0 0.

draw:type

It defines the kind of shape. Apache OpenOffice uses this to identify those shapes, which correspond to Microsoft custom shapes to do the right things when export a document into one of the formats of MSOffice. Shapes without such special treating shout get the default type non-primitive.

draw:enhanced-path 

It describes the line, which actually makes the shape. You can think of a custom shape as a rectangle canvas, on which lines are drawn. Such lines are called a “path”. The commands to define a path are based on the SVG path definitions, but they are not identical. Therefore the own namespace draw is used. One restriction is, that always absolute coordinates for points are used. Consequently all commands are upper case letters.

Most commands start drawing from the actual position after drawing the previous commands. Therefore the path often starts with the move command M. A straight line is drawn by the command L. And the command Z will close the path. For the full set of available commands see the section in the specification or the list below.

Editing the Element custom-shape

The first own shape will be a parabola. So change the value of attribute "draw:name" to "Parabola".

It will be a normal parabola y=x² with a x-range from -3 to 3, which results in a y-range from 0 to 9. So we need "svg:viewBox="0 0 6 9" and have to transform the mathematical coordinates to this local coordinate system.

A parabola can be drawn with a quadratic Béziercurve, which is command Q. But that kind of curve is not yet available in AOO3.4, but will be first implemented in the AOO4.0. Therefore I use a cubic Bézier curve here, which is command C. In general a cubic Bézier curve is defined by start point, two control points and an end point. For the desired parabola the mathematical coordinates would be start point(-3|9), first control point (-1|-3), second control point (1|3), and end point (3|9).

Tbd: two pictures, one mathematical, one local coordinates

We have to transform this mathematical points to the local coordinate system and get start point (0|0), first control (2|12), second control (4|12), and end point (6|0). Notice, that the control points are outside the range given by the attribute svg:viewBox, but that does not matter. Even the path itself may be outside.

The command for the cubic Bézier curve does not contain the start point, but uses the current position of the path as start point. Therefor we first need to move to point (0|0). Write M 0 0. The parameter for the command are separated be a space. The specification allows a comma too, but because of Issue 121507 it is not yet possible in AOO3.4. Then write C 2 12 4 12 6 0. Do not close the path, so do not write Z. That's all. Save the file. If you work directly on a fodg-file you have to close the file now.

Getting back to Apache OpenOffice

We need to go back and undo our unzip. Do not zip the folder, but mark the whole content and zip it. You likely get a file, which is inside the folder, but that does not matter now. You need to rename the file to .odg filename-extension. And you should use a filename, which gives you a hint, which shape you have designed in it. Name it Parabola.odg for example. If you leave the file extension .zip unchanged, you cannot open the file directly, but need to specify the import filter.

Go back to Apache OpenOffice and open the file. You hopefully see a nice parabola.

Make the Shape Available

But how make the new shape available for other documents? Use the Gallery! You can create an own theme, for example “Mathematics”. Click the shape, press the mouse button for about two seconds and then - still pressing down the mouse button - drag it into a theme.

If you want to distribute your shapes, then you can distribute your Gallery theme or you collect your new shapes in a document, from which the user can drag them in his own Gallery.

Working with the Shape

You can use your own shape the same way as the predefined ones. If you want it unfilled or with a thicker line, you can easily style it. Make the parabola wider or smaller, or rotate it. It will alway be a correct parabola with a smooth line.

Tbd: picture of use

Using Equations

This chapter shows you how to use equations. We will design an isosceles triangle ABC.

Planing the Shape

We use the mathematical coordinates A(0|0) and B(0|8) in the example, which gives edge length 8. You know the x-coordinate of the point C is 4, because of the symmetry of the shape. For the y-coordinate you need the height of the triangle. A formulary gives you . So for this special triangle it would be . But for to show you equations, the value will be calculated and not used as direct number.

Next step we decide how to place the triangle onto the rectangle given by svg:width and svg:height. The user can scale, rotate and shear this box and then the triangle will no longer be isosceles. But their should be one easy to get size, where the edges are really of same length. Using the height with the square root is not easy to reconstruct for the user. Therefore we use a square size and make the viewBox square too. To allow snapping of the triangle path to the grid either the top corner or the bottom edge has to be aligned to the edge of the box. We use the bottom edge here.

Considering all this we use svg:viewBox="0 0 8 8" and for the triangle the screen coordinates A(0|8), B(8|8) and C(4|8-h) with . The path will be very simple: Move to point A, draw line to point B, draw line to point C, close path.

Creating the Shape

Start with a new document as described in the chapter "Getting Started" and open the file content.xml in your editor.

Name the shape "isosceles triangle".

draw:name="isosceles triangle"

Make sure the size of the shape is square, for example 4cm.

svg:width="4cm" svg:height="4cm"

Set the viewBox to constrained axes.

svg:viewBox="0 0 8 8"

You cannot write any expression into a parameter in the path. So draw:enhanced-path="M 0 8 L 8 8 4 8-4*sqrt(3) Z" is not possible. A new element is needed, the element draw:equation.

Write the Equation

The element draw:equation has an attribute draw:name and an attribute draw:formula. It has no child element, so it is a single tag <draw:equation draw:name="..." draw:formula="..." />.

The name of the formula is used to reference the value. The specification allows an arbitrary string as name. But Apache OpenOffice converts it automatically to "f0", "f1", "f2" and so on. So it is easier for you to identify your formulas, if you use this names from the beginning.

The formula itself goes to the attribute formula. Besides the operators +, -, *, / you can use some functions (e.g. sqrt for the square root) and some special constants. You find these in chapter 19.171 draw:formula in the specification or see the tables below. So your new element looks like <draw:equation draw:name="f0" draw:formula="8-4*sqrt(3)" /> But where to put it?

The element draw:enhanced-geometry consists of a start tag <draw:enhanced-geometry ...> and an end tag </draw:enhanced-geometry>. The start tag can have a lot of attributes, which makes it a little bit confusing, if you use a simple editor. Move towards the end tag and place the new element before it.

Write the path

Now we edit the path. A reference to a formula is written with a ? character immediately followd by the name of the formula. Try to write the path and then compare.

You should have written <draw:enhanced-geometry draw:enhanced-path="M 0 8 L 8 8 4 ?f0 Z">.

Complete Custom Shape

All together your shape should look like this in a simple editor.

...

In XML Notepad it is

Tbd:picture

Save the file and zip the folder content. If you have used the same example as in the chapter "Getting Started", then you must be careful not to select the odg-file for zipping, which is likely still inside the folder.

Defining Cartesian Handles

Example parallelogram with vertical shearing.

Defining Polar Handles

Example right triangle with Thales circle

References

Eisenberg, J. David
Creating Custom Shapes.2005.
http://books.evc-cit.info/odbook/custom_shapes_article.odt [called 2013-01-04]

OpenDocument-v1.2-part1
Open Document Format for Office Applications (OpenDocument) Version 1.2
Part1: OpenDocument Schema. 29 September 2011. OASIS Standard.
http://docs.oasis-open.org/office/v1.2/os/OpenDocument-v1.2-os-part1.html.

W3C SVG Working Group
SVG 1.1 Second Edition Recommendation. 16 August 2011.
http://www.w3.org/TR/SVG/Overview.html