Writer/Unification of Graphic Objects and Embedded Objects

From Apache OpenOffice Wiki
< Writer
Revision as of 09:38, 5 November 2013 by Od (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Writer Icon.png

Writer Project

Please view the guidelines
before contributing.

Popular Subcategories:

Internal Documentation:

API Documentation:

Ongoing Efforts:

Sw.OpenOffice.org

Replacement of Writer graphic/embedded object by Draw graphic/embedded object.

Benefit of this unification

The motivations for replacing the Writer graphic object and the Writer embedded object by the Draw graphic object respectively Draw embedded object are the following:

  • Only one implementation for the same type of object in all applications of OOo – consolidation of OOo's code basis.In the OpenDocument file format and the OpenOffice.org file format such a distinction also doesn't exist.
  • Only one user interface for the same type of object in all applications of OOo. Exceptions should/will exist only for the specific properties for an application – e.g. position and size dialog in Writer.
  • Asynchronous loading of linked graphics have to be solved only once.
  • Rotation of graphics in Writer, also needed for Microsoft Word interoperability.
  • Interactive cropping functionality of Draw graphic objects becomes available in Writer.
  • Grouping of graphics and embedded objects in Writer with other Draw objects, also needed for Microsoft Word interoperability.
  • Workaround in WW8 import filter, which replaces grouped embedded objects by grouped graphic objects, can be removed.
  • Workaround in copy-and-paste from Draw/Impress/Calc into Writer, which replaces grouped embedded objects by grouped graphic objects, can be removed.
  • Workaround after load, which replaces grouped embedded objects by grouped graphic objects, can be removed.

Missing features at Draw graphic/embedded object

Draw graphic object

From the Writer perspective the following features are missing at the Draw graphic object:

  • Writer border properties
  • Hyperlink properties
  • Macro properties
  • Writer horizontal flipping property – flipping dependent of the the page type (odd or even)
  • Cropping functionality not available
  • Style support
  • Contour properties for the wrapping of the text around the graphic.

Draw embedded object

From the Writer perspective the following features are missing at the Draw embedded object:

  • Writer border properties
  • Hyperlink properties
  • Macro properties
  • Solid and transparent background color as fillingA background color becomes visible in Writer, if a border and a border distance are applied to a Writer embedded object.
  • Solid and transparent background graphic as fillingA background graphic becomes visible in Writer, if a border and a border distance are applied to a Writer embedded object.
  • Shadow
  • Style support
  • Contour properties for the wrapping of the text around the embedded object.

Decisions about implementation

Discussion between AW, OS and OD (in 2006) reveals that:

  • The Writer border properties has to be natively supported by the Draw graphic object respectively Draw embedded object.
  • The hyperlink and macro properties will be implemented in Writer and in Draw.
  • The Writer horizontal flipping property can only be implemented in the Draw with refactoring of the Drawing layer, which would cost a lot of effort. We (AW and OD) would vote for this refactoring. As an alternative this missing feature could also been implemented in the Writer. Keeping in mind that the Drawing layer hasn't got any knowledge about odd and even pages, because the Writer only creates one Drawing page for the complete Writer document, this alternative becomes more attractive. Thus, the Writer horizontal flipping will be implemented in Writer.
  • The cropping functionality has been to made available in Writer.
  • The background color/graphic as filling and the shadow has to be natively supported by the Draw embedded object.
  • The contour properties are only needed in Writer. Thus, its support for Draw objects (in general or only for Draw graphic object and Draw embedded object) should be done in Writer.
  • The style support will be implemented in Writer and in Draw generally for Draw objects. In the first step, only the properties, which are currently supported in Writer as style properties, will be implemented. These are:
    • Size and position properties
    • Option properties – see pane “Options”
    • Wrapping properties
    • Background properties – color and graphic as filling
    • Border properties
    • Shadow properties
    • Macro properties

Refactoring of Writer's usage of the Drawing layer

see also http://wiki.services.openoffice.org/wiki/Refactoring_of_Writer%27s_usage_of_the_Drawing_layer.

Actual discussion between AW, HBRINKM and OD (in 2009-03) reveals that before replacing the Writer graphic object and the Writer embedded object by the corresponding Draw object a refactoring of the Writer's usage of the Drawing layer should be performed. The Writer should use the Drawing layer with a separation of model and view:

  • The Writer model should hold one Draw model for the model information about Drawing objects. This Draw model is called “Draw model” in the following and is used for load, save and UNO-API modifications.
  • Each Writer view should hold its own Draw model for visualization. Such a Draw model is called “Draw view model” in the following. The visualized Draw objects are clones from their corresponding Draw object of the Draw model.The Writer takes care of the relationships between the Draw object in the Draw model and its clones in the Draw view model(s).Note: Due to the fact that currently all Writer views share only one layout only one Draw view model is needed at the moment. Thus, the Draw view model will be bound to the layout. When each Writer view will get its own layout, then each Writer view will also have its own Draw view model.
  • Interactive changes of the user at Draw objects will take place at the clone Draw object in the Draw view model. These changes have to propagated to Draw object in the Draw model and the other existing clone Draw objects.
  • Changes via the UNO-API or by the user via e.g. format dialog at the Draw object in the Draw model have to propagated to the existing clone Draw objects in the Draw view model(s).
  • It seems that the UNDO of a certain change can be handled at the Draw object, at which the change is performed.

The motivation for this refactoring is that the following problems will be solved:

  • Controls in repeated areas (page header, page footer and table header rows) will work.
  • Several problems with Draw objects in repeated areas will be solved due to the fact that the concept of virtual Draw objects is no longer used.E.g. text animations in Draw objects in repeated areas does not work.
  • Remove of special code for virtual Draw objects in module svx, which is only used by the Writer.
  • The Writer gets more control over the changes made at Draw objects.
  • Former problems, which arise during the implementation of multiple different views support in Writer, will also been solved “by side effect”.

Implication of loading ODF text documents in previous versions of OOo

On graphics

Case A: A graphic is identified as a Writer graphic. Then, it will lose all properties, which are only supported by Draw graphic objects. This is only the rotation property and the shadow property (because of different exceptation how it's represented in ODF).There will be also some difference in the layout, because the border for Writer graphic objects is drawn inside the frame area, while it is drawn outside the frame area for Draw graphic objects. But, typically inserted graphic objects haven't got any border.

Case B: A graphic is identified as a Draw graphic object. Then, it will lose the border, border distance, Writer horizontal flipping, hyperlink and macro properties.

Version of OOo prior to 2.0.3 distinguish between Writer graphic and Draw graphic by an existing name for the graphic. Since version OOo 2.0.3 the distinctive criterion is the existence of a style for the graphic. Thus, case B will not occur, because all graphics will have a name and a style – see previous chapter, task 5.

On embedded objects

An embedded object will lose all properties, which are only supported by Draw embedded objects. This is only the shadow property (because of different exceptation how it's represented in ODF)

There will be some difference in the layout, because – as for graphics – the border for Writer embedded objects is drawn inside the frame area, while it will drawn outside the frame area for Draw embedded objects. But, typically inserted embedded objects haven't got any border.

Implication of loading ODF text documents from previous versions of OOo

On graphics

Case A: A graphic is in the previous version identified as a Writer graphic. Then, no properties will be lost. There will be some difference in the layout, because the border for Writer graphic objects is drawn inside the frame area, while it will drawn outside the frame area for Draw graphic.

Case B: A graphic is in the previous version identified as a Draw graphic. Then, no properties will be lost. There will be also no difference in the layout.

On embedded objects

No properties will be lost. There will be some difference in the layout, because – as for graphics – the border for Writer embedded objects is drawn inside the frame area, while it will drawn outside the frame area for Draw embedded objects. But, typically inserted embedded objects haven't got any border.

Implementation roadmap

Drawing layer usage refactoring in Writer

see http://wiki.services.openoffice.org/wiki/Refactoring_of_Writer%27s_usage_of_the_Drawing_layer#Implementation_details

Unification tasks in Draw

Border properties

In order to replace the Writer graphic/embedded object by the Draw graphic/embedded object the Draw graphic/embedded object has to be enhanced by the Writer border properties:

  • Support of the Writer graphic/embedded object border properties– see com::sun::star::text::BaseFrameProperties for the API– see Menu -> Format -> Picture -> Borders for the dialog
    • Support of different borders for top, bottom, left and right– see ...::text::BaseFrameProperties::TopBorder || BottomBorder || LeftBorder || RightBorder
    • Support of double line borders – see ...::table::BorderLine
    • Support of distance between border and graphic/embedded content– see ...::text::BaseFrameProperties::BorderDistance || TopBorderDistance || LeftBorderDistance || RightBorderDistanceNote: These distance values are also used to describe the distances between the border and the text.

These border properties are planned to be implemented for all rectangular drawing objects and can be done independently from the replacement of the Writer graphic/embedded object by the Draw graphic/embedded object. But it's a prerequisite for the replacement.

These border properties will exist beside the current line properties of a rectangular drawing object – see com::sun::star::drawing::LineProperties. Both property sets will be applied/drawn to a rectangular drawing object – first the current line properties then the new border properties.

The Writer offers the new border properties for Draw graphic objects, the other applications offer the current line properties. If in Writer the border properties are set (via user interface or UNO-API), the line properties should be cleared. If in the other applications the line properties are set (via user interface or UNO-API), the border properties should be cleared.

Note: Currently in Writer the distance between border and graphic/embedded content is only applied, if a border line is drawn at the corresponding side. This should be corrected, also due to better ODF conformance.

Note: No certain corner join style is implemented in Writer – it's mostly similar to mitered. This corner style should be implemented for rectangular drawing objects with the new border properties.

The Writer graphic/embedded object border properties are currently reflected in the OpenDocument file format by the following attributes:

  1. <fo:border> and <fo:border-line-width> - border properties for all sides.
  2. <fo:border-top> and <fo:border-line-width-top> - border property for the top.
  3. <fo:border-bottom> and <fo:border-line-width-bottom> - border property for the bottom.
  4. <fo:border-left> and <fo:border-line-width-left> - border property for the left.
  5. <fo:border-right> and <fo:border-line-width-right> - border property for the right.
  6. <fo:padding> - border distance for all sides.
  7. <fo:padding-top>, <fo:padding-bottom>, <fo:padding-left> and <fo:padding-right> - border distance for the top, bottom, left and right.

Attributes 1. - 5. can be reused for drawing objects.

Note: Itempools and Itemsets in the applications have to be extended by the Writer border properties items.

The padding attributes 6. and 7. have to be reused, too. But, they are already used by drawing objects for the text content. Regarding the OASIS OpenDocument specification 1.0 – see http://www.oasis-open.org/committees/documents.php?wg_abbrev=office – this isn't correct. The <fo:padding> attributes are defined to determine the content area of a formatting object. This content area includes text, image, etc. Thus, the current usage of <fo:padding> for Draw objects is a defect. See the illustration given at www.w3.org/TR/REC-CSS2/box.html#img-boxdim for the details about the different box areas adopted by the OpenDocument file format from the CSS box model.

Some important notes about this illustration and its box areas:

  • The content area is the area, in which the content (text, image, embedded content, etc.) is drawn.
  • Cropping of an image has only influence on how the content area is filled. The area of the content area, which are left empty by using negative cropping, should be transparent.
  • A background drawn as a filling (e.g. color, gradient, hatching or bitmap) is drawn into the padding area and content area, but it's overlapped by the drawn content. E.g., if the content is a transparent image and the background/filling is red solid color, the red solid color will be visible through the transparent parts of the image.

The proposed solution is:

  • Correct behavior for Draw objects regarding <fo:padding> attributes – apply the values to every content, especially to image and embedded content.
  • The default values for <fo:padding> attributes for a Draw object are 0,25cm for <fo:padding-top> and <fo:padding-bottom> and 0,13cm for <fo:padding-left> and <fo:padding-right>. For Draw graphic objects and Draw embedded objects, which are inserted by the user using the user interface, these values should be overritten by 0cm.
  • Introduce a compatibility document option for all applications – not visible in the user interface – to handle documents from previous StarOffice/OOo versions.

Important note: This defect correction affects all applications and will cause that Draw graphic/embedded objects would look different in previous versions of StarOffice/OOo, when one of the border distance values isn't 0cm.

Background

Background is in general available in Draw for a Draw embedded object. But, it isn't drawn.

Shadow

Shadow is in general available in Draw for a Draw embedded object. But, it isn't drawn.

Important note: The shadow property for Writer graphic/embedded object is written into OpenDocument using <style:shadow> attribute. For Draw objects the OpenDocument attributes <draw:shadow>, <draw:shadow-offset-x>, <draw:shadow-offset-y>, <draw:shadow-color> and <draw:shadow-opacity> are written.According to discussion with MIB, OpenDocument <style:shadow> will not be written any more by OOo. But, this attribute has to be read and mapped accordingly.

Hyperlink

The hyperlink property has to be natively supported by Draw objects, at least by the Draw graphic object and by Draw embedded object.

Macro

The macro property has to be natively supported by Draw objects, at least by the Draw graphic object and by Draw embedded object.

Style

The size, background, border, shadow and macro properties hve to be supported by Draw objects as style properties. The style properties for a Draw object in Writer as a whole will be handled by the Writer style for the Draw object. The Writer style contains the properties of the Draw style plus its own ones (position, option and wrapping). The user interface will change the Writer style and the Writer style assures that each properties is propagated to the Draw style. During import and export the Draw style properties aren't filled respectively written.

Unification tasks in Writer

The following tasks have to be performed in Writer:

Horizontal flipping

Extend the Draw graphic object in Writer by the horizontal flipping property.

Interactive cropping

Make the interactive cropping functionality of Draw graphic objects available in Writer. The Writer toolbar “Draw object properties” needs a corresponding adjustment.

Contour

Extend Draw objects in Writer by the contour property (at least for the Draw graphic object and the Draw embedded object).

Functionality of Writer toolbar “Picture”

Make the functions of the Writer toolbar “Picture” for Writer graphic objects available for Draw graphic objects.

Functionality of Writer toolbar “OLE-Object”

Make the functions of the Writer toolbar “OLE-Object” for Writer embedded objects available for Draw embedded objects.

UNO-API for Draw graphic objects in Writer

Adjust UNO-API for Draw graphic objects in Writer:

  • service com::sun::star::text::TextGraphicObject has to be supported for Draw graphic objects.
  • interface com::sun::star::text::XTextGraphicObjectsSupplier has to supply also the Draw graphic objects.

UNO-API for Draw embedded objects in Writer:

Adjust API for Draw embedded objects in Writer:

  • service com::sun::star::text::TextEmbeddedObject has to be supported for Draw embedded objects.
  • interface com::sun::star::text::XTextEmbeddedObjectsSupplier has to supply also the Draw embedded objects.

Use the Draw graphic object instead of the Writer graphic object.

  • Completely delete the code for the Writer graphic object in the Writer.
  • Inserted Draw graphic objects will get a default name – a generated one, which is currently used for Writer graphic objects.
  • Inserted Draw graphic objects will get a default style – the one, which is currently used for Writer graphic objects.

Use the Draw embedded object instead of the Writer embedded object.

  • Solve problem, that currently Draw embedded objects aren't supported by the Writer.
  • Completely delete the code for the Writer embedded object in the Writer.
  • Inserted Draw embedded objects will get a default name – a generated one, which is currently used for Writer embedded objects.
  • Inserted Draw embedded objects will get a default style – the one, which is currently user for Writer embedded objects.

Adjust the import filters:

  • OpenDocument Text filter:
    • Import all graphic objects as Draw graphic objects. Identify 'old' Writer graphic objects in the file format and set appropriate attributes at the imported Draw graphic object – e.g. border distance values or shadow property.
    • Import all embedded objects as Draw embedded objects. Identify 'old' Writer embedded objects in the file format and set appropriate attributes at the imported Draw embedded object – e.g. border distance values or shadow property.
    • Import OpenDocument attribute <style:shadow> for all Draw objects.
  • WW8, RTF, WordML, docx, HTML filter:
    • Import each graphic as a Draw graphic object – no replacement of imported Draw graphic objects by Writer graphic objects (WW8, RTF, WordML and docx).
    • Import each embedded object as a Draw embedded object – no replacement of imported Draw embedded objects by Writer embedded objects (WW8, RTF, WordML and docx).
    • Keep setting of Writer specific properties (hyperlink, macro, etc.).
    • For WW8, RTF, WordML and docx adjust the border line import.

Adjust the export filters:

  • OpenDocument:
    • Suppress export of Draw style for each Draw object. Instead the Writer style for the Draw object is exported.
    • Shadow property - export as Draw shadow attributes.Thus, older versions of /OOo will lose this property, if the object is indentified as a Writer object.
  • OpenOffice.org filter:
    • Shadow property
    • [A-Nice-To-Have]: All graphics, which are named, are read as Writer graphic objects and all graphics, which aren't named, are read as Draw graphic objects. Thus, the filter could analyze each graphic object and decide depending on its properties, if it would be better to name it or not.
  • WW8, RTF, WordML, docx, HTML filter:
    • Export Writer specific properties for the Draw graphic/embedded objects.
      • WW8, RTF and WordML support the hyperlink property. The macro property and the horizontal flipping only on odd or even pages isn't supported by WW8, RTF and WordML. Adjust the export of the line border properties.
      • docx - ?
      • HTML supports the hyperlink property.

Adjust Writer toolbar 'Draw object properties'

ToDo: clarify what has to be adjusted.

Probably different toolbars for different types of Draw objects:

  • Draw graphic objects – see above
  • Draw embedded objects – see above
  • ...

Tests

test plan(s) for end user tests

API-Tests

UNIT-Tests

Media:Example.ogg

Personal tools