oox/README

   1 Support for Office Open XML, the office XML-format designed by Microsoft.
   2
   3 See also:
   4 [http://wiki.openoffice.org/wiki/OOX]
   5
   6 == DrawingML Custom shapes and presets ==
   7
   8 custom shapes are part of DrawingML and are different to binary ppt
   9 and VML in older formats, so we needed to add new code to work with
  10 these. the import happens in oox/source/drawingml, where they are
  11 imported as LO's enhanced custom shape's. see
  12 offapi/com/sun/star/drawing/CustomShape.idl and
  13 offapi/com/sun/star/drawing/EnhancedCustomShape*.idl
  14
  15 the export is quite behind now, as it was done before we started work
  16 on fully supporting drawingml custom shapes. (see FUTURE WORK below)
  17
  18 example of drawingml preset:
  19
  20          <a:prstGeom prst="star5">
  21            <a:avLst/>
  22          </a:prstGeom>
  23
  24 example of drawingml custom shape (equal to star5 preset):
  25
  26    <avLst xmlns="http://schemas.openxmlformats.org/drawingml/2006/main">
  27      <gd name="adj" fmla="val 19098" />
  28      <gd name="hf" fmla="val 105146" />
  29      <gd name="vf" fmla="val 110557" />
  30    </avLst>
  31    <gdLst xmlns="http://schemas.openxmlformats.org/drawingml/2006/main">
  32      <gd name="a" fmla="pin 0 adj 50000" />
  33      <gd name="swd2" fmla="*/ wd2 hf 100000" />
  34      <gd name="shd2" fmla="*/ hd2 vf 100000" />
  35      <gd name="svc" fmla="*/ vc  vf 100000" />
  36      <gd name="dx1" fmla="cos swd2 1080000" />
  37      <gd name="dx2" fmla="cos swd2 18360000" />
  38      <gd name="dy1" fmla="sin shd2 1080000" />
  39      <gd name="dy2" fmla="sin shd2 18360000" />
  40      <gd name="x1" fmla="+- hc 0 dx1" />
  41      <gd name="x2" fmla="+- hc 0 dx2" />
  42      <gd name="x3" fmla="+- hc dx2 0" />
  43      <gd name="x4" fmla="+- hc dx1 0" />
  44      <gd name="y1" fmla="+- svc 0 dy1" />
  45      <gd name="y2" fmla="+- svc 0 dy2" />
  46      <gd name="iwd2" fmla="*/ swd2 a 50000" />
  47      <gd name="ihd2" fmla="*/ shd2 a 50000" />
  48      <gd name="sdx1" fmla="cos iwd2 20520000" />
  49      <gd name="sdx2" fmla="cos iwd2 3240000" />
  50      <gd name="sdy1" fmla="sin ihd2 3240000" />
  51      <gd name="sdy2" fmla="sin ihd2 20520000" />
  52      <gd name="sx1" fmla="+- hc 0 sdx1" />
  53      <gd name="sx2" fmla="+- hc 0 sdx2" />
  54      <gd name="sx3" fmla="+- hc sdx2 0" />
  55      <gd name="sx4" fmla="+- hc sdx1 0" />
  56      <gd name="sy1" fmla="+- svc 0 sdy1" />
  57      <gd name="sy2" fmla="+- svc 0 sdy2" />
  58      <gd name="sy3" fmla="+- svc ihd2 0" />
  59      <gd name="yAdj" fmla="+- svc 0 ihd2" />
  60    </gdLst>
  61    <ahLst xmlns="http://schemas.openxmlformats.org/drawingml/2006/main">
  62      <ahXY gdRefY="adj" minY="0" maxY="50000">
  63        <pos x="hc" y="yAdj" />
  64      </ahXY>
  65    </ahLst>
  66    <cxnLst xmlns="http://schemas.openxmlformats.org/drawingml/2006/main">
  67      <cxn ang="3cd4">
  68        <pos x="hc" y="t" />
  69      </cxn>
  70      <cxn ang="cd2">
  71        <pos x="x1" y="y1" />
  72      </cxn>
  73      <cxn ang="cd4">
  74        <pos x="x2" y="y2" />
  75      </cxn>
  76      <cxn ang="cd4">
  77        <pos x="x3" y="y2" />
  78      </cxn>
  79      <cxn ang="0">
  80        <pos x="x4" y="y1" />
  81      </cxn>
  82    </cxnLst>
  83    <rect l="sx1" t="sy1" r="sx4" b="sy3" xmlns="http://schemas.openxmlformats.org/drawingml/2006/main" />
  84    <pathLst xmlns="http://schemas.openxmlformats.org/drawingml/2006/main">
  85      <path>
  86        <moveTo>
  87          <pt x="x1" y="y1" />
  88        </moveTo>
  89        <lnTo>
  90          <pt x="sx2" y="sy1" />
  91        </lnTo>
  92        <lnTo>
  93          <pt x="hc" y="t" />
  94        </lnTo>
  95        <lnTo>
  96          <pt x="sx3" y="sy1" />
  97        </lnTo>
  98        <lnTo>
  99          <pt x="x4" y="y1" />
 100        </lnTo>
 101        <lnTo>
 102          <pt x="sx4" y="sy2" />
 103        </lnTo>
 104        <lnTo>
 105          <pt x="x3" y="y2" />
 106        </lnTo>
 107        <lnTo>
 108          <pt x="hc" y="sy3" />
 109        </lnTo>
 110        <lnTo>
 111          <pt x="x2" y="y2" />
 112        </lnTo>
 113        <lnTo>
 114          <pt x="sx1" y="sy2" />
 115        </lnTo>
 116        <close />
 117      </path>
 118    </pathLst>
 119
 120 we needed to extend our custom shapes for missing features and so 5
 121 new segment commands were added. G command for arcto drawingml record
 122 and H I J K commands for darken, darkenless, lighten, lightenless
 123 records. the commands are save into ODF in special namespace drawooo,
 124 which is extension not yet in the standard. Thorsten suggested to put
 125 it in such a namespace and keep original (incomplete) geometry for
 126 backward compatibility, before we can extend the ODF. that's why you
 127 will see 2 of them in cases where some of the new commands was
 128 needed. Radek backported code for the new commands to 3-6
 129 and 4-0 branches.
 130
 131 the drawingml also contains new presets (compared to binary/VML) and
 132 so we now have code with these presets - they are basically
 133 predefined custom shapes. we generate them using scripts in
 134 oox/source/drawingml/customshapes/ and the output are
 135 oox/source/drawingml/customshapepresets[123456].cxx source files
 136 containing the definition for the preset shapes. this mean that we
 137 import presets from OOXML files perfectly. one area to look at might
 138 be check how handles on the imported custom shapes (and presets)
 139 work.
 140
 141 the source code generation happens in these steps:
 142
 143   * generate pptx files by running generatePresetsPPTXs.pl. it
 144     generates files in pptx/ from cshape.pptx sample - replacing
 145     slide1.xml in it and placing it in new file in pptx/ named after
 146     the preset plus one cshape-all.pptx file all the presets
 147
 148   * build oox module with debug (ie. make -s debug=t dbglevel=2)
 149
 150   * import cshape-all.pptx into impress and redirect output to
 151     custom-shapes.log
 152
 153   * generate oox-drawingml-cs-presets data file by running
 154     generatePresetsData.pl - it uses debug output from the custom-shapes.log
 155     file
 156
 157   * check generated data file oox-drawingml-cs-presets and move them to
 158     oox/source/drawingml/
 159
 160   * build oox with new source files and test
 161
 162 while importing presets, we also set the name of the custom shape so
 163 that we can detect it on export as save it again as preset.
 164
 165 the scripts in oox/source/drawingml/customshapes/ also generate pptx
 166 files for signle presets and also for all presets
 167 cshape-all.pptx. the cshape-all.pptx file is then loaded into impress
 168 build with debug enabled in oox and the command line output contains
 169 information, which are used by generatePresetsCXX.pl. redirect the
 170 output into custom-shapes.log in oox/source/drawingml/customshapes/
 171 and run the script. it creates the customshapepresets[123456].cxx
 172 source files with presets definitions. also the generated pptx files
 173 can be used when debugging bugs in custom shapes import/export. also
 174 the cshape-all.pptx can be used to test the round trips. there's small
 175 problem with these pptx as they cannot be imported into powerpoint,
 176 but that can be fixed quickly. when fixed, we can use it to
 177 test powerpoint odp export and see how complete it is regarding
 178 custom shapes. OpenXML SDK tools might help when fixing
 179 cshape-all.pptx
 180 http://www.microsoft.com/en-us/download/details.aspx?id=30425
 181
 182 FUTURE WORK: because we have to make sure that all the roundtrips
 183 like PPTX --> ODP --> PPTX work correctly and doesn't lose data.
 184 the only problematic part is probably saving custom shapes (ie. not
 185 presets) to PPTX. that part of code predates work on custom shapes
 186 and is unable to export general custom shapes yet. it will need a bit
 187 of work as LO has more complex equations than DrawingML. other parts
 188 should work OK, PPTX --> ODP should work and don't lose any
 189 data. presets should already survive PPTX --> ODP --> PPTX roundtrip