Difference between revisions of "Writer/Accessibility"

From Apache OpenOffice Wiki
Jump to: navigation, search
m (Proposal from joaniediggs (mailto:joaniediggs@openoffice.org) taken from IssueZilla issue)
m
 
(25 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
{{Writer Project|Category=Writer/Accessibility}}
 
{{Writer Project|Category=Writer/Accessibility}}
 
[[Category:Accessibility]]
 
[[Category:Accessibility]]
[[Category:Writer/Effort]]
+
[[Category:Writer/Effort/Completed]]
 
__TOC__
 
__TOC__
  
Line 12: Line 12:
 
The comments of a Writer document are also known as notes (prior to OOo 3.2) or annotations (OpenDocument file format specification, version 1.0, 1.1 and 1.2).
 
The comments of a Writer document are also known as notes (prior to OOo 3.2) or annotations (OpenDocument file format specification, version 1.0, 1.1 and 1.2).
  
Working out the details is work in progress.
+
=== Refined proposal ===
  
=== Proposal from joaniediggs (mailto:joaniediggs@openoffice.org) taken from IssueZilla issue ===
+
After a deeper look at the current presentation of a comment in the user interface (used windows and controls), prototyping some stuff and considering joaniediggs' (mailto:joaniediggs@openoffice.org) proposal and williewalker's (mailto:williewalker@openoffice.org) input the following document hierarchy results as a refined proposal of a document hierarchy seen by accessibility tool Accerciser for a comment:
  
The document hierarchy seen by accessibility tool Accerciser for a comment which annotates a certain text position in the third paragraph of a Writer document should look like:
+
<div style="background:#cccccc;width:60%">
<div style="background:#cccccc">
+
 
:-> ATK_ROLE_DOCUMENT_FRAME
 
:-> ATK_ROLE_DOCUMENT_FRAME
 
::-> ATK_ROLE_PARAGRAPH
 
::-> ATK_ROLE_PARAGRAPH
Line 23: Line 22:
 
::-> ATK_ROLE_PARAGRAPH
 
::-> ATK_ROLE_PARAGRAPH
 
:::-> ATK_ROLE_SCROLL_PANE
 
:::-> ATK_ROLE_SCROLL_PANE
 +
::::-> ATK_ROLE_PANEL
 
::::-> ATK_ROLE_PARAGRAPH ("Annotation")
 
::::-> ATK_ROLE_PARAGRAPH ("Annotation")
 
::::-> ATK_ROLE_PARAGRAPH ("1st paragraph bold")
 
::::-> ATK_ROLE_PARAGRAPH ("1st paragraph bold")
 
::::-> ATK_ROLE_PARAGRAPH ("2nd paragraph italic")
 
::::-> ATK_ROLE_PARAGRAPH ("2nd paragraph italic")
 
::::-> ATK_ROLE_PARAGRAPH ("3rd paragraph centered")
 
::::-> ATK_ROLE_PARAGRAPH ("3rd paragraph centered")
::::-> ATK_ROLE_{TEXT,PARAGRAPH} ("Oliver-Rainer Wittmann")
+
:::-> ATK_ROLE_TEXT ("Oliver-Rainer Wittmann")
::::-> ATK_ROLE_{TEXT,PARAGRAPH} ("12/12/2008 15:01")
+
:::-> ATK_ROLE_TEXT ("12/12/2008 15:01")
::::-> ATK_ROLE_PUSH_BUTTON
+
:::-> ATK_ROLE_PUSH_BUTTON
 
::-> ATK_ROLE_PARAGRAPH
 
::-> ATK_ROLE_PARAGRAPH
 
::-> ATK_ROLE_PARAGRAPH
 
::-> ATK_ROLE_PARAGRAPH
 +
:::-> ATK_ROLE_UNKNOWN [exist when comment annotates text range; its a non-showing accessible object]
 
::-> ATK_ROLE_PARAGRAPH
 
::-> ATK_ROLE_PARAGRAPH
 
</div>
 
</div>
 
The scroll pane shall represent the comment by which the comment's position can be determined. Its children are the comment's content - paragraphs - followed by two texts containing the author and the date of the comment. The last children is a push button. In the user interface the push button is used to open a context menu with certain actions on comments.
 
 
=== Refined proposal from od (mailto:od@openoffice.org) ===
 
 
After a deeper look at the current presentation of a comment in the user interface (used windows and controls), prototyping some stuff and considering williewalker's (mailto:williewalker@openoffice.org) input the following document hierarchy results as a refined proposal:
 
 
-> ATK_ROLE_DOCUMENT_FRAME
 
  -> ATK_ROLE_PARAGRAPH
 
  -> ATK_ROLE_PARAGRAPH
 
  -> ATK_ROLE_PARAGRAPH
 
      -> ATK_ROLE_NOTE
 
        -> ATK_ROLE_PANEL
 
            -> ATK_ROLE_PARAGRAPH ("Annotation")
 
            -> ATK_ROLE_PARAGRAPH ("1st paragraph bold")
 
            -> ATK_ROLE_PARAGRAPH ("2nd paragraph italic")
 
            -> ATK_ROLE_PARAGRAPH ("3rd paragraph centered")
 
        -> ATK_ROLE_TEXT ("Oliver-Rainer Wittmann")
 
        -> ATK_ROLE_TEXT ("12/12/2008 15:01")
 
        -> ATK_ROLE_PUSH_BUTTON
 
  -> ATK_ROLE_PARAGRAPH
 
  -> ATK_ROLE_PARAGRAPH
 
      -> ATK_ROLE_NOTE_END
 
  -> ATK_ROLE_PARAGRAPH
 
  
 
=== Requirements ===
 
=== Requirements ===
Line 63: Line 40:
 
Below is a list of requirements which are collected from the comments of the IssueZilla issue. Sometimes a refinement or a possible proposal for its solution is given:
 
Below is a list of requirements which are collected from the comments of the IssueZilla issue. Sometimes a refinement or a possible proposal for its solution is given:
  
# Identification of the uppermost accessible object by OOo's accessible role "COMMENT". This accessible role should be mapped to ATK_ROLE_NOTE in OOo's ATK bridge.
+
# [SOLVED in cws sw33a11y01] Identification of the uppermost accessible object by OOo's accessible role "COMMENT". <span style="background: tomato; color: white;">'''(ES: term "COMMENT" not found in Accerciser)'''</span>
# Accessible name "Author" for the accessible object representing the fixed text window control containing the author's name.
+
#* In OOo's ATK bridge this accessible role should be mapped to ATK role ATK_ROLE_SCROLL_PANE <span style="background: green; color: white;">'''(ES: FIXED)'''</span>
# Accessible name "Date" for the accessible object representing the fixed text window control containing comment's creation date.
+
#* [POSTPONED until OOo's base line for Gnome contains at least ATK 1.12] New AtkAttribute { "xml_roles", "note" }. The AtkAttribute should be provided via ATK-method <AtkObject::atk_object_get_attributes(..)>
# Accessible name "Actions" and accessible description "Activate this button to open a list of actions to perform on this comment" for the accessibility object which represents the push button
+
# [SOLVED in cws sw33a11y01] Accessible name "Author" for the accessible object representing the fixed text window control containing the author's name.<span style="background: green; color: white;">'''(ES: FIXED)'''</span>
# Tool tip for push button containing its accessible description.
+
# [SOLVED in cws sw33a11y01] Accessible name "Date" for the accessible object representing the fixed text window control containing comment's creation date.<span style="background: green; color: white;">'''(ES: FIXED)'''</span>
# The special character in the paragraph's text which marks the text position which a comment is annotating respectively which marks the start position of a text range which a comment is annotating should have a run attribute, named (e.g.) "Note" whose value is the accessible object representing this comment.
+
# [SOLVED in cws sw33a11y01] Accessible name "Actions" and accessible description "Activate this button to open a list of actions which cane be performed on this comment and other comments" for the accessibility object which represents the push button. <span style="background: green; color: white;">'''(ES: FIXED)'''</span>
# For a comment which annotates a text range a non-showing accessible object with OOo's accessible role "COMMENT_END" shall exist. Its parent shall be the paragraph containing the end position of the text range the comment is annotating.
+
# [SOLVED in cws sw33a11y01] Tool tip for push button containing its accessible description. <span style="background: green; color: white;">'''(ES: FIXED)'''</span>
# The corresponding accessible objects of accessible role "COMMENT" and "COMMENT_END" shall be in relation with relation type "MEMBER_OF".
+
# [REMOVED] The special character in the paragraph's text which marks the text position which a comment is annotating respectively which marks the start position of a text range which a comment is annotating should have a run attribute, named "Comment" whose value is the accessible object representing this comment. This requirement has been removed, because the value of a run attribute at ATK is only a string. Thus, a reference to an corresponding <AtkObject> instance can not be transfered.
# Comments of visible paragraphs which are not visible in the user interface shall exist as accessible objects. Its corresponding showing and/or visible states shall not be set.
+
# [POSTPONED until comments on text ranges have been implemented] For a comment which annotates a text range a non-showing accessible object with OOo's accessible role "COMMENT_END" shall exist. Its parent shall be the paragraph containing the end position of the text range the comment is annotating.
 +
#* In OOo's ATK bridge this accessible role should be mapped to ATK role ATK_ROLE_UNKNOWN
 +
#* [POSTPONED until OOo's base line for Gnome contains ATK 1.12] New AtkAttribute { "xml_roles", "note_end" }. The AtkAttribute is provided via ATK-method <AtkObject::atk_object_get_attributes(..)>
 +
# [POSTPONED until comments on text ranges have been implemented] The corresponding accessible objects of accessible role "COMMENT" and "COMMENT_END" shall be in relation with relation type "MEMBER_OF".
 +
# [ADJUSTED] Comments of visible paragraphs which are not inside the visible area of the document shall exist as accessible objects. Its SHOWING and the VISIBLE states will correspond to OOo's definition of these states - see http://api.openoffice.org/docs/common/ref/com/sun/star/accessibility/AccessibleStateType.html. <br><div style="background: tomato; color: white; width: 500px;">'''(ES: Not as described.<br>Test 1: a part of the Paragraph containing the comment is displayed on the screen but the comment (and anchor) are not in in the document view -> Accerciser: the comment is present in the hierarchy and is SHOWING AND VISIBLE -> BUG.<br>Test 2: only the comment is displayed on screen and its paragraph not: Accerciser: the comment is NOT present in the hierarchy -> BUG)'''</div>
 
# [SOLVED] The user should be able to quickly add or delete a comment.
 
# [SOLVED] The user should be able to quickly add or delete a comment.
 
#* Adding is already possible via <Ctrl-Alt-N>
 
#* Adding is already possible via <Ctrl-Alt-N>
 
#* Deletion is already possible via deletion of the special character in the paragraph's text.
 
#* Deletion is already possible via deletion of the special character in the paragraph's text.
# The user should be able to quickly navigate between the document content and the comments.
+
# [SOLVED] The user should be able to quickly navigate between the document content and the comments.
#* [OPEN: It is needed to define the navigation keys.]
+
#* When the cursor is on the special character of the comment the user can navigate into the comment via Ctrl-Alt-N. via ESC the user navigates from the comment to the document content.
# When in the document content area and the user sees a comment is present, navigating to the comment should automatically make the comment become visible. Any associated comment for the current caret position should be visible and it should be obvious which comment it is.
+
# [REMOVED] When in the document content area and the user sees a comment is present, navigating to the comment should automatically make the comment become visible. Any associated comment for the current caret position should be visible and it should be obvious which comment it is. This requirement has been removed, because it can cause unintended changes of the document's visible area. When the comment which is associated at the current cursor position is made visible the cursor position can then be out of sight. I (OD) think that such a change in the document's visible area does not make sense.
#* When the cursor is moved to the special character in the paragraph's text the visual representation of the "anchor line" changes - from dashed to solid - the comment window also gets a shadow.
+
# [SOLVED] When the cursor is moved to the special character in the paragraph's text the visual representation of the "anchor line" changes - from dashed to solid - the comment window also gets a shadow.<span style="background: green; color: white;">'''(ES: FIXED)'''</span>
#* [OPEN: It is needed to define how this change in the visual representation of the comment is reflected for accessibility tools.]
+
#* [POSTPONED]: It is needed to define how this change in the visual representation of the comment is reflected for accessibility tools.]
# The user should be able to quickly jump from one comment to the next (e.g., let them quickly scan what other people had to say about the document).
+
# [SOLVED] The user should be able to quickly jump from one comment to the next (e.g., let them quickly scan what other people had to say about the document).
#* [OPEN: Is is needed to define the navigation keys.]
+
#* The navigation keys are Ctrl-Alt-PageUp/PageDown.<span style="background: orange; color: white;">'''(ES: This must be documented -> Please task to UFI)'''</span>
# The user should be able to easily navigate within a comment -- go from field to field, select/copy/edit text, etc.
+
# [SOLVED in cws sw33a11y01] The user should be able to easily navigate within a comment -- go from field to field, select/copy/edit text, etc.
#* There are currently only two window controls which are of interest for this requirement - the window control which contains the comment content and the push button. To navigate from the comment content to the push button <Ctrl-Tab> shall work. To navigate from the push-button to the comment content <Tab> shall work. Inside the comment content normal text navigation shall work.
+
#* There are currently only two window controls which are of interest for this requirement - the window control which contains the comment content and the push button.<br> To navigate from the comment content to the push button: <Ctrl-(Shift)-Tab>.<br> To navigate from the push-button to the comment content <(Ctrl-(Shift-))Tab>.<br> Inside the comment content normal text navigation.<br><span style="background: green; color: white;">'''(ES: FIXED)'''</span>

Latest revision as of 11:51, 19 July 2010

Writer Icon.png

Writer Project

Please view the guidelines
before contributing.

Popular Subcategories:

Extension:DynamicPageList (DPL), version 2.3.0 : Warning: No results.

Internal Documentation:

Extension:DynamicPageList (DPL), version 2.3.0 : Warning: No results.

API Documentation:

Ongoing Efforts:

Extension:DynamicPageList (DPL), version 2.3.0 : Warning: No results.

Sw.OpenOffice.org

Home for the accessibility work in the Writer.

Issue 88070 - Expose comments at the accessibility API for accessibility tools

Details about the issue 88070 - link to the intrinsic IssueZilla issue - in order to expose the comments of a Writer document.

The comments of a Writer document are also known as notes (prior to OOo 3.2) or annotations (OpenDocument file format specification, version 1.0, 1.1 and 1.2).

Refined proposal

After a deeper look at the current presentation of a comment in the user interface (used windows and controls), prototyping some stuff and considering joaniediggs' (mailto:joaniediggs@openoffice.org) proposal and williewalker's (mailto:williewalker@openoffice.org) input the following document hierarchy results as a refined proposal of a document hierarchy seen by accessibility tool Accerciser for a comment:

-> ATK_ROLE_DOCUMENT_FRAME
-> ATK_ROLE_PARAGRAPH
-> ATK_ROLE_PARAGRAPH
-> ATK_ROLE_PARAGRAPH
-> ATK_ROLE_SCROLL_PANE
-> ATK_ROLE_PANEL
-> ATK_ROLE_PARAGRAPH ("Annotation")
-> ATK_ROLE_PARAGRAPH ("1st paragraph bold")
-> ATK_ROLE_PARAGRAPH ("2nd paragraph italic")
-> ATK_ROLE_PARAGRAPH ("3rd paragraph centered")
-> ATK_ROLE_TEXT ("Oliver-Rainer Wittmann")
-> ATK_ROLE_TEXT ("12/12/2008 15:01")
-> ATK_ROLE_PUSH_BUTTON
-> ATK_ROLE_PARAGRAPH
-> ATK_ROLE_PARAGRAPH
-> ATK_ROLE_UNKNOWN [exist when comment annotates text range; its a non-showing accessible object]
-> ATK_ROLE_PARAGRAPH

Requirements

Below is a list of requirements which are collected from the comments of the IssueZilla issue. Sometimes a refinement or a possible proposal for its solution is given:

  1. [SOLVED in cws sw33a11y01] Identification of the uppermost accessible object by OOo's accessible role "COMMENT". (ES: term "COMMENT" not found in Accerciser)
    • In OOo's ATK bridge this accessible role should be mapped to ATK role ATK_ROLE_SCROLL_PANE (ES: FIXED)
    • [POSTPONED until OOo's base line for Gnome contains at least ATK 1.12] New AtkAttribute { "xml_roles", "note" }. The AtkAttribute should be provided via ATK-method <AtkObject::atk_object_get_attributes(..)>
  2. [SOLVED in cws sw33a11y01] Accessible name "Author" for the accessible object representing the fixed text window control containing the author's name.(ES: FIXED)
  3. [SOLVED in cws sw33a11y01] Accessible name "Date" for the accessible object representing the fixed text window control containing comment's creation date.(ES: FIXED)
  4. [SOLVED in cws sw33a11y01] Accessible name "Actions" and accessible description "Activate this button to open a list of actions which cane be performed on this comment and other comments" for the accessibility object which represents the push button. (ES: FIXED)
  5. [SOLVED in cws sw33a11y01] Tool tip for push button containing its accessible description. (ES: FIXED)
  6. [REMOVED] The special character in the paragraph's text which marks the text position which a comment is annotating respectively which marks the start position of a text range which a comment is annotating should have a run attribute, named "Comment" whose value is the accessible object representing this comment. This requirement has been removed, because the value of a run attribute at ATK is only a string. Thus, a reference to an corresponding <AtkObject> instance can not be transfered.
  7. [POSTPONED until comments on text ranges have been implemented] For a comment which annotates a text range a non-showing accessible object with OOo's accessible role "COMMENT_END" shall exist. Its parent shall be the paragraph containing the end position of the text range the comment is annotating.
    • In OOo's ATK bridge this accessible role should be mapped to ATK role ATK_ROLE_UNKNOWN
    • [POSTPONED until OOo's base line for Gnome contains ATK 1.12] New AtkAttribute { "xml_roles", "note_end" }. The AtkAttribute is provided via ATK-method <AtkObject::atk_object_get_attributes(..)>
  8. [POSTPONED until comments on text ranges have been implemented] The corresponding accessible objects of accessible role "COMMENT" and "COMMENT_END" shall be in relation with relation type "MEMBER_OF".
  9. [ADJUSTED] Comments of visible paragraphs which are not inside the visible area of the document shall exist as accessible objects. Its SHOWING and the VISIBLE states will correspond to OOo's definition of these states - see http://api.openoffice.org/docs/common/ref/com/sun/star/accessibility/AccessibleStateType.html.
    (ES: Not as described.
    Test 1: a part of the Paragraph containing the comment is displayed on the screen but the comment (and anchor) are not in in the document view -> Accerciser: the comment is present in the hierarchy and is SHOWING AND VISIBLE -> BUG.
    Test 2: only the comment is displayed on screen and its paragraph not: Accerciser: the comment is NOT present in the hierarchy -> BUG)
  10. [SOLVED] The user should be able to quickly add or delete a comment.
    • Adding is already possible via <Ctrl-Alt-N>
    • Deletion is already possible via deletion of the special character in the paragraph's text.
  11. [SOLVED] The user should be able to quickly navigate between the document content and the comments.
    • When the cursor is on the special character of the comment the user can navigate into the comment via Ctrl-Alt-N. via ESC the user navigates from the comment to the document content.
  12. [REMOVED] When in the document content area and the user sees a comment is present, navigating to the comment should automatically make the comment become visible. Any associated comment for the current caret position should be visible and it should be obvious which comment it is. This requirement has been removed, because it can cause unintended changes of the document's visible area. When the comment which is associated at the current cursor position is made visible the cursor position can then be out of sight. I (OD) think that such a change in the document's visible area does not make sense.
  13. [SOLVED] When the cursor is moved to the special character in the paragraph's text the visual representation of the "anchor line" changes - from dashed to solid - the comment window also gets a shadow.(ES: FIXED)
    • [POSTPONED]: It is needed to define how this change in the visual representation of the comment is reflected for accessibility tools.]
  14. [SOLVED] The user should be able to quickly jump from one comment to the next (e.g., let them quickly scan what other people had to say about the document).
    • The navigation keys are Ctrl-Alt-PageUp/PageDown.(ES: This must be documented -> Please task to UFI)
  15. [SOLVED in cws sw33a11y01] The user should be able to easily navigate within a comment -- go from field to field, select/copy/edit text, etc.
    • There are currently only two window controls which are of interest for this requirement - the window control which contains the comment content and the push button.
      To navigate from the comment content to the push button: <Ctrl-(Shift)-Tab>.
      To navigate from the push-button to the comment content <(Ctrl-(Shift-))Tab>.
      Inside the comment content normal text navigation.
      (ES: FIXED)
Personal tools