Custom Shapes in OpenOffice.

org
OneofthegreatfeaturesofOpenOffice.orgistheabilitytoinsertcomplexshapessuchascubes,stars,word
balloons,flowchartsymbols,andevensmileyfaces.

Theseshapescanhaveahandlewhichletsyouchangetheshapeofpartofthedrawing.Inthefollowing
figureofthewordballoon,theyellowdotisthehandle.

Becauseofthisinteractivity,mostofthecustomshapesarewiredintoOpenOffice.org.Ifyouknowhowthey
arerepresentedintheOpenDocumentXML,though,youcancreateyourownshapesforuseinyourdocuments.
Youcanteasilyaddthemtothedrawingtoolbar;thatwouldrequirerebuildingtheOpenOffice.orgapplication
fromsource.Youhavetotakethelongwayaroundinstead:
a) UnzipanexistingdrawingdocumentintoitsconstituentXMLfiles.
b) Editthecontent.xmlfiletoaddtheXMLforyourcustomshape.
c) Rezipthefilestocreateanewdrawingdocument.
d) Copyandpastethecustomshapesfromthenewdocumenttoyourotherdocuments.

A Simple Custom Shape

Acustomshapecanbeafixedsetoflines.Forourfirstshape,letsconstructasimplepictureofahouse:
Thiswillinvolveputtingthefollowingmarkupintothecontent.xmlfile:

<draw:custom-shape
draw:style-name="gr2" draw:text-style-name="P1"
draw:layer="layout"
svg:width="2.354cm" svg:height="2.249cm"
svg:x="1.00cm" svg:y="2.50cm">
<text:p/>
<draw:enhanced-geometry
svg:viewBox="0 0 1000 1000"
draw:text-areas="0 400 1000 1000"
draw:enhanced-path="M 0 400 L 0 1000 1000 1000 1000 400 Z N
M 0 400 L 500 0 1000 400 Z N"/>
</draw:custom-shape>
Example1:XMLforasimplecustomshape

CreatingCustomShapesPage1

Theopening<draw:custom-shape>elementhastheseattributes:
draw:style-name
Thegraphicstyleforthecustomshape.Intheminimalfile,thisspecifiesthattheareaistobefilledinwhite.
Anyattachedtextistobecenteredhorizontallyandvertically,andtheheightandwidthdonotgroworshrink
tomatchanyaddedtext.
draw:text-style-name
Thetextstyleforattachedtext;centeredtextwithnomarginorindent.
draw:layer="layout"
Thedrawinggoesinthemaindrawingarea(asopposedtocontrolsordimensionlines).
svg:xandsvg:y
Thelocationoftheupperleftcorneroftheobject.
svg:widthandsvg:height
Thewidthandheightoftheobjectsboundingbox,whichistherectangularareathatcompletelyencloses
theobject.
Thecontentofthe<draw:custom-shape>elementstartswiththeattachedtext;normallyacustomshape
youcreateshouldnothaveanytext,soputinanempty<text:p>element.
Thetextisfollowedbythemaineventthe<draw:enhanced-geometry>element,whichdescribeshowthe
customshapeistobedrawn.
svg:viewBox
Thisattributesetsthecoordinatesystemfortheobject.Itconsistsoffourintegersgivingtheorigin(xandy)
andwidthandheightofthecoordinatesystem.Youshouldalwayssetthexandyvaluestozero.
OpenOffice.orgsetsthewidthandheightto21600forcustomobjects.1Inthisexample,wearesettingthe
coordinatesystemto1000unitstomakethearithmeticeasier.
draw:text-areas
Thisattributegivestheleft,top,right,andbottomcoordinateswheretextisattachedtotheobject.These
coordinatesareintermsofthesystemestablishedbysvg:viewBox.Ifyouspecifyasecondtextarea,itis
usedforverticaltext.Inthiscase,wesetthetextareatothewallsofthehousesothattextdoesntappear
intheroofarea.
draw:extended-path
TheextendedpathisbasedonthepathattributeintheScalableVectorGraphics(SVG)specification.It
consistsofaseriesofcommandsandparametersthatdescribethelinesandcurvestobedrawing.An
extendedpathconsistsofoneormoresubpaths,consistingofamovetocommandfollowedbyoneormore
lineorcurvecommands.Herearethecommandsusedinthispath:

1 Thisgivesyouacoordinatesystemcorrespondingtoawidthandheightof15inchesintwips,wherethereare
1440twipsperinch.
CreatingCustomShapesPage2

Command

Meaning

Parameters

Movetoapoint

xandycoordinates

Line(seriesofconnectedlines)

pairsofxandycoordinates

Closesubpathbydrawingalinetothe
beginningpointofsubpath.

none

Endsubpath

none

You Try It!

Downloadtheexamplefilesthatcamewiththisarticle,downloadableathttp://books.evc
cit.info/odbook/custom_shapes_article.zip.Gointothecustom_shapes_odgdirectoryandinserttheXML
fromExample1intofilecontent.xmlattheplacewherethemarkupsays:
<!-- Your custom shapes go here -->
Nowzipthefilesinthefolder.OnLinux,youuseacommandlikethis:
zip -r ../test.odg *
The..makessurethattheresultingfileendsupinadirectoryotherthantheonethatholdtheunzippedfiles.
Openfiletest.odginOpenOffice.org.Ifyouvedoneeverythingcorrectly,youshouldseesomethinglikethis:

Handles and Modifiers

Theshapewejustmadealsolooksalotlikethosesignsyouseehanginginstorewindows:
Thisexamplewillputahandleonthetopofthestringthatletsyouadjustits
height.HereistheXMLforthe<draw:enhanced-geometry element>,withthe
newinformationinredandbold:
<draw:enhanced-geometry
svg:viewBox="0 0 1000 1000"
draw:text-areas="0 400 1000 1000"
draw:modifiers="0"
draw:enhanced-path="M 0 400 L 0 1000 1000 1000 1000 400 Z N
M 0 400 L 500 $0 1000 400 F Z N
U 500 $0 50 50 0 180 Z N">
<draw:handle draw:handle-position="500 $0"
draw:handle-range-y-minimum="0"
draw:handle-range-y-maximum="350"/>
</draw:enhanced-geometry>
Example2:Simpleshapewithhandle

CreatingCustomShapesPage3

Out to Lunch.

Thefirstchangeisthedraw:modifiersattribute.Itsvalueisawhitespaceseparatedlistoffloatingpoint
numbers.Amodifieractsverymuchlikeavariableinaprogramminglanguage.Thefirstentryinthelistof
numbersisreferredtoas$0,thesecondas$1,thethirdas$2,andsoon.
ThecommandM 0 400 L 500 $0 1000 400referstothatfirstvariable;insteadofalwaysdrawingthe
triangletothetopoftheshapearea,itdrawstowhatevervalueisin$0.(Whentheobjectfirstappears,that
valueiszero,soitdrawstothetop.)
Thesecondchangeisaminorone;byaddingtheFcommandbeforeclosingapath,theapplicationthat
displaystheobjectwillnotfillthepath.Thisleavesthetriangularareaunderthestringempty.
Finally,theenhancedpathusesanewcommand:U,whichdrawsacircleorellipse.Thefirsttwoparameters
afterthecommandarethexandycoordinatesofthecenterofthecircle/ellipse.Thenexttwoparametersare
thewidthandheightofthecircle/ellipse'saxes.(Inthiscase,theyareequal,soitdrawsacircle.)Thelasttwo
parametersarethestartingandendingangleindegrees.Noticethattheycoordinateofthecirclescenteris
drawnat$0,which,atthebeginning,iszero.
Thekeytointeractionisinthe<draw:handle>element.Thedraw:handle-positiongivestheinitialx
andycoordinatesofahandle.Becausethepositionusesmodifier$0,thislinksthehandlepositionwiththat
modifier.Asthehandleismoved,thevalueof$0willcontaintheycoordinateofthehandle.The
draw:handle-range-y-minimumanddraw:handle-range-y-maximumattributesdoexactlywhattheir
namessay:limittherangethroughwhichthehandlemaybemoved.Becausenoxrangeisspecified,thehandle
cannotmoveinthexdirectionatall.

Equations
Thenextexampleissomethingyoumightwanttocreateifyouwerewritingageometrybook.Thiscustomobject
isatrianglewhosetopvertexcanbedraggedbothhorizontallyandvertically.Asyoureshapethetriangle,aline
willalwaysconnectthelowerleftvertextothecenteroftheoppositeside.Alittlealgebratellsyouhowtodraw
thatline.Ifthetopvertex,leftbase,andrightbaseverticesareatcoordinates(x1,y1),(x2,y2),and(x3,y3),then
thelinegoesfrom(x2,y2)to((x1+x3)/2,(y1+y3)/2).Herestheenhancedgeometryforthisshape.

<draw:enhanced-geometry
svg:viewBox="0 0 1000 1000"
draw:modifiers="0 0"
draw:enhanced-path="M 0 1000 L $0 $1 1000 1000 Z N
M 0 1000 L ?f0 ?f1 F N">
<draw:equation draw:name="f0" draw:formula="($0 + right) / 2"/>
<draw:equation draw:name="f1" draw:formula="($1 + bottom) / 2"/>
<draw:equation draw:name="f2" draw:formula="2*(bottom - top) / 3"/>
<draw:handle draw:handle-position="$0 $1"
draw:handle-range-x-minimum="0"
draw:handle-range-x-maximum="right"
draw:handle-range-y-minimum="0"
draw:handle-range-y-maximum="?f2"/>
</draw:enhanced-geometry>
Example3:Shapeusingformulas

CreatingCustomShapesPage4

Inadditiontotheuseofmodifiers,($0and$1),theenhancedpathdrawsthelinefromcoordinate(0,1000)
to(?f0,?f1)withthecommandM 0 1000 L ?f0 ?f1. Theleadingquestionmarkindicatesthatthe
applicationshouldusetheresultofthe<draw:equation>withthecorrespondingdraw:nameattribute.Ifyou
lookatthefirst<draw:equation>element,youseethattheresultofequationf0isthesumofthecurrentx
coordinate,inmodifier$0,andstherightcoordinateofthecoordinatesystem2dividedbytwo.Theresultof
equationf1isthesumofthecurrentycordinate,inmodifier$1,andthetopoftheboundingbox,dividedby
two.Equationf2isusedintheattributedraw:handle-range-y-maximum="?f2"torestricttheymovement
ofthehandlesoitcangonofurtherthantwothirdsofthewaydowntheobjectarea.
Equationsmayuseallthetypicalarithmeticoperations:+,,*,and/.Equationsalsomayincludefunction
callstoabs,sqrt,sin,cos,tan,atan,atan2,max,andmin.Thelasttwoofthesefunctionsrequiretwo
arguments.Theresevenaniffunctionthattakesthreearguments.Ifthefirstargumentsvalueisgreaterthan
orequaltozero,thentheresultoftheifisthevalueofthesecondargument,otherwiseitisthevalueofthe
thirdargument.

A Complex Example
MostshopsthatputupanOuttoLunchsignalsohaveaclocktellingwhentheyllbeback.Thefollowing
customshapehastwohandlesthatletyousetthehourandminutehandofaclockface:
Heresaquickoverviewofthetrigonometryinvolvedtofindoutthecoordinatesfor
thehourhand,giventhatthecoordinatesystemis1000by1000units:

Getthexandydistancesbysubtracting500fromthehandlescoordinates
Theangleofthehourhandisthearctangentofy/x
Calculatethecosineandsineoftheangle
Drawalinefrom(500,500)to(500+lengthofhourhand*cosine,500+lengthof
hourhand*sine)

Thecalculationsfortheminutehanddifferonlyinthattheminutehandislongerthanthehourhand.Heres
theXMLItstartswiththeoutercircle,thesmallcircleinthecenteroftheclock,andthen12tickmarksaround
theinnerfaceoftheclock.3Thelastpartofthepathdrawsthehourhandandminutehand.
<draw:enhanced-geometry
svg:viewBox="0 0 1000 1000"
draw:text-areas="0 0 1000 1000"
draw:modifiers="500 150 500 50"
draw:enhanced-path="U 500 500 500 500 0 360 Z N
U 500 500 20 20 0 360 F N
M 1000 500 L 970 500 N M 933 750 L 907 735 N
M 750 933 L 735 907 N M 500 1000 L 500 970 N
M 250 933 L 265 907 N M 66 750 L 92 735 N
M 0 500 L 30 500 N M 66 249 L 92 264 N
M 249 66 L 264 92 N M 499 0 L 499 30 N
M 750 66 L 735 92 N M 933 249 L 907 264 N
M 500 500 L ?hourX ?hourY N M 500 500 L ?minuteX ?minuteY N">
Example4:CustomShapeClockPath

2 OpenDocumentletsyouusethereservedwordsright,left,bottom,andtop,whichstandforthe
cornersofthecoordinatesystem.Thatway,youdonthavetorememberandcopycoordinatenumbers.
3 IusedaPerlprogramtogeneratethecoordinatesratherthantryingtoguessthemorfigurethemoutbyhand.
CreatingCustomShapesPage5

Theequationsfollow,asdescribedintheprecedingpseudocode,finishingupwiththehandle
specifications.Therangesforthehourandminutehandensurethatthehourhandshandlecannotbeexteded
outasfarastheminutehands,sotheydonthavetooverlap.
<!-- calculations for hour hand -->
<draw:equation draw:name="cosHour"
draw:formula="cos(atan2($1-500,$0-500))"/>
<draw:equation draw:name="sinHour"
draw:formula="sin(atan2($1-500,$0-500))"/>
<draw:equation draw:name="hourX"
draw:formula="500 + 350 * ?cosHour"/>
<draw:equation draw:name="hourY"
draw:formula="500 + 350 * ?sinHour"/>
<!-- calculations for minute hand -->
<draw:equation draw:name="cosMinute"
draw:formula="cos(atan2($3-500,$2-500))"/>
<draw:equation draw:name="sinMinute"
draw:formula="sin(atan2($3-500,$2-500))"/>
<draw:equation draw:name="minuteX"
draw:formula="500 + 450 * ?cosMinute"/>
<draw:equation draw:name="minuteY"
draw:formula="500 + 450 * ?sinMinute"/>
<!-- handle for hour hand -->
<draw:handle draw:handle-position="$0 $1"
draw:handle-range-x-minimum="150"
draw:handle-range-x-maximum="850"
draw:handle-range-y-minimum="150"
draw:handle-range-y-maximum="850"/>
<!-- handle for minute hand -->
<draw:handle draw:handle-position="$2 $3"
draw:handle-range-x-minimum="50"
draw:handle-range-x-maximum="950"
draw:handle-range-y-minimum="50"
draw:handle-range-y-maximum="950"/>
</draw:enhanced-geometry>
Example5:Customshapeclock:EquationsandHandles

Further Information
Thisarticlehasgivenyouthebasicinformationthatyouneedtostartcreatingandusingyourowncustom
shapes.Therearemanyotherpathcommandsthatletyoudrawarcs,cubicandquadraticBziercurves,and
quarterellipses.Forafulllist,seetheOpenDocumentspecificationathttp://www.oasis
open.org/committees/documents.php?wg_abbrev=office.

Thisarticleis2005byJ.DavidEisenberg.ThecontentiscurrentlylicensedunderaCreativeCommonsLicense

CreatingCustomShapesPage6