Difference between revisions of "User:Regina/MYDrafts5"

Revision as of 23:44, 3 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

Getting started

This chapter gives you an overview to the work flow and tools using a simple example.

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. 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"?>.

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!

Understanding the Element custom-shape

In contrast to OOXML with its abbreviations, the ODFformat 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.

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 for example the used font.

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 your 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 with transformation for rotation, shearing or with any linear transformation matrix.

For this four attributes the ODF specification does not create an own definition, 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.

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

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 coordinates which are assigned to the left/top position, the third and forth value are the above width/height in local coordinates. If you omit this attribute, Apache OpenOffice uses left/top position 0 0 and width/height of 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 left/top, but because of bug .... the coordinate system has to always start in 0 0.

draw:type 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 describes the line, which actually makes the shape. You can thing 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. 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 first be 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).

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 bug ... 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 see a nice parabola. If you want it unfilled or with thicker line, you can easily style it.

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.

Using Equations

Example isosceles triangle.

Defining Cartesian Handles

Example parallelogram with vertical shearing.

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