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 ```xml
  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
 124 we needed to extend our custom shapes for missing features and so 5
 125 new segment commands were added. `G` command for arcto drawingml record
 126 and `H` `I` `J` `K` commands for darken, darkenless, lighten, lightenless
 127 records. the commands are save into ODF in special namespace drawooo,
 128 which is extension not yet in the standard. Thorsten suggested to put
 129 it in such a namespace and keep original (incomplete) geometry for
 130 backward compatibility, before we can extend the ODF. that's why you
 131 will see 2 of them in cases where some of the new commands was
 132 needed.
 133
 134 In order to convert preset shapes to LO's enhanced custom shape,
 135 we need to load shape definition of preset shapes. The procedure
 136 to convert the definition from OOXML spec for LO is documented
 137 (also a script) in `oox/source/drawingml/customshapes/README.md`.
 138 The scripts in `oox/source/drawingml/customshapes/` also generate pptx
 139 files for single presets and also for all presets
 140 `cshape-all.pptx`. The cshape-all.pptx file is then loaded into Impress
 141 build with debug enabled in oox and the command line output contains
 142 information. The generated definition is `oox-drawingml-cs-presets`.
 143
 144 Check `CustomShapeProperties::initializePresetDataMap()` to see how
 145 generated presets data are loaded into LO.
 146 While importing presets, we prefix the name with "ooxml-" so
 147 that we can detect it on export as save it again as preset.
 148
 149 The generated pptx files
 150 can be used when debugging bugs in custom shapes import/export. also
 151 the cshape-all.pptx can be used to test the round trips. there's small
 152 problem with these pptx as they cannot be imported into powerpoint,
 153 but that can be fixed quickly. when fixed, we can use it to
 154 test powerpoint odp export and see how complete it is regarding
 155 custom shapes. OpenXML SDK tools might help when fixing
 156 `cshape-all.pptx`
 157 <http://www.microsoft.com/en-us/download/details.aspx?id=30425>
 158
 159 ## Export
 160 Here is how LO's enhanced custom shapes are exported:
 161
 162 * Shape name is `ooxml-*` - they are imported from ooxml, export as is.
 163 * Denylist - ODF presets that has OOXML equivalent.
 164   We convert adjustment values case by case. Microsoft Office
 165   is rather strict about adjustment values, either none of them
 166   are provided so that default values are taken, or the exact set
 167   of handles have to be provided. In some cases we are converting
 168   from the preset with less handles to the one with more handles
 169   so that default values suitable for the odf one need to be
 170   provided.
 171 * Allowlist - ODF presets that has OOXML equivalent but looks a bit
 172 different, export them as `PolyPolygon`.
 173
 174 Check Andras Timar's presentation[1] and `ShapeExport::WriteCustomShape()`
 175 for further detail.
 176
 177 ## Future Works
 178 Because we have to make sure that all the roundtrips
 179 like PPTX --> ODP --> PPTX work correctly and doesn't lose data.
 180 the only problematic part is probably saving custom shapes (ie. not
 181 presets) to PPTX. that part of code predates work on custom shapes
 182 and is unable to export general custom shapes yet. It will need a bit
 183 of work as LO has more complex equations than `DrawingML`. other parts
 184 should work OK, PPTX --> ODP should work and don't lose any
 185 data. presets should already survive PPTX --> ODP --> PPTX roundtrip
 186
 187 [1] <https://archive.fosdem.org/2016/schedule/event/drawingml/attachments/slides/1184/export/events/attachments/drawingml/slides/1184/andras_timar_fosdem_2016.pdf>