Difference between revisions of "Create a New Custom Shape in Source in File"

From Apache OpenOffice Wiki
Jump to: navigation, search
(Using Cygwin)
m (Understanding the Element custom-shape: add link to specification)
Line 75: Line 75:
 
;<tt>draw:enhanced-path</tt> :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 <tt>draw</tt> is used. One restriction is, that always absolute coordinates for points are used. Consequently all commands are upper case letters.
 
;<tt>draw:enhanced-path</tt> :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 <tt>draw</tt> 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.
+
: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 [http://docs.oasis-open.org/office/v1.2/os/OpenDocument-v1.2-os-part1.html#__RefHeading__1417000_253892949 section 19.145] in the specification or the list below.
  
 
==== Editing the Element <tt>custom-shape</tt> ====
 
==== Editing the Element <tt>custom-shape</tt> ====

Revision as of 07:02, 10 May 2013

Template:Documentation/DraftPage Template:Documentation/HelpNeeded

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. The tutorial is at the same time an introduction to the ODF specification of 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

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.

A 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. It is useful to know a little bit about a markup languages like XML or HTML, but such knowledge is no precondition.

Examine the File content.xml

You can use each editor, which is able to write UTF-8 encoding. I work on Windows 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. Custom shapes use in most cases the prefixes draw: and svg:.

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 these 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. But when you will share your files with users of PowerPoint you should stick with 21600 | 21600, because PowerPoint can only use integer values in its current versions. The ODF 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 track those shapes, which correspond to Microsoft custom shapes and to the predefined shapes in OOXML. So it does 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 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 parameters for a 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

Unzip-Zip-Workflow for ODF Documents

Although an .odg document is actually a zip-container, it has a special feature. The file mimetype (It has no filename-extension!) is not compressed and it needs to be the first file in the container. Your work-flow has to consider this.

Using Features of Windows 7

  1. Rename the .odg file to .zip. Ignore the warning.
  2. Double click the zip-container. Windows 7 treats a zip-container nearly as a folder and you will see a treeview of the container content.
  3. Grab the file "content.xml" and drag it outside the container. Hold down the shift-key to move the file. Do not close the treeview of the container.
  4. Open the file "content.xml" (or another one you will work on) in your favorite editor, make all the changes you want, save the file and then close it.
  5. Grab the file and drag it back into the container.
  6. Go one level up in the tree-view and rename the file back from .zip to the original .odg filename extension.
  7. Open the file in Apache OpenOffice and check your changes.

This work-flow leaves the file 'mimetype' untouched, but you need to rename the .odg file.

Using the Packer 7-Zip on Windows 7

  1. Right click the .odg file and open it with 7-Zip.
  2. Right click the file content.xml and open it "external", or double click the file. This will open it with the application, that is bound to the filename extension .xml. Or configure 7-Zip to use your favorite editor (only first time), and right click the file and choose item "edit".
  3. Make all your changes, save the file and close it. 7-Zip will notice, that the file is changed and ask you to update it. Agree.
  4. Close 7-Zip.
  5. Open the file in Apache OpenOffice, check your changes and save the file.

7-Zip will keep the file 'mimetype' uncompressed. But unfortunately 7-Zip will reorder the files alphabetically. Therefore the file 'mimetype' is no longer the first one in the package. Saving the file with Apache OpenOffice will repair this, but might alter your changes too. Nevertheless this work-flow is very quick, when you do not want to alter the content, but only examine it.

If you ever need to repair the .odg file using 7-Zip, you can do it this way:

  1. Unpack the .odg file to e.g. C:\Temp\
  2. Start command window.
  3. Add 7-Zip temporarily to your path by e.g. set path=%path%;C:\Program Files\7-Zip\
  4. Change to directory C:\Temp\
  5. Call the command line version of 7-Zip by 7z a -mx=0 dummy.zip mimetype (a means add, -mx=0 means without compressing).
  6. Close command window. This will set back your path settings.
  7. Use the Windows filemanager and drag the remaining files into the new dummy.zip container. You cannot do this with the file 'mimetype', because Windows will compress it automatically, when you drag it into a zip-container.
  8. Rename the file dummy.zip to the correct file name having .odg file name extension.
  9. Move the file to the desired place.

Using Cygwin

This proposal will likely work similar on Linux, but I have not tested it. (proposed by Ariel Constenla-Haile, sited from mailinglist openoffice-dev http://mail-archives.apache.org/mod_mbox/openoffice-dev/201303.mbox/%3C20130328122918.GA598%40localhost%3E ) All of the following should be available in your cygwin:

only take the content.xml out of the ODF file:

 ]$ unzip demo.odg content.xml
 Archive:  demo.odg
 inflating: content.xml 

indent it, to make it more readable:

 ]$ xmlindent -w content.xml

edit it (vim has syntax highlighting):

 ]$ vim content.xml

put the modified content.xml back:

 ]$ zip demo.odg content.xml
 updating: content.xml
 (deflated 84%)

If you get a warning like this:

       zip warning: Local Entry CRC does not match CD: content.xml

It's just a warning, the file can be opened safely (nevertheless, best back up it before playing with all this) vid. http://softsolder.com/2010/07/25/

Features in Detail

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 got:

<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:modifiers="3"
    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:modifiers="3"
    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

Tbd. Example right triangle with Thales circle

Setting Gluepoints

Tbd. Setting glue points to the Thales circle

Simple Text

Tbd. Example arc with text.

FontWork

Tbd. Introduce fontwork attributes.

Extruding

Tbd. Extrude with UI and show resulting elements and attributes

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

Personal tools