Difference between revisions of "User:Regina/MYDrafts5"

Latest revision as of 17:52, 28 January 2013

Custom Shapes Work in progress.

How to Use Custom Shapes

What is a 'Custom Shape'

Handles

Extrusion

FontWork

Tutorial: Create Own Custom Shapes

This tutorial addresses developers and advanced users. It shows how to generate a new custom shape. For this aim the source text of the file is edited directly.

Getting started

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

New Document

In this tutorial we edit a file directly, no macro is used. Apache OpenOffice has a setting to optimize the file size. That is done by removing all not necessary blanks and line ends. So the whole content is one large line. That is very bad, when you will edit such file. Some editors might not even open the file because the line is too long. Therefore go to menu “Tools”, item “Options…”, and then section “Load/Save”. Disable the option “Size optimization for ODF format”.

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

<text:p /> 

Here you will see text, which you have entered in the shape. The rectangle has not got any text, therefore the element is empty.

<draw:enhanced-geometry ... /> 

This is the distinctive part, it is specific to custom-shapes. Here we made our changes. The rectangle is a very simple shape, so the element has only some attributes but no sub-elements.

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 to them. 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 19.145 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

Defining Cartesian Handles

In the next example a triangle with a vertical edge on the left side is made. The opposite corner will be movable up and down using a handle. The triangle is placed on a 10 × 10 canvas.

Tbd: Insert picture triangle.png

We start with a version that has the fixed corners in (0|0), (10|6) and (0|10). That is done nearly similar to the rectangle in section "Getting started". Try it yourself. You should have get:

<draw:enhanced-geometry
        svg:viewBox="0 0 10 10"
        draw:type="non-primitive"
        draw:enhanced-path="M 0 0 L 10 6 0 10 Z"
    />

Why use the Z command and not a line to point (0|0)? Using a L command would not close the path to a polygon, but it would be a polyline with four points, which start and end points are accidentally at the same position. The command Z makes it a polygon with three points.

A handle is a little yellow circle. You can drag it with the mouse and move it. Its coordinates are variable. Therefore the shape needs something to hold varying values. This is done in an attribute draw:modifiers of the element draw:enhanced-geometry. It is a list of values. You write it with an initial value, but that will later on change, when you move the handle.

<draw:enhanced-geometry ... draw:modifiers="6"  />

The handle itself is made by an element draw:handle, a sub-element of the element draw:enhanced-geometry. This has an attribute draw:handle-position with a pair of values. The first is the x-coordinate, the second the y-coordinate. The x-coordinate is 10, the y-coordinate gets a reference to the modifier. Such reference is written with the character $ followed by the position of the value in the list. Counting starts on 0. When you move the handle, the actual value is written to the modifier and when you change the modifier the handle will follow. So the text is now:

<draw:enhanced-geometry     
     ...
     draw:modifiers="6"
     draw:enhanced-path="M 0 0 L 10 6 0 10 Z" >
     <draw:handle draw:handle-position="10 $0"  />
</draw:enhanced-geometry>

Notice, that the element draw:handle has no content and therefore a combined start-end tag is used. And the element draw:enhanced-geometry now has a sub-element and therefore a separate end tag is needed.

You should look at it in AOO. When you zip it, make sure that you only mark those files originally belonging to the document. Previous odg-files or backup files from your editor must not be included in the zip-archive.

You should get a triangle and a handle. You can move the handle up and down, but the corner of the triangle will not yet follow the movement. The y-coordinate of the corner needs to use the modifier value too. That is done with a reference to the modifier. The syntax is the same as in the handle-position.

Go back to your editor and change the attribute draw:enhanced-path to

draw:enhanced-path="M 0 0 L 10 $0 0 10 Z"

So you have got finally

<draw:enhanced-geometry
     svg:viewBox="0 0 10 10"
     draw:type="non-primitive"
     draw:modifiers="6"      
     draw:enhanced-path="M 0 0 L 10 $0 0 10 Z" >
     <draw:handle draw:handle-position="10 $0"  />
</draw:enhanced-geometry>

Save, zip and tryout your shape.

Using Equations

This chapter shows you how to use equations by creating a parallelogram.

The example parallelogram has a fixed edge on the left side and the opposite edge will be movable up and down. The coordinate system is again set to size 10 × 10.

Tbd: picture

This is not very different from the triangle above, so try it yourself.

You have likely written

<draw:enhanced-geometry
        svg:viewBox="0 0 10 10"
        draw:type="non-primitive"
        draw:enhanced-path="M 0 0 L 10 $0 10 $0+10 0 10 Z">
        <draw:handle draw:handle-position="10 $0"  />
    </draw:enhanced-geometry>

and find, that it does not work. That is because of the part $0+10 in the path. It is not possible to use an expression in a parameter of a command. A further element is needed, the element draw:equation.

The element draw:equation is a sub-element of the element draw:enhanced-geometry. It has an attribute draw:name and an attribute draw:formula. It has no child element, so it is a combined start-end 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 these names from the beginning.

The expression 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 (e.g. pi). 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="$0+10" />.

A reference is then used instead of the expression in the path. Such reference to a formula is written with a ? character immediately followed by the name of the equation. The path becomes draw:enhanced-path="M 0 0 L 10 $0 10 ?f0 0 10 Z".

All together you get the enhanced-geometry

<draw:enhanced-geometry
        svg:viewBox="0 0 10 10"
        draw:type="non-primitive"
        draw:enhanced-path="M 0 0 L 10 $0 10 ?f0 0 10 Z">
        <draw:equation draw:name="f0" draw:formula="$0+10" />
        <draw:handle draw:handle-position="10 $0" />
    </draw:enhanced-geometry>

Defining Polar Handles

Example right triangle with Thales circle

Setting Gluepoints

Simple Text

FontWork

Extruding

API for Custom Shapes

Custom Shapes in Core

Relation to OOXML

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