oox/README

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