From ed5640d8b587fbcfed7dd7967f3de04b37a76f26 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 11:06:44 +0200 Subject: Adding upstream version 4:7.4.7. Signed-off-by: Daniel Baumann --- oox/README.md | 193 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 193 insertions(+) create mode 100644 oox/README.md (limited to 'oox/README.md') diff --git a/oox/README.md b/oox/README.md new file mode 100644 index 000000000..73e7449e5 --- /dev/null +++ b/oox/README.md @@ -0,0 +1,193 @@ +# Office Open XML (ooxml) Support + +Support for Office Open XML, the office XML-format designed by Microsoft. + +## DrawingML Custom shapes and presets + +Custom shapes are part of DrawingML and are different to binary ppt +and VML in older formats. +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` +Check `CustomShapeProperties::pushToPropSet()` and see +how custom shape properties are converted. + +Preset shapes are custom shapes whose guides and handles +have been defined in OOXML specification. By specifying +preset type and the adjustment values, the reset can +be taken from the shape definition. + +example of drawingml preset: +```xml + + + +``` + +example of drawingml custom shape (equal to star5 preset): +```xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +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. + +In order to convert preset shapes to LO's enhanced custom shape, +we need to load shape definition of preset shapes. The procedure +to convert the definition from OOXML spec for LO is documented +in `oox/source/drawingml/customshapes/README.md`. +The `oox/source/drawingml/customshapes/generate.sh` script generate pptx +files for single 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. The generated definition is `oox-drawingml-cs-presets`. + +Check `CustomShapeProperties::initializePresetDataMap()` to see how +generated presets data are loaded into LO. +While importing presets, we prefix the name with "ooxml-" so +that we can detect it on export as save it again as preset. + +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 might help when fixing `cshape-all.pptx` + + + +Also, "OOXML Viewer VSCode Extension" is a useful tool for debugging +OOXML documents. + + + +## Export +Here is how LO's enhanced custom shapes are exported: + +* Shape name is `ooxml-*` - they are imported from ooxml, export as is. +* Denylist - ODF presets that has OOXML equivalent. + We convert adjustment values case by case. Microsoft Office + is rather strict about adjustment values, either none of them + are provided so that default values are taken, or the exact set + of handles have to be provided. In some cases we are converting + from the preset with less handles to the one with more handles + so that default values suitable for the odf one need to be + provided. +* Allowlist - ODF presets that has OOXML equivalent but looks a bit +different, export them as `PolyPolygon`. + +Check Andras Timar's presentation[1] and `ShapeExport::WriteCustomShape()` +for further detail. + +## Future Works +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 + +[1] -- cgit v1.2.3