Accessible.xml: Document the GetRole method

Copied descriptions from AtspiRole, and fixed some inconsistencies in those.

1 files changed, 470 insertions, 0 deletions

diff --git a/xml/Accessible.xml b/xml/Accessible.xml
index c8fd8e0f..520a8ff8 100644
--- a/xml/Accessible.xml
+++ b/xml/Accessible.xml
@@ -247,6 +247,476 @@
       <annotation name="org.qtproject.QtDBus.QtTypeName.Out0" value="QSpiRelationArray"/>
     </method>
 
+    <!--
+        GetRole:
+
+        Gets the accessible role that the current object represents.  Roles make it
+        possible for various UI toolkits to expose their controls to assistive
+        technologies (ATs) with a standard interface, regardless of toolkit.  For example,
+        a widget that acts like a conventional push button (appears unpressed; presses
+        when acted upon; invokes a certain action when pressed) can expose an
+        ATSPI_ROLE_PUSH_BUTTON role.
+
+        Role values - these are the enum values from AtspiRole in atspi-constants.h:
+
+        0 - ATSPI_ROLE_INVALID: A role indicating an error condition, such as
+            uninitialized Role data.
+
+        1 - ATSPI_ROLE_ACCELERATOR_LABEL: Object is a label indicating the keyboard
+            accelerators for the parent.
+
+        2 - ATSPI_ROLE_ALERT: Object is used to alert the user about something.
+
+        3 - ATSPI_ROLE_ANIMATION: Object contains a dynamic or moving image of some
+            kind.
+
+        4 - ATSPI_ROLE_ARROW: Object is a 2D directional indicator.
+
+        5 - ATSPI_ROLE_CALENDAR: Object contains one or more dates, usually arranged
+            into a 2D list.
+
+        6 - ATSPI_ROLE_CANVAS: Object that can be drawn into and is used to trap
+            events.
+
+        7 - ATSPI_ROLE_CHECK_BOX: A choice that can be checked or unchecked and
+            provides a separate indicator for the current state.
+
+        8 - ATSPI_ROLE_CHECK_MENU_ITEM: A menu item that behaves like a check box. See
+            ATSPI_ROLE_CHECK_BOX.
+
+        9 - ATSPI_ROLE_COLOR_CHOOSER: A specialized dialog that lets the user choose a
+            color.
+
+        10 - ATSPI_ROLE_COLUMN_HEADER: The header for a column of data.
+
+        11 - ATSPI_ROLE_COMBO_BOX: A list of choices the user can select from.
+
+        12 - ATSPI_ROLE_DATE_EDITOR: An object which allows entry of a date.
+
+        13 - ATSPI_ROLE_DESKTOP_ICON: An inconifed internal frame within a DESKTOP_PANE.
+
+        14 - ATSPI_ROLE_DESKTOP_FRAME: A pane that supports internal frames and
+             iconified versions of those internal frames.
+
+        15 - ATSPI_ROLE_DIAL: An object that allows a value to be changed via rotating a
+             visual element, or which displays a value via such a rotating element.
+
+        16 - ATSPI_ROLE_DIALOG: A top level window with title bar and a border.
+
+        17 - ATSPI_ROLE_DIRECTORY_PANE: A pane that allows the user to navigate through
+             and select the contents of a directory.
+
+        18 - ATSPI_ROLE_DRAWING_AREA: An object used for drawing custom user interface
+             elements.
+
+        19 - ATSPI_ROLE_FILE_CHOOSER: A specialized dialog that displays the files in
+             the directory and lets the user select a file, browse a different
+             directory, or specify a filename.
+
+        20 - ATSPI_ROLE_FILLER: A object that fills up space in a user interface.
+
+        21 - ATSPI_ROLE_FOCUS_TRAVERSABLE: Don't use, reserved for future use.
+
+        22 - ATSPI_ROLE_FONT_CHOOSER: Allows selection of a display font.
+
+        23 - ATSPI_ROLE_FRAME: A top level window with a title bar, border, menubar,
+             etc.
+
+        24 - ATSPI_ROLE_GLASS_PANE: A pane that is guaranteed to be painted on top of
+             all panes beneath it.
+
+        25 - ATSPI_ROLE_HTML_CONTAINER: A document container for HTML, whose children
+             represent the document content.
+
+        26 - ATSPI_ROLE_ICON: A small fixed size picture, typically used to decorate
+             components.
+
+        27 - ATSPI_ROLE_IMAGE: An image, typically static.
+
+        28 - ATSPI_ROLE_INTERNAL_FRAME: A frame-like object that is clipped by a desktop
+             pane.
+
+        29 - ATSPI_ROLE_LABEL: An object used to present an icon or short string in an
+             interface.
+
+        30 - ATSPI_ROLE_LAYERED_PANE: A specialized pane that allows its children to be
+             drawn in layers, providing a form of stacking order.
+
+        31 - ATSPI_ROLE_LIST: An object that presents a list of objects to the user and
+             allows the user to select one or more of them.
+
+        32 - ATSPI_ROLE_LIST_ITEM: An object that represents an element of a list.
+
+        33 - ATSPI_ROLE_MENU: An object usually found inside a menu bar that contains a
+             list of actions the user can choose from.
+
+        34 - ATSPI_ROLE_MENU_BAR: An object usually drawn at the top of the primary
+             dialog box of an application that contains a list of menus the user can
+             choose from.
+
+        35 - ATSPI_ROLE_MENU_ITEM: An object usually contained in a menu that presents
+             an action the user can choose.
+
+        36 - ATSPI_ROLE_OPTION_PANE: A specialized pane whose primary use is inside a
+             dialog.
+
+        37 - ATSPI_ROLE_PAGE_TAB: An object that is a child of a page tab list.
+
+        38 - ATSPI_ROLE_PAGE_TAB_LIST: An object that presents a series of panels (or
+             page tabs), one at a time,through some mechanism provided by the
+             object.
+
+        39 - ATSPI_ROLE_PANEL: A generic container that is often used to group objects.
+
+        40 - ATSPI_ROLE_PASSWORD_TEXT: A text object uses for passwords, or other places
+             where the text content is not shown visibly to the user.
+
+        41 - ATSPI_ROLE_POPUP_MENU: A temporary window that is usually used to offer the
+             user a list of choices, and then hides when the user selects one of those
+             choices.
+
+        42 - ATSPI_ROLE_PROGRESS_BAR: An object used to indicate how much of a task has
+             been completed.
+
+        43 - ATSPI_ROLE_PUSH_BUTTON: An object the user can manipulate to tell the
+             application to do something.
+
+        44 - ATSPI_ROLE_RADIO_BUTTON: A specialized check box that will cause other
+             radio buttons in the same group to become unchecked when this one is
+             checked.
+
+        45 - ATSPI_ROLE_RADIO_MENU_ITEM: Object is both a menu item and a "radio button".
+             See ATSPI_ROLE_RADIO_BUTTON.
+
+        46 - ATSPI_ROLE_ROOT_PANE: A specialized pane that has a glass pane and a
+             layered pane as its children.
+
+        47 - ATSPI_ROLE_ROW_HEADER: The header for a row of data.
+
+        48 - ATSPI_ROLE_SCROLL_BAR: An object usually used to allow a user to
+             incrementally view a large amount of data by moving the bounds of a
+             viewport along a one-dimensional axis.
+
+        49 - ATSPI_ROLE_SCROLL_PANE: An object that allows a user to incrementally view
+             a large amount of information. Scroll pane objects are usually
+             accompanied by ATSPI_ROLE_SCROLL_BAR controllers, on which the
+             ATSPI_RELATION_CONTROLLER_FOR and ATSPI_RELATION_CONTROLLED_BY
+             reciprocal relations are set. See the GetRelationSet method.
+
+        50 - ATSPI_ROLE_SEPARATOR: An object usually contained in a menu to provide a
+             visible and logical separation of the contents in a menu.
+
+        51 - ATSPI_ROLE_SLIDER: An object that allows the user to select from a bounded range.
+             Unlike ATSPI_ROLE_SCROLL_BAR, ATSPI_ROLE_SLIDER objects need not control
+             'viewport'-like objects.
+
+        52 - ATSPI_ROLE_SPIN_BUTTON: An object which allows one of a set of choices to
+             be selected, and which displays the current choice.
+
+        53 - ATSPI_ROLE_SPLIT_PANE: A specialized panel that presents two other panels
+             at the same time.
+
+        54 - ATSPI_ROLE_STATUS_BAR: Object displays non-quantitative status information
+             (c.f. ATSPI_ROLE_PROGRESS_BAR)
+
+        55 - ATSPI_ROLE_TABLE: An object used to repesent information in terms of rows
+             and columns.
+
+        56 - ATSPI_ROLE_TABLE_CELL: A 'cell' or discrete child within a Table. Note:
+             Table cells need not have ATSPI_ROLE_TABLE_CELL, other
+             role values are valid as well.
+
+        57 - ATSPI_ROLE_TABLE_COLUMN_HEADER: An object which labels a particular column
+             in a Table interface interface.
+
+        58 - ATSPI_ROLE_TABLE_ROW_HEADER: An object which labels a particular row in a
+             Table interface. Table rows and columns may also be labelled via the
+             ATSPI_RELATION_LABEL_FOR/ATSPI_RELATION_LABELLED_BY relationships; see
+             the GetRelationSet method.
+
+        59 - ATSPI_ROLE_TEAROFF_MENU_ITEM: Object allows menu to be removed from menubar
+             and shown in its own window.
+
+        60 - ATSPI_ROLE_TERMINAL: An object that emulates a terminal.
+
+        61 - ATSPI_ROLE_TEXT: An interactive widget that supports multiple lines of text
+             and optionally accepts user input, but whose purpose is not to solicit user
+             input. Thus ATSPI_ROLE_TEXT is appropriate for the text view in a plain text
+             editor but inappropriate for an input field in a dialog box or web form. For
+             widgets whose purpose is to solicit input from the user, see ATSPI_ROLE_ENTRY
+             and ATSPI_ROLE_PASSWORD_TEXT. For generic objects which display a brief amount
+             of textual information, see ATSPI_ROLE_STATIC.
+
+        62 - ATSPI_ROLE_TOGGLE_BUTTON: A specialized push button that can be checked or
+             unchecked, but does not procide a separate indicator for the current
+             state.
+
+        63 - ATSPI_ROLE_TOOL_BAR: A bar or palette usually composed of push buttons or
+             toggle buttons.
+
+        64 - ATSPI_ROLE_TOOL_TIP: An object that provides information about another
+             object.
+
+        65 - ATSPI_ROLE_TREE: An object used to repsent hierarchical information to the
+             user.
+
+        66 - ATSPI_ROLE_TREE_TABLE: An object that presents both tabular and
+             hierarchical info to the user.
+
+        67 - ATSPI_ROLE_UNKNOWN: The object contains some accessible information,
+             but its role is not known.
+
+        68 - ATSPI_ROLE_VIEWPORT: An object usually used in a scroll pane, or to
+             otherwise clip a larger object or content renderer to a specific
+             onscreen viewport.
+
+        69 - ATSPI_ROLE_WINDOW: A top level window with no title or border.
+
+        70 - ATSPI_ROLE_EXTENDED: means that the role for this item is known, but not
+             included in the core enumeration. Deprecated since 2.24.
+
+        71 - ATSPI_ROLE_HEADER: An object that serves as a document header.
+
+        72 - ATSPI_ROLE_FOOTER: An object that serves as a document footer.
+
+        73 - ATSPI_ROLE_PARAGRAPH: An object which is contains a single paragraph of
+             text content. See also ATSPI_ROLE_TEXT.
+
+        74 - ATSPI_ROLE_RULER: An object which describes margins and tab stops, etc.
+             for text objects which it controls (should have
+             ATSPI_RELATION_CONTROLLER_FOR relation to such).
+
+        75 - ATSPI_ROLE_APPLICATION: An object corresponding to the toplevel accessible
+             of an application, which may contain ATSPI_ROLE_FRAME objects or other
+             accessible objects. Children of objects with the ATSPI_ROLE_DESKTOP_FRAME role
+             are generally ATSPI_ROLE_APPLICATION objects.
+
+        76 - ATSPI_ROLE_AUTOCOMPLETE: The object is a dialog or list containing items
+             for insertion into an entry widget, for instance a list of words for
+             completion of a text entry.
+
+        77 - ATSPI_ROLE_EDITBAR: The object is an editable text object in a toolbar.
+
+        78 - ATSPI_ROLE_EMBEDDED: The object is an embedded component container.  This
+             role is a "grouping" hint that the contained objects share a context
+             which is different from the container in which this accessible is
+             embedded. In particular, it is used for some kinds of document embedding,
+             and for embedding of out-of-process component, "panel applets", etc.
+
+        79 - ATSPI_ROLE_ENTRY: The object is a component whose textual content may be
+             entered or modified by the user, provided ATSPI_STATE_EDITABLE is present.
+             A readonly ATSPI_ROLE_ENTRY object (i.e. where ATSPI_STATE_EDITABLE is
+             not present) implies a read-only 'text field' in a form, as opposed to a
+             title, label, or caption.
+
+        80 - ATSPI_ROLE_CHART: The object is a graphical depiction of quantitative data.
+             It may contain multiple subelements whose attributes and/or description
+             may be queried to obtain both the  quantitative data and information about
+             how the data is being presented. The ATSPI_LABELLED_BY relation is
+             particularly important in interpreting objects of this type, as is the
+             accessible description property. See ATSPI_ROLE_CAPTION.
+
+        81 - ATSPI_ROLE_CAPTION: The object contains descriptive information, usually
+             textual, about another user interface element such as a table, chart, or
+             image.
+
+        82 - ATSPI_ROLE_DOCUMENT_FRAME: The object is a visual frame or container which
+             contains a view of document content.  Document frames may occur within
+             another Document instance, in which case the second document may be
+             said to be embedded in the containing instance.  HTML frames are often
+             ATSPI_ROLE_DOCUMENT_FRAME:  Either this object, or a singleton descendant,
+             should implement the org.a11y.atspi.Document interface.
+
+        83 - ATSPI_ROLE_HEADING: The object serves as a heading for content which
+             follows it in a document. The 'heading level' of the heading, if
+             availabe,  may be obtained by       querying the object's attributes.
+
+        84 - ATSPI_ROLE_PAGE: The object is a containing instance which encapsulates a
+             page of information. ATSPI_ROLE_PAGE is used in documents and content which
+             support a paginated navigation model.
+
+        85 - ATSPI_ROLE_SECTION: The object is a containing instance of document content
+             which constitutes a particular 'logical' section of the document.  The
+             type of content within a section, and the nature of the section division
+             itself, may be obtained by querying the object's attributes.  Sections
+             may be nested.
+
+        86 - ATSPI_ROLE_REDUNDANT_OBJECT: The object is redundant with another object in
+             the hierarchy, and is exposed for purely technical reasons.  Objects of
+             this role should be ignored by clients, if they are encountered at all.
+
+        87 - ATSPI_ROLE_FORM: The object is a containing instance of document content
+             which has within it components with which the user can interact in order
+             to input information; i.e. the object is a container for pushbuttons,
+             comboboxes, text input fields, and other 'GUI' components. ATSPI_ROLE_FORM
+             should not, in general, be used for toplevel GUI containers or dialogs,
+             but should be reserved for 'GUI' containers which occur within document
+             content, for instance within Web documents, presentations, or text
+             documents.  Unlike other GUI containers and dialogs which occur inside
+             application instances, ATSPI_ROLE_FORM containers' components are
+             associated with the current document, rather than the current foreground
+             application or viewer instance.
+
+        88 - ATSPI_ROLE_LINK: The object is a hypertext anchor, i.e. a "link" in a
+             hypertext document.  Such objects are distinct from 'inline' content
+             which may also use the Hypertext/Hyperlink interfaces to indicate
+             the range/location within a text object where an inline or embedded object
+             lies.
+
+        89 - ATSPI_ROLE_INPUT_METHOD_WINDOW: The object is a window or similar viewport
+             which is used to allow composition or input of a 'complex character',
+             in other words it is an "input method window".
+
+        90 - ATSPI_ROLE_TABLE_ROW: A row in a table.
+
+        91 - ATSPI_ROLE_TREE_ITEM: An object that represents an element of a tree.
+
+        92 - ATSPI_ROLE_DOCUMENT_SPREADSHEET: A document frame which contains a
+             spreadsheet.
+
+        93 - ATSPI_ROLE_DOCUMENT_PRESENTATION: A document frame which contains a
+             presentation or slide content.
+
+        94 - ATSPI_ROLE_DOCUMENT_TEXT: A document frame which contains textual content,
+             such as found in a word processing application.
+
+        95 - ATSPI_ROLE_DOCUMENT_WEB: A document frame which contains HTML or other
+             markup suitable for display in a web browser.
+
+        96 - ATSPI_ROLE_DOCUMENT_EMAIL: A document frame which contains email content
+             to be displayed or composed either in plain text or HTML.
+
+        97 - ATSPI_ROLE_COMMENT: An object found within a document and designed to
+             present a comment, note, or other annotation. In some cases, this object
+             might not be visible until activated.
+
+        98 - ATSPI_ROLE_LIST_BOX: A non-collapsible list of choices the user can select from.
+
+        99 - ATSPI_ROLE_GROUPING: A group of related widgets. This group typically has a label.
+
+        100 - ATSPI_ROLE_IMAGE_MAP: An image map object. Usually a graphic with multiple
+              hotspots, where each hotspot can be activated resulting in the loading of
+              another document or section of a document.
+
+        101 - ATSPI_ROLE_NOTIFICATION: A transitory object designed to present a
+              message to the user, typically at the desktop level rather than inside a
+              particular application.
+
+        102 - ATSPI_ROLE_INFO_BAR: An object designed to present a message to the user
+              within an existing window.
+
+        103 - ATSPI_ROLE_LEVEL_BAR: A bar that serves as a level indicator to, for
+              instance, show the strength of a password or the state of a battery. Since: 2.8
+
+        104 - ATSPI_ROLE_TITLE_BAR: A bar that serves as the title of a window or a
+              dialog. Since: 2.12
+
+        105 - ATSPI_ROLE_BLOCK_QUOTE: An object which contains a text section
+              that is quoted from another source.  Since: 2.12
+
+        106 - ATSPI_ROLE_AUDIO: An object which represents an audio
+              element. Since: 2.12
+
+        107 - ATSPI_ROLE_VIDEO: An object which represents a video
+              element. Since: 2.12
+
+        108 - ATSPI_ROLE_DEFINITION: A definition of a term or concept. Since: 2.12
+
+        109 - ATSPI_ROLE_ARTICLE: A section of a page that consists of a
+              composition that forms an independent part of a document, page, or
+              site. Examples: A blog entry, a news story, a forum post. Since: 2.12
+
+        110 - ATSPI_ROLE_LANDMARK: A region of a web page intended as a
+              navigational landmark. This is designed to allow Assistive
+              Technologies to provide quick navigation among key regions within a
+              document. Since: 2.12
+
+        111 - ATSPI_ROLE_LOG: A text widget or container holding log content, such
+              as chat history and error logs. In this role there is a
+              relationship between the arrival of new items in the log and the
+              reading order. The log contains a meaningful sequence and new
+              information is added only to the end of the log, not at arbitrary
+              points. Since: 2.12
+
+        112 - ATSPI_ROLE_MARQUEE: A container where non-essential information
+              changes frequently. Common usages of marquee include stock tickers
+              and ad banners. The primary difference between a marquee and a log
+              is that logs usually have a meaningful order or sequence of
+              important content changes. Since: 2.12
+
+        113 - ATSPI_ROLE_MATH: A text widget or container that holds a mathematical
+              expression. Since: 2.12
+
+        114 - ATSPI_ROLE_RATING: A widget whose purpose is to display a rating,
+              such as the number of stars associated with a song in a media
+              player. Objects of this role should also implement
+              the Value interface. Since: 2.12
+
+        115 - ATSPI_ROLE_TIMER: An object containing a numerical counter which
+              indicates an amount of elapsed time from a start point, or the time
+              remaining until an end point. Since: 2.12
+
+        116 - ATSPI_ROLE_STATIC: A generic non-container object whose purpose is to display
+              a brief amount of information to the user and whose role is known by the
+              implementor but lacks semantic value for the user. Examples in which
+              ATSPI_ROLE_STATIC is appropriate include the message displayed in a message
+              box and an image used as an alternative means to display text.
+              ATSPI_ROLE_STATIC should not be applied to widgets which are traditionally
+              interactive, objects which display a significant amount of content, or any
+              object which has an accessible relation pointing to another object. The
+              displayed information, as a general rule, should be exposed through the
+              accessible name of the object. For labels which describe another widget, see
+              ATSPI_ROLE_LABEL. For text views, see ATSPI_ROLE_TEXT. For generic
+              containers, see ATSPI_ROLE_PANEL. For objects whose role is not known by the
+              implementor, see ATSPI_ROLE_UNKNOWN. Since: 2.16.
+
+        117 - ATSPI_ROLE_MATH_FRACTION: An object that represents a mathematical fraction. Since: 2.16.
+
+        118 - ATSPI_ROLE_MATH_ROOT: An object that represents a mathematical expression
+              displayed with a radical. Since: 2.16.
+
+        119 - ATSPI_ROLE_SUBSCRIPT: An object that contains text that is displayed as a
+              subscript. Since: 2.16.
+
+        120 - ATSPI_ROLE_SUPERSCRIPT: An object that contains text that is displayed as a
+              superscript. Since: 2.16.
+
+        121 - ATSPI_ROLE_DESCRIPTION_LIST: An object that represents a list of term-value
+              groups. A term-value group represents an individual description and consist
+              of one or more names (ATSPI_ROLE_DESCRIPTION_TERM) followed by one or more
+              values (ATSPI_ROLE_DESCRIPTION_VALUE). For each list, there should not be
+              more than one group with the same term name. Since: 2.26.
+
+        122 - ATSPI_ROLE_DESCRIPTION_TERM: An object that represents a term or phrase
+              with a corresponding definition. Since: 2.26.
+
+        123 - ATSPI_ROLE_DESCRIPTION_VALUE: An object that represents the description,
+              definition, or value of a term. Since: 2.26.
+
+        124 - ATSPI_ROLE_FOOTNOTE: An object that contains the text of a footnote. Since: 2.26.
+
+        125 - ATSPI_ROLE_CONTENT_DELETION: Content previously deleted or proposed to be
+              deleted, e.g. in revision history or a content view providing suggestions
+              from reviewers. Since: 2.34.
+
+        126 - ATSPI_ROLE_CONTENT_INSERTION: Content previously inserted or proposed to be
+              inserted, e.g. in revision history or a content view providing suggestions
+              from reviewers. Since: 2.34.
+
+        127 - ATSPI_ROLE_MARK: A run of content that is marked or highlighted, such as for
+              reference purposes, or to call it out as having a special purpose. If the
+              marked content has an associated section in the document elaborating on the
+              reason for the mark, then an ATSPI_RELATION_DETAILS relation should be used on the mark
+              to point to that associated section. In addition, the reciprocal relation
+              ATSPI_RELATION_DETAILS_FOR should be used on the associated content section
+              to point back to the mark. See the GetRelationSet method. Since: 2.36.
+
+        128 - ATSPI_ROLE_SUGGESTION: A container for content that is called out as a
+              proposed change from the current version of the document, such as by a reviewer of
+              the content. An object with this role should include children with
+              ATSPI_ROLE_CONTENT_DELETION and/or ATSPI_ROLE_CONTENT_INSERTION, in any order, to
+              indicate what the actual change is. Since: 2.36
+    -->
     <method name="GetRole">
       <arg direction="out" type="u"/>
     </method>