Difference between revisions of "TextAlignment"

From Apache OpenOffice Wiki
Jump to: navigation, search
({{bug|105270}})
m (BLA Text Alignment - OpenOffice.org vs. OpenDocument)
 
(6 intermediate revisions by the same user not shown)
Line 43: Line 43:
 
* Internally introduce new text alignment values <code>START</code> and <code>END</code> corresponding to ODF's <code>left/start</code> and <code>right/end</code> text alignment values. Additionally, the text formatting has to be adjusted to support these new text alignment values accordingly.
 
* Internally introduce new text alignment values <code>START</code> and <code>END</code> corresponding to ODF's <code>left/start</code> and <code>right/end</code> text alignment values. Additionally, the text formatting has to be adjusted to support these new text alignment values accordingly.
 
* Adjustment of the user interface.
 
* Adjustment of the user interface.
** There are two alternatives for the format dialogs for paragraphs, table cells and styles. In general the user will no longer have the possibility to apply text alignment values <code>LEFT</code> and <code>RIGHT</code> any more. Instead the new text alignment values <code>START</code> and <code>END</code> will be applied:
+
** Keep the terms ''left'' and ''right'' for the text alignment:
:: Drop in general the terms ''left'' and ''right'' for the text alignment:
+
*** Format dialogs for paragraphs, table cells and styles have to be made aware of the writing direction of the to be formatted object/objects or of the document. By this it can be assured that the text alignment values <code>START</code> and <code>END</code> are mapped to the right terms ''left'', ''right'', ''left/top'' and ''right/bottom'' and vice versa.
::: The terms ''left'', ''right'', ''left/top'' and ''right/bottom'' are dropped in favor of something similar to the XSL definition of the corresponding text alignment values <code>start</code> and <code>end</code>.
+
*** This has the drawback that for certain use cases the writing direction of the to be formatted objects is ambiguous. To be deterministic in all use cases the following solutions are implemented:
:: Keep the terms ''left'' and ''right'' for the text alignment:
+
**** In text documents the writing direction of the paragraph in which the cursor is in is taken.
::: Format dialogs for paragraphs, table cells and styles have to be made aware of the writing direction of the to be formatted object. By this it can be assured that the text alignment values <code>START</code> and <code>END</code> are mapped to the right terms ''left'', ''right'', ''left/top'' and ''right/bottom'' and vice versa.
+
**** In drawing objects and in table cells of Calc sheets OOo does not support different writing directions for its paragraphs table cells -> no drawbacks here.
** Formatting Toolbar buttons "Align left" and "Align right": Keep the actual terms and its visualization in its icons in order to visual reflect the behavior of these buttons. Internally, the correct text alignment values <code>START</code> respectively <code>END</code> need to be applied at the paragraph/table cell in order to corresponding the visualized behavior. E.g., if toolbar button "Align left" is clicked and the cursor is placed in a paragraph with right-to-left writing direction text alignment value <code>END</code> needs to be applied.
+
**** For two or more table cells with different writing directions in a Calc sheet the sheet's default writing direction is taken.** Formatting Toolbar buttons "Align left" and "Align right": Keep the actual terms and its visualization in its icons in order to visual reflect the behavior of these buttons. Internally, the correct text alignment values <code>START</code> respectively <code>END</code> need to be applied at the paragraph/table cell in order to corresponding the visualized behavior. E.g., if toolbar button "Align left" is clicked and the cursor is placed in a paragraph with right-to-left writing direction text alignment value <code>END</code> needs to be applied.
 
** Formatting Toolbar buttons "Left-to-Right" and "Right-to-Left" (visible, if enhanced support for complex text layout (CTL) has been enabled): Internally, the actual behavior of these functions are that the writing direction is set to <code>left-to-right</code> respectively <code>right-to-left</code> and the text alignment is set to <code>LEFT</code> respectively <code>RIGHT</code>. The setting of the text alignment needs to be adjusted to <code>START</code> for both functions.
 
** Formatting Toolbar buttons "Left-to-Right" and "Right-to-Left" (visible, if enhanced support for complex text layout (CTL) has been enabled): Internally, the actual behavior of these functions are that the writing direction is set to <code>left-to-right</code> respectively <code>right-to-left</code> and the text alignment is set to <code>LEFT</code> respectively <code>RIGHT</code>. The setting of the text alignment needs to be adjusted to <code>START</code> for both functions.
 
* Introduce a new UNO-API for the text alignment of paragraphs - com::sun::star::style::ParagraphProperties::ParaTextAlign with the possible values <code>START</code>, <code>END</code>, <code>BLOCK</code>, <code>CENTER</code> and <code>STRETCH</code>. Values <code>START</code> and <code>END</code> correspond to the internally newly introduced text alignment values. The values <code>BLOCK</code>, <code>CENTER</code> and <code>STRETCH</code> are the same as the ones from the existing UNO-API com::sun::star::style::ParagraphProperties::ParaAdjust.
 
* Introduce a new UNO-API for the text alignment of paragraphs - com::sun::star::style::ParagraphProperties::ParaTextAlign with the possible values <code>START</code>, <code>END</code>, <code>BLOCK</code>, <code>CENTER</code> and <code>STRETCH</code>. Values <code>START</code> and <code>END</code> correspond to the internally newly introduced text alignment values. The values <code>BLOCK</code>, <code>CENTER</code> and <code>STRETCH</code> are the same as the ones from the existing UNO-API com::sun::star::style::ParagraphProperties::ParaAdjust.
Line 177: Line 177:
  
 
=== Test cases for the proposed solution ===
 
=== Test cases for the proposed solution ===
 +
 +
===== Format Paragraph Dialog, Tab pane "Alignment" =====
 +
* Test functionality of setting alignment and text direction
 +
** for one paragraph
 +
*** no hard-set attribute values
 +
*** hard-set attribute values equal to the default ones
 +
*** hard-set attribute values different to the default ones
 +
** for two or more paragraphs with the same alignment/text direction attribute values
 +
** for two or more paragraphs with different alignment/text direction attribute values
 +
 +
===== Format Paragraph Style Dialog, Tab pane "Alignment" =====
 +
 +
* [need to be filled...]

Latest revision as of 10:17, 11 January 2011


Issue 105270

The following is about how to solve issue 105270 for OpenOffice.org.

Text Alignment - OpenOffice.org vs. OpenDocument

In OpenOffice.org (OOo) the text alignment attribute values LEFT and RIGHT are treated independent from the writing direction of the paragraph.

In OpenDocument (ODF) which relies on XSL - http://www.w3.org/TR/xsl/#text-align - the text alignment attribute values left and right are mapped to start respectively end. Thus, there are depending on the writing direction of the paragraph.

This is the root cause of the defect described in issue 105270. The text alignment of a paragraph whose writing direction is right-to-left and which is text-aligned at the right border is stored by OOo by ODF attribute fo:text-align="end". fo:text-align="end" is interpreted by OOo as internal text alignment attribute value RIGHT in order to align the paragraph at the right border. But, this is not correct regarding the ODF specification. According to the ODF specification the text alignment attribute value "end" means that the paragraph is text-aligned at the end-edge of the paragraph according to the writing direction. For a right-to-left paragraph this is the left border.

The defect of issue 105270 is a serious one regarding OOo's ODF support for documents which contain paragraphs whose writing direction is right-to-left. It causes also interoperability problems when exchanging such documents with other ODF supporting application, especially ODF supporting office productivity applications.

Easy Fix - but not sufficient

It looks like as this issue is easy to fix:

  • easy fix: Just change OOo's interpretation of its test alignment values LEFT and RIGHT and everything is ok.

Unfortunately, it is not that easy :(

There is no doubt that OOo has to support ODF's left/start and right/end for the text alignment and its corresponding meaning. But certain stuff has to be considered which will make the solution more complicate and will cost more effort. At least the following points need attention:

  1. OOo's format dialogs for paragraphs respectively paragraphs in table cells use terms left and right - left/top and right/bottom, if enhanced support for Asian languages has been enabled - for the text alignment. Correcting/Changing OOo's text alignment will have impact on this user interface.
  2. OOo's formatting toolbar uses terms left and right and corresponding visualizations of left-aligned respectively right-aligned text in its icons for the text alignment. Correcting/Changing OOo's text alignment will have impact on this user interface.
  3. OOo has corresponding UNO-APIs for its text alignment. These are com::sun::star::style::ParagraphProperties::ParaAdjust for paragraphs and com::sun::star::table::CellProperties::HoriJustify for the paragraphs in table cells. These UNO-APIs have writing direction independent text alignment values LEFT and RIGHT. Applying the easy fix would be an incompatible change of these UNO-APIs and would break existing extensions, macros, etc. which are using these UNO-APIs. Supporting these UNO-APIs - at least for one or two OOo version or until a major OOo release - is important and expected by the corresponding user group.
  4. OOo's import and export filters for foreign file formats needs to be adjusted when OOo's text alignment is corrected/changed.
  5. In order to fulfill the user expectations regarding the handling of ODF documents created by former OOo versions in a new OOo version existing ODF documents created by OOo versions which still have issue 105270 need to be "corrected" when handled by OOo versions in which issue 105270 has been fixed.
  6. ODF documents containing paragraphs whose writing direction is right-to-left and created by OOo versions in which issue 105270 has been fixed will be displayed incorrect in OOo versions which still have issue 105270. This is the nature of the defect described in issue 105270. But, it does not correspond to the user expectations regarding the handling of ODF documents created by newer OOo versions in a former OOo version. This problem already exists when handling ODF documents which are created by other ODF supporting applications. There is nothing to do to solve this problem, except updating to the last released OOo version. When preparing the OOo version in which issue 105270 will be fixed, this problem should be clearly communicated. At least the release notes should contain corresponding communication about the solution of issue 105270 and its impact.

Proposed Solution

Considering the thoughts of the previous chapter the following solution has been worked out:

  • Internally keep OOo's text alignment values LEFT and RIGHT with the current meaning and impact. The intention to keep these text alignment values is that they are only used for ODF documents which are created by former OOo versions which still have issue 105270 and for the support of the existing UNO-APIs in order not to break existing extensions, macros, etc. which are using these UNO-APIs.
  • Internally introduce new text alignment values START and END corresponding to ODF's left/start and right/end text alignment values. Additionally, the text formatting has to be adjusted to support these new text alignment values accordingly.
  • Adjustment of the user interface.
    • Keep the terms left and right for the text alignment:
      • Format dialogs for paragraphs, table cells and styles have to be made aware of the writing direction of the to be formatted object/objects or of the document. By this it can be assured that the text alignment values START and END are mapped to the right terms left, right, left/top and right/bottom and vice versa.
      • This has the drawback that for certain use cases the writing direction of the to be formatted objects is ambiguous. To be deterministic in all use cases the following solutions are implemented:
        • In text documents the writing direction of the paragraph in which the cursor is in is taken.
        • In drawing objects and in table cells of Calc sheets OOo does not support different writing directions for its paragraphs table cells -> no drawbacks here.
        • For two or more table cells with different writing directions in a Calc sheet the sheet's default writing direction is taken.** Formatting Toolbar buttons "Align left" and "Align right": Keep the actual terms and its visualization in its icons in order to visual reflect the behavior of these buttons. Internally, the correct text alignment values START respectively END need to be applied at the paragraph/table cell in order to corresponding the visualized behavior. E.g., if toolbar button "Align left" is clicked and the cursor is placed in a paragraph with right-to-left writing direction text alignment value END needs to be applied.
    • Formatting Toolbar buttons "Left-to-Right" and "Right-to-Left" (visible, if enhanced support for complex text layout (CTL) has been enabled): Internally, the actual behavior of these functions are that the writing direction is set to left-to-right respectively right-to-left and the text alignment is set to LEFT respectively RIGHT. The setting of the text alignment needs to be adjusted to START for both functions.
  • Introduce a new UNO-API for the text alignment of paragraphs - com::sun::star::style::ParagraphProperties::ParaTextAlign with the possible values START, END, BLOCK, CENTER and STRETCH. Values START and END correspond to the internally newly introduced text alignment values. The values BLOCK, CENTER and STRETCH are the same as the ones from the existing UNO-API com::sun::star::style::ParagraphProperties::ParaAdjust.
  • Introduce a new UNO-API for the text alignment of paragraphs in table cells - com::sun::star::table::CellProperties::CellTextAlign with the possible values STANDARD, START, CENTER, END, BLOCK and REPEAT. Values START and END correspond to the internally newly introduced text alignment values. The values STANDARD, CENTER, BLOCK and REPEAT are the same as the ones from the existing UNO-API com::sun::star::table::CellProperties::HoriJustify.
  • The ODF import filter has to distinguish two cases
Import of ODF documents which has been created by OOo versions which still have issue 105270. In this case ODF attribute fo:text-align is mapped using the existing UNO-APIs. This assures that such ODF documents are displayed as they are displayed in the OOo versions which still have issue 105270. We will get the following mapping:
fo:text-align value maps to
text alignment value
"left" LEFT
"start" LEFT
"right" RIGHT
"end" RIGHT
Import of other ODF documents. In this case the new UNO-APIs are used. We will get the following mapping:
fo:text-align value maps to
text alignment value
"left" START
"start" START
"right" END
"end" END
  • The new UNO-APIs have to return START respectively END when the text alignment attribute has text alignment value LEFT respectively RIGHT set. For this conversion two cases need to be distinguished.
Conversion for a certain style:
text alignment value writing direction
of the style (*1)
maps to
UNO-API text alignment value
LEFT left-to-right START
RIGHT left-to-right END
LEFT right-to-left END
RIGHT right-to-left START
Conversion for a certain paragraph or table cell:
text alignment value writing direction
of paragraph/table cell
writing direction
of style (*1)
maps to
UNO-API text alignment value
LEFT left-to-right left-to-right OR
right-to-left
START
LEFT
inherited from a style
left-to-right right-to-left START
RIGHT left-to-right left-to-right OR
right-to-left
END
RIGHT
inherited from a style
left-to-right right-to-left END
LEFT right-to-left left-to-right OR
right-to-left
END
LEFT
inherited from a style
right-to-left left-to-right END
RIGHT right-to-left left-to-right OR
right-to-left
START
RIGHT
inherited from a style
right-to-left left-to-right START
(*1) If the style has no writing direction set and does not inherit a writing direction from its parent style, the writing direction of the document is taken.
  • Deprecate the existing UNO-APIs com::sun::star::style::ParagraphProperties::ParaAdjust and com::sun::star::table::CellProperties::HoriJustify. Document that these UNO-APIs are deprecated in favor of the new ones. Assure that at these deprecated UNO-APIs text alignment values LEFT and RIGHT are returned, when the newly introduced text alignment values START and END are set at the internal text alignment attribute. The conversion will be documented in the UNO-API documentation and has to distinguish two cases:
Conversion for a certain style:
text alignment value writing direction
of style (*2)
maps to
UNO-API text alignment value
START left-to-right LEFT
END left-to-right RIGHT
START right-to-left RIGHT
END right-to-left LEFT
Conversion for a certain paragraph or table cell:
text alignment value writing direction
of paragraph/table cell
writing direction
of style (*2)
maps to
UNO-API text alignment value
START left-to-right left-to-right OR
right-to-left
LEFT
START
inherited from a style
left-to-right right-to-left LEFT
END left-to-right left-to-right OR
right-to-left
RIGHT
END
inherited from a style
left-to-right right-to-left RIGHT
START right-to-left left-to-right OR
right-to-left
RIGHT
START
inherited from a style
right-to-left left-to-right RIGHT
END right-to-left left-to-right OR
right-to-left
LEFT
END
inherited from a style
right-to-left left-to-right LEFT
(*2) If the style has no writing direction set and does not inherit a writing direction from its parent style, the writing direction of the document is taken.
  • The ODF export filter will only use the newly introduced UNO-APIs. Thus, written ODF attribute fo:text-align="left"/"start" respectively fo:text-align="right"/"end" will be according to the ODF specification.
  • Each export and import filter for foreign file formats needs to be reviewed and adjusted according to the above given conversions. In order to keep the current behavior of these filters in the first step they can rely on the existing text alignment values. In a follow-up task considering that in a future version the deprecated UNO-APIs will be removed and considering the foreign file format's text alignment definition further adjustments to the export and import filters can be made.
Import filters can continue to use the existing internal APIs or the existing UNO-APIs to set the text alignment values.
Export filters can also use the existing internal APIs or the existing, but deprecated UNO-APIs to retrieve the text alignment values. In the case that the existing internal APIs are used the new text alignment values START and END need to be converted as given above for the existing, but deprecated UNO-APIs.

Test cases for the proposed solution

Format Paragraph Dialog, Tab pane "Alignment"
  • Test functionality of setting alignment and text direction
    • for one paragraph
      • no hard-set attribute values
      • hard-set attribute values equal to the default ones
      • hard-set attribute values different to the default ones
    • for two or more paragraphs with the same alignment/text direction attribute values
    • for two or more paragraphs with different alignment/text direction attribute values
Format Paragraph Style Dialog, Tab pane "Alignment"
  • [need to be filled...]
Personal tools