oox/README.md

   1 # Office Open XML (ooxml) Support
   2
   3 Support for Office Open XML, the office XML-format designed by Microsoft.
   4
   5 ## DrawingML Custom shapes and presets
   6
   7 Custom shapes are part of DrawingML and are different to binary ppt
   8 and VML in older formats.
   9 The import happens in `oox/source/drawingml`, where they are
  10 imported as LO's enhanced custom shape's. see
  11 `offapi/com/sun/star/drawing/CustomShape.idl` and
  12 `offapi/com/sun/star/drawing/EnhancedCustomShape*.idl`
  13 Check `CustomShapeProperties::pushToPropSet()` and see
  14 how custom shape properties are converted.
  15
  16 Preset shapes are custom shapes whose guides and handles
  17 have been defined in OOXML specification. By specifying
  18 preset type and the adjustment values, the reset can
  19 be taken from the shape definition.
  20
  21 example of drawingml preset:
  22
  23          <a:prstGeom prst="star5">
  24            <a:avLst/>
  25          </a:prstGeom>
  26
  27 example of drawingml custom shape (equal to star5 preset):
  28
  29    <avLst xmlns="http://schemas.openxmlformats.org/drawingml/2006/main">
  30      <gd name="adj" fmla="val 19098" />
  31      <gd name="hf" fmla="val 105146" />
  32      <gd name="vf" fmla="val 110557" />
  33    </avLst>
  34    <gdLst xmlns="http://schemas.openxmlformats.org/drawingml/2006/main">
  35      <gd name="a" fmla="pin 0 adj 50000" />
  36      <gd name="swd2" fmla="*/ wd2 hf 100000" />
  37      <gd name="shd2" fmla="*/ hd2 vf 100000" />
  38      <gd name="svc" fmla="*/ vc  vf 100000" />
  39      <gd name="dx1" fmla="cos swd2 1080000" />
  40      <gd name="dx2" fmla="cos swd2 18360000" />
  41      <gd name="dy1" fmla="sin shd2 1080000" />
  42      <gd name="dy2" fmla="sin shd2 18360000" />
  43      <gd name="x1" fmla="+- hc 0 dx1" />
  44      <gd name="x2" fmla="+- hc 0 dx2" />
  45      <gd name="x3" fmla="+- hc dx2 0" />
  46      <gd name="x4" fmla="+- hc dx1 0" />
  47      <gd name="y1" fmla="+- svc 0 dy1" />
  48      <gd name="y2" fmla="+- svc 0 dy2" />
  49      <gd name="iwd2" fmla="*/ swd2 a 50000" />
  50      <gd name="ihd2" fmla="*/ shd2 a 50000" />
  51      <gd name="sdx1" fmla="cos iwd2 20520000" />
  52      <gd name="sdx2" fmla="cos iwd2 3240000" />
  53      <gd name="sdy1" fmla="sin ihd2 3240000" />
  54      <gd name="sdy2" fmla="sin ihd2 20520000" />
  55      <gd name="sx1" fmla="+- hc 0 sdx1" />
  56      <gd name="sx2" fmla="+- hc 0 sdx2" />
  57      <gd name="sx3" fmla="+- hc sdx2 0" />
  58      <gd name="sx4" fmla="+- hc sdx1 0" />
  59      <gd name="sy1" fmla="+- svc 0 sdy1" />
  60      <gd name="sy2" fmla="+- svc 0 sdy2" />
  61      <gd name="sy3" fmla="+- svc ihd2 0" />
  62      <gd name="yAdj" fmla="+- svc 0 ihd2" />
  63    </gdLst>
  64    <ahLst xmlns="http://schemas.openxmlformats.org/drawingml/2006/main">
  65      <ahXY gdRefY="adj" minY="0" maxY="50000">
  66        <pos x="hc" y="yAdj" />
  67      </ahXY>
  68    </ahLst>
  69    <cxnLst xmlns="http://schemas.openxmlformats.org/drawingml/2006/main">
  70      <cxn ang="3cd4">
  71        <pos x="hc" y="t" />
  72      </cxn>
  73      <cxn ang="cd2">
  74        <pos x="x1" y="y1" />
  75      </cxn>
  76      <cxn ang="cd4">
  77        <pos x="x2" y="y2" />
  78      </cxn>
  79      <cxn ang="cd4">
  80        <pos x="x3" y="y2" />
  81      </cxn>
  82      <cxn ang="0">
  83        <pos x="x4" y="y1" />
  84      </cxn>
  85    </cxnLst>
  86    <rect l="sx1" t="sy1" r="sx4" b="sy3" xmlns="http://schemas.openxmlformats.org/drawingml/2006/main" />
  87    <pathLst xmlns="http://schemas.openxmlformats.org/drawingml/2006/main">
  88      <path>
  89        <moveTo>
  90          <pt x="x1" y="y1" />
  91        </moveTo>
  92        <lnTo>
  93          <pt x="sx2" y="sy1" />
  94        </lnTo>
  95        <lnTo>
  96          <pt x="hc" y="t" />
  97        </lnTo>
  98        <lnTo>
  99          <pt x="sx3" y="sy1" />
 100        </lnTo>
 101        <lnTo>
 102          <pt x="x4" y="y1" />
 103        </lnTo>
 104        <lnTo>
 105          <pt x="sx4" y="sy2" />
 106        </lnTo>
 107        <lnTo>
 108          <pt x="x3" y="y2" />
 109        </lnTo>
 110        <lnTo>
 111          <pt x="hc" y="sy3" />
 112        </lnTo>
 113        <lnTo>
 114          <pt x="x2" y="y2" />
 115        </lnTo>
 116        <lnTo>
 117          <pt x="sx1" y="sy2" />
 118        </lnTo>
 119        <close />
 120      </path>
 121    </pathLst>
 122
 123 we needed to extend our custom shapes for missing features and so 5
 124 new segment commands were added. `G` command for arcto drawingml record
 125 and `H` `I` `J` `K` commands for darken, darkenless, lighten, lightenless
 126 records. the commands are save into ODF in special namespace drawooo,
 127 which is extension not yet in the standard. Thorsten suggested to put
 128 it in such a namespace and keep original (incomplete) geometry for
 129 backward compatibility, before we can extend the ODF. that's why you
 130 will see 2 of them in cases where some of the new commands was
 131 needed.
 132
 133 In order to convert preset shapes to LO's enhanced custom shape,
 134 we need to load shape definition of preset shapes. The procedure
 135 to convert the definition from OOXML spec for LO is documented
 136 (also a script) in `oox/source/drawingml/customshapes/README.md`.
 137 The scripts in `oox/source/drawingml/customshapes/` also generate pptx
 138 files for single presets and also for all presets
 139 `cshape-all.pptx`. The cshape-all.pptx file is then loaded into Impress
 140 build with debug enabled in oox and the command line output contains
 141 information. The generated definition is `oox-drawingml-cs-presets`.
 142
 143 Check `CustomShapeProperties::initializePresetDataMap()` to see how
 144 generated presets data are loaded into LO.
 145 While importing presets, we prefix the name with "ooxml-" so
 146 that we can detect it on export as save it again as preset.
 147
 148 The generated pptx files
 149 can be used when debugging bugs in custom shapes import/export. also
 150 the cshape-all.pptx can be used to test the round trips. there's small
 151 problem with these pptx as they cannot be imported into powerpoint,
 152 but that can be fixed quickly. when fixed, we can use it to
 153 test powerpoint odp export and see how complete it is regarding
 154 custom shapes. OpenXML SDK tools might help when fixing
 155 `cshape-all.pptx`
 156 <http://www.microsoft.com/en-us/download/details.aspx?id=30425>
 157
 158 ## Export
 159 Here is how LO's enhanced custom shapes are exported:
 160
 161 * Shape name is `ooxml-*` - they are imported from ooxml, export as is.
 162 * Denylist - ODF presets that has OOXML equivalent.
 163   We convert adjustment values case by case. Microsoft Office
 164   is rather strict about adjustment values, either none of them
 165   are provided so that default values are taken, or the exact set
 166   of handles have to be provided. In some cases we are converting
 167   from the preset with less handles to the one with more handles
 168   so that default values suitable for the odf one need to be
 169   provided.
 170 * Allowlist - ODF presets that has OOXML equivalent but looks a bit
 171 different, export them as `PolyPolygon`.
 172
 173 Check Andras Timar's presentation[1] and `ShapeExport::WriteCustomShape()`
 174 for further detail.
 175
 176 ## Future Works
 177 Because we have to make sure that all the roundtrips
 178 like PPTX --> ODP --> PPTX work correctly and doesn't lose data.
 179 the only problematic part is probably saving custom shapes (ie. not
 180 presets) to PPTX. that part of code predates work on custom shapes
 181 and is unable to export general custom shapes yet. It will need a bit
 182 of work as LO has more complex equations than `DrawingML`. other parts
 183 should work OK, PPTX --> ODP should work and don't lose any
 184 data. presets should already survive PPTX --> ODP --> PPTX roundtrip
 185
 186 [1] <https://archive.fosdem.org/2016/schedule/event/drawingml/attachments/slides/1184/export/events/attachments/drawingml/slides/1184/andras_timar_fosdem_2016.pdf>