oox/README

Support for Office Open XML, the office XML-format designed by Microsoft.

See also:
[http://wiki.openoffice.org/wiki/OOX]

== DrawingML Custom shapes and presets ==

custom shapes are part of DrawingML and are different to binary ppt
and VML in older formats, so we needed to add new code to work with
these. the import happens in oox/source/drawingml, where they are
imported as LO's enhanced custom shape's. see
offapi/com/sun/star/drawing/CustomShape.idl and
offapi/com/sun/star/drawing/EnhancedCustomShape*.idl

the export is quite behind now, as it was done before we started work
on fully supporting drawingml custom shapes. (see FUTURE WORK below)

example of drawingml preset:

         <a:prstGeom prst="star5">
           <a:avLst/>
         </a:prstGeom>

example of drawingml custom shape (equal to star5 preset):

   <avLst xmlns="http://schemas.openxmlformats.org/drawingml/2006/main">
     <gd name="adj" fmla="val 19098" />
     <gd name="hf" fmla="val 105146" />
     <gd name="vf" fmla="val 110557" />
   </avLst>
   <gdLst xmlns="http://schemas.openxmlformats.org/drawingml/2006/main">
     <gd name="a" fmla="pin 0 adj 50000" />
     <gd name="swd2" fmla="*/ wd2 hf 100000" />
     <gd name="shd2" fmla="*/ hd2 vf 100000" />
     <gd name="svc" fmla="*/ vc  vf 100000" />
     <gd name="dx1" fmla="cos swd2 1080000" />
     <gd name="dx2" fmla="cos swd2 18360000" />
     <gd name="dy1" fmla="sin shd2 1080000" />
     <gd name="dy2" fmla="sin shd2 18360000" />
     <gd name="x1" fmla="+- hc 0 dx1" />
     <gd name="x2" fmla="+- hc 0 dx2" />
     <gd name="x3" fmla="+- hc dx2 0" />
     <gd name="x4" fmla="+- hc dx1 0" />
     <gd name="y1" fmla="+- svc 0 dy1" />
     <gd name="y2" fmla="+- svc 0 dy2" />
     <gd name="iwd2" fmla="*/ swd2 a 50000" />
     <gd name="ihd2" fmla="*/ shd2 a 50000" />
     <gd name="sdx1" fmla="cos iwd2 20520000" />
     <gd name="sdx2" fmla="cos iwd2 3240000" />
     <gd name="sdy1" fmla="sin ihd2 3240000" />
     <gd name="sdy2" fmla="sin ihd2 20520000" />
     <gd name="sx1" fmla="+- hc 0 sdx1" />
     <gd name="sx2" fmla="+- hc 0 sdx2" />
     <gd name="sx3" fmla="+- hc sdx2 0" />
     <gd name="sx4" fmla="+- hc sdx1 0" />
     <gd name="sy1" fmla="+- svc 0 sdy1" />
     <gd name="sy2" fmla="+- svc 0 sdy2" />
     <gd name="sy3" fmla="+- svc ihd2 0" />
     <gd name="yAdj" fmla="+- svc 0 ihd2" />
   </gdLst>
   <ahLst xmlns="http://schemas.openxmlformats.org/drawingml/2006/main">
     <ahXY gdRefY="adj" minY="0" maxY="50000">
       <pos x="hc" y="yAdj" />
     </ahXY>
   </ahLst>
   <cxnLst xmlns="http://schemas.openxmlformats.org/drawingml/2006/main">
     <cxn ang="3cd4">
       <pos x="hc" y="t" />
     </cxn>
     <cxn ang="cd2">
       <pos x="x1" y="y1" />
     </cxn>
     <cxn ang="cd4">
       <pos x="x2" y="y2" />
     </cxn>
     <cxn ang="cd4">
       <pos x="x3" y="y2" />
     </cxn>
     <cxn ang="0">
       <pos x="x4" y="y1" />
     </cxn>
   </cxnLst>
   <rect l="sx1" t="sy1" r="sx4" b="sy3" xmlns="http://schemas.openxmlformats.org/drawingml/2006/main" />
   <pathLst xmlns="http://schemas.openxmlformats.org/drawingml/2006/main">
     <path>
       <moveTo>
         <pt x="x1" y="y1" />
       </moveTo>
       <lnTo>
         <pt x="sx2" y="sy1" />
       </lnTo>
       <lnTo>
         <pt x="hc" y="t" />
       </lnTo>
       <lnTo>
         <pt x="sx3" y="sy1" />
       </lnTo>
       <lnTo>
         <pt x="x4" y="y1" />
       </lnTo>
       <lnTo>
         <pt x="sx4" y="sy2" />
       </lnTo>
       <lnTo>
         <pt x="x3" y="y2" />
       </lnTo>
       <lnTo>
         <pt x="hc" y="sy3" />
       </lnTo>
       <lnTo>
         <pt x="x2" y="y2" />
       </lnTo>
       <lnTo>
         <pt x="sx1" y="sy2" />
       </lnTo>
       <close />
     </path>
   </pathLst>

we needed to extend our custom shapes for missing features and so 5
new segment commands were added. G command for arcto drawingml record
and H I J K commands for darken, darkenless, lighten, lightenless
records. the commands are save into ODF in special namespace drawooo,
which is extension not yet in the standard. Thorsten suggested to put
it in such a namespace and keep original (incomplete) geometry for
backward compatibility, before we can extend the ODF. that's why you
will see 2 of them in cases where some of the new commands was
needed. Radek backported code for the new commands to 3-6
and 4-0 branches.

the drawingml also contains new presets (compared to binary/VML) and
so we now have code with these presets - they are basically
predefined custom shapes. we generate them using scripts in
oox/source/drawingml/customshapes/ and the output are
oox/source/drawingml/customshapepresets[123456].cxx source files
containing the definition for the preset shapes. this mean that we
import presets from OOXML files perfectly. one area to look at might
be check how handles on the imported custom shapes (and presets)
work.

the source code generation happens in these steps:

  * generate pptx files by running generatePresetsPPTXs.pl. it
    generates files in pptx/ from cshape.pptx sample - replacing
    slide1.xml in it and placing it in new file in pptx/ named after
    the preset plus one cshape-all.pptx file all the presets

  * build oox module with debug (ie. make -s debug=t dbglevel=2)

  * import cshape-all.pptx into impress and redirect output to
    custom-shapes.log

  * generate oox-drawingml-cs-presets data file by running
    generatePresetsData.pl - it uses debug output from the custom-shapes.log
    file

  * check generated data file oox-drawingml-cs-presets and move them to
    oox/source/drawingml/

  * build oox with new source files and test

while importing presets, we also set the name of the custom shape so
that we can detect it on export as save it again as preset.

the scripts in oox/source/drawingml/customshapes/ also generate pptx
files for signle presets and also for all presets
cshape-all.pptx. the cshape-all.pptx file is then loaded into impress
build with debug enabled in oox and the command line output contains
information, which are used by generatePresetsCXX.pl. redirect the
output into custom-shapes.log in oox/source/drawingml/customshapes/
and run the script. it creates the customshapepresets[123456].cxx
source files with presets definitions. also the generated pptx files
can be used when debugging bugs in custom shapes import/export. also
the cshape-all.pptx can be used to test the round trips. there's small
problem with these pptx as they cannot be imported into powerpoint,
but that can be fixed quickly. when fixed, we can use it to
test powerpoint odp export and see how complete it is regarding
custom shapes. OpenXML SDK tools might help when fixing
cshape-all.pptx
http://www.microsoft.com/en-us/download/details.aspx?id=30425

FUTURE WORK: because we have to make sure that all the roundtrips
like PPTX --> ODP --> PPTX work correctly and doesn't lose data.
the only problematic part is probably saving custom shapes (ie. not
presets) to PPTX. that part of code predates work on custom shapes
and is unable to export general custom shapes yet. it will need a bit
of work as LO has more complex equations than DrawingML. other parts
should work OK, PPTX --> ODP should work and don't lose any
data. presets should already survive PPTX --> ODP --> PPTX roundtrip