Information technology — Interoperability with assistive technology (AT) — Part 3: IAccessible2 accessibility application programming interface (API)

ISO/IEC TR 13066:2012 provides an overview to the structure and terminology of the IAccessible2 accessibility API. It provides: a description of the overall architecture and terminology of the API; further introductory explanations regarding the content and use of the API beyond those found in Annex A of ISO/IEC 13066-1; an overview of the main properties, including: of user interface elements, of how to get and set focus, of communication mechanisms in the API; a discussion of design considerations for the API (e.g. pointers to external sources of information on accessibility guidance related to using the API); information on extending the API (and where this is appropriate); an introduction to the programming interface of the API (including pointers to external sources of information). It provides this information as an introduction to the IAccessible2 API to assist: IT system level developers who create custom controls and/or interface to them; AT developers involved in programming "hardware to software" and "software to software" interactions.

Technologies de l'information — Interopérabilité avec les technologies d'assistance — Partie 3: Interface de programmation d'applications (API) d'accessibilité IAccessible2

General Information

Status
Published
Publication Date
06-Sep-2012
Current Stage
9093 - International Standard confirmed
Start Date
28-Jul-2017
Completion Date
28-Jul-2017
Ref Project

Buy Standard

Technical report
ISO/IEC TR 13066-3:2012 - Information technology -- Interoperability with assistive technology (AT)
English language
22 pages
sale 15% off
Preview
sale 15% off
Preview

Standards Content (sample)

TECHNICAL ISO/IEC
REPORT TR
13066-3
First edition
2012-09-15
Information technology — Interoperability
with Assistive Technology (AT) —
Part 3:
IAccessible2 accessibility application
programming interface (API)
Technologies de l'information — Interopérabilité avec les technologies
d'assistance —
Partie 3: Interface de programmation d'applications (API) d'accessibilité
IAccessible2
Reference number
ISO/IEC TR 13066-3:2012(E)
ISO/IEC 2012
---------------------- Page: 1 ----------------------
ISO/IEC TR 13066-3:2012(E)
COPYRIGHT PROTECTED DOCUMENT
© ISO/IEC 2012

All rights reserved. Unless otherwise specified, no part of this publication may be reproduced or utilized in any form or by any means,

electronic or mechanical, including photocopying and microfilm, without permission in writing from either ISO at the address below or

ISO's member body in the country of the requester.
ISO copyright office
Case postale 56  CH-1211 Geneva 20
Tel. + 41 22 749 01 11
Fax + 41 22 749 09 47
E-mail copyright@iso.org
Web www.iso.org
Published in Switzerland
ii © ISO/IEC 2012 – All rights reserved
---------------------- Page: 2 ----------------------
ISO/IEC TR 13066-3:2012(E)
Contents Page

Foreword ............................................................................................................................................................. v

Introduction ........................................................................................................................................................ vi

1  Scope ...................................................................................................................................................... 1

2  Terms and definitions ........................................................................................................................... 1

3  General Description .............................................................................................................................. 5

3.1  General Description .............................................................................................................................. 5

3.2  Architecture ........................................................................................................................................... 5

4  Using the API ......................................................................................................................................... 7

4.1  Overview ................................................................................................................................................. 7

4.2  User Interface elements ........................................................................................................................ 7

4.3  Getting and setting focus ..................................................................................................................... 8

4.4  Communication Mechanisms ............................................................................................................... 8

4.5  Introduction to Programming interface ............................................................................................... 8

4.5.1  COM Interface ........................................................................................................................................ 8

5  Exposing User Interface Element Information ................................................................................... 8

5.1  Role, state(s), boundary, name, and description of the user interface element ............................. 9

5.2  Current value and any minimum or maximum values, if the user interface element

represents one of a range of values .................................................................................................... 9

5.3  Text contents, text attributes, and the boundary of text rendered to the screen ......................... 10

5.4  The relationship of the user interface element to other user interface elements ........................ 10

5.4.1  In a single data value, whether this user interface element is a label for another user

interface element or is labelled by another user interface element ............................................... 10

5.4.2  In a table, the row and column that it is in, including headers of the row and column if

present .................................................................................................................................................. 10

5.4.3  In a hierarchical relationship, any parent containing the user interface element, and any

children contained by the user interface element ........................................................................... 10

6  Exposing User Interface Element Actions ........................................................................................ 11

7  Keyboard Focus .................................................................................................................................. 11

8  Events ................................................................................................................................................... 11

8.1  changes in the user interface element value .................................................................................... 12

8.2  changes in the name of the user interface element ......................................................................... 12

8.3  changes in the description of the user interface element ............................................................... 12

8.4  changes in the boundary of the user interface element .................................................................. 12

8.5  changes in the hierarchy of the user interface element .................................................................. 12

9  Programmatic Modifications of States, Properties, Values, and Text ........................................... 12

10  Design Considerations ....................................................................................................................... 13

10.1  Using IA2 .............................................................................................................................................. 13

10.1.1  The IAccessible2Proxy.dll .................................................................................................................. 13

10.1.2  Using IAccessibleApplication to get Application’s name and version .......................................... 13

10.1.3  Discovering Interfaces and Services ................................................................................................. 13

10.1.4  Component – building block of widgets ........................................................................................... 14

10.1.5  Discovering actions on accessible objects ...................................................................................... 15

10.1.6  Working with images ........................................................................................................................... 16

10.1.7  Working with number values ............................................................................................................. 16

10.1.8  Working with tables ............................................................................................................................. 17

10.1.9  Working with text ................................................................................................................................. 18

10.1.10 Object relations ................................................................................................................................... 20

© ISO/IEC 2012 – All rights reserved iii
---------------------- Page: 3 ----------------------
ISO/IEC TR 13066-3:2012(E)

10.1.11 Cross reference with Atk interfaces ..................................................................................................21

11  Further Information..............................................................................................................................22

11.1.1  IAccessible2 Extensibility ...................................................................................................................22

iv © ISO/IEC 2012 – All rights reserved
---------------------- Page: 4 ----------------------
ISO/IEC TR 13066-3:2012(E)
Foreword

ISO (the International Organization for Standardization) and IEC (the International Electrotechnical

Commission) form the specialized system for worldwide standardization. National bodies that are members of

ISO or IEC participate in the development of International Standards through technical committees

established by the respective organization to deal with particular fields of technical activity. ISO and IEC

technical committees collaborate in fields of mutual interest. Other international organizations, governmental

and non-governmental, in liaison with ISO and IEC, also take part in the work. In the field of information

technology, ISO and IEC have established a joint technical committee, ISO/IEC JTC 1.

International Standards are drafted in accordance with the rules given in the ISO/IEC Directives, Part 2.

The main task of the joint technical committee is to prepare International Standards. Draft International

Standards adopted by the joint technical committee are circulated to national bodies for voting. Publication as

an International Standard requires approval by at least 75 % of the national bodies casting a vote.

In exceptional circumstances, the joint technical committee may propose the publication of a Technical

Report, when the joint technical committee has collected data of a different kind from that which is normally

published as an International Standard (“state of the art”, for example).

Attention is drawn to the possibility that some of the elements of this part of ISO/IEC 13066 may be the

subject of patent rights. ISO and IEC shall not be held responsible for identifying any or all such patent rights.

ISO/IEC TR 13066-3 was prepared by Joint Technical Committee ISO/IEC JTC 1, Information technology,

Subcommittee SC 35, User interfaces.

ISO/IEC 13066 consists of the following parts, under the general title Information technology —

Interoperability with assistive technology (AT):
 Part 1: Requirements and recommendations for interoperability

 Part 2: Windows accessibility application programming interface (API) [Technical Report]

 Part 3: IAccessible2 accessibility application programming interface (API)
© ISO/IEC 2012 – All rights reserved v
---------------------- Page: 5 ----------------------
ISO/IEC TR 13066-3:2012(E)
Introduction

Assistive technology (AT) is specialized information technology (IT) hardware or software that is added to or

incorporated within a system that increases accessibility for an individual. In other words, it is special purpose

IT that interoperates with another IT product enabling a person with a disability to use the IT product.

Interoperability involves the ability to add or replace AT to existing components of IT systems. Interoperability

between AT and IT is best facilitated via the use of standardized, public interfaces for all IT components.

This part of ISO/IEC 13066 describes the IAccessible2 API that can be used as a framework to support

software to software IT-AT interoperability on the Windows platform.
vi © ISO/IEC 2012 – All rights reserved
---------------------- Page: 6 ----------------------
TECHNICAL REPORT ISO/IEC TR 13066-3:2012(E)
Information technology — Interoperability with Assistive
Technology (AT) —
Part 3:
IAccessible2 accessibility application programming interface
(API)
1 Scope

This part of ISO/IEC 13066 provides an overview to the structure and terminology of the IAccessible2

accessibility API.
It provides:
 a description of the overall architecture and terminology of the API;

 further introductory explanations regarding the content and use of the API beyond those found in Annex A

of ISO/IEC 13066-1;
 an overview of the main properties, including:
 of user interface elements,
 of how to get and set focus,
 of communication mechanisms in the API;

 a discussion of design considerations for the API (e.g. pointers to external sources of information on

accessibility guidance related to using the API);
 information on extending the API (and where this is appropriate);

 an introduction to the programming interface of the API (including pointers to external sources of

information).

It provides this information as an introduction to the IAccessible2 API to assist:

 IT system level developers who create custom controls and/or interface to them;

 AT developers involved in programming "hardware to software" and "software to software" interactions.

2 Terms and definitions
For the purposes of this document, the following terms and definitions apply.
© ISO/IEC 2012 – All rights reserved 1
---------------------- Page: 7 ----------------------
ISO/IEC TR 13066-3:2012(E)
2.1
accessible object

part of user interface object that is accessible by Microsoft Active Accessibility

NOTE An accessible object is represented by a pair of the IAccessible interface and ChildId identifier.

2.2
application programming interface
API

collection of invocation methods and associated parameters used by one piece of software to request actions

from another piece of software
[ISO/IEC 18012-1:2004, definition 3.1.1]
2.3
application software
software that is specific to the solution of an application problem
[ISO/IEC 2382-1, definition 10.04.01]
EXAMPLE A spreadsheet program is application software.
2.4
assistive technology

hardware or software added to, or incorporated within, a system that increases accessibility for an individual

EXAMPLE Braille display, screen reader, screen magnification software and eye tracking device.

[ISO 9241-171, definition 3.5]

NOTE Within this part of ISO/IEC 13066, where assistive technology (and its abbreviation AT) is used, it is to be

considered as both singular and plural, without distinction. If it is to be used in the singular only, it will be preceded by the

article "an" (i.e. an assistive technology). If it is to be used in the plural only, it will be preceded by the adjective "multiple"

(i.e. multiple AT).
2.5
client
component that uses the services of another component

NOTE In this part of ISO/IEC 13066, client refers more specifically to a component that uses the services of either or

both Microsoft Active Accessibility and/or UI Automation to access, identify, or manipulate the UI elements of an

application.
2.6
Component Object Model
COM

object-oriented programming model that defines how objects interact within a single process or between

processes

NOTE In COM, clients have access to an object through interfaces implemented on the object.

2.7
compatibility

capability of a functional unit to meet the requirements of a specified interface without appreciable modification

[ISO/IEC 2382-1, definition 01.06.11]
2 © ISO/IEC 2012 – All rights reserved
---------------------- Page: 8 ----------------------
ISO/IEC TR 13066-3:2012(E)
2.8
function
defined objective or characteristic action of a system or component
[IEEE Std. 610.12-1990, unnumbered definition]
EXAMPLE A system has inventory control as its primary function.
2.9
information/communication technology
ICT

technology for gathering, storing, retrieving, processing, analysing and transmitting information

[ISO 9241-20, definition 3.4]
EXAMPLE A computer system is a type of ICT.2.13.
2.10
interface

shared boundary between two functional units, defined by various characteristics pertaining to the functions,

physical interconnections, signal exchanges, and other characteristics, as appropriate

[ISO/IEC 2382-1, definition 01.01.38]
2.11
interoperability

capability to communicate, execute programs, or transfer data among various functional units in a manner that

requires the user to have little or no knowledge of the unique characteristics of those units

[ISO/IEC 2382-1, definition 01.01.47]
2.12
Microsoft Active Accessibility

COM-based technology that improves the way accessibility aids work with applications running on Microsoft

Windows

NOTE It provides dynamic-link libraries (DLLs) that are incorporated into the operating system, as well as a COM

interface and application programming elements that provide reliable methods for exposing information about user

interface elements.
2.13
operating system

software that controls the execution of programs and that may provide services such as resource allocation,

scheduling, input-output control, and data management

NOTE Although operating systems are predominantly software, partial hardware implementations are possible.

[ISO/IEC 2382-1, definition 01.04.08]
2.14
servers

servers in Microsoft Active Accessibility are components (applications, dlls, etc.) that have UI and expose

information about the UI and/or allow it to be manipulated

NOTE The terminology ‘server’ in Microsoft Active Accessibility is a synonym of ‘providers’ in UI Automation.

2.15
service
functionality made available to a user electronically
© ISO/IEC 2012 – All rights reserved 3
---------------------- Page: 9 ----------------------
ISO/IEC TR 13066-3:2012(E)
[ISO/IEC 24752-1 URC, definition 4.27]

EXAMPLE Airline reservation service, currency translation services, weather forecasting, restaurant

recommendations, etc.
2.16
simple element

UI element that shares an IAccessible object with other peer elements

NOTE A simple element relies on the shared IAccessible object (typically its parent in the object hierarchy) to

expose its properties.
2.17
software

all or part of the programs, procedures, rules, and associated documentation of an information processing

system

NOTE Software is an intellectual creation that is independent of the medium on which it is recorded.

[ISO/IEC 2382-1, definition 01.01.08]
2.18
system software
platform software

application-independent software that supports the running of application software

[ISO/IEC 2382-1, definition 01.04.02]

EXAMPLE An operating system, a Web browser, or a programming environment (e.g. Java) can be used as a

platform for application software.
2.19
user interface
mechanisms by which a person interacts with a computer system

NOTE The user interface provides input mechanisms, allowing users to manipulate a system. It also provides output

mechanisms, allowing the system to produce the effects of the users’ manipulation.

2.20
user interface element
user interface object
entity of the user interface that is presented to the user by the software
[ISO 9241-171 definition 3.38]
NOTE 1 User interface elements may or may not be interactive.

NOTE 2 Both entities relevant to the task and entities of the user interface are regarded as user interface elements.

Different user interface element types are text, graphics and controls. A user interface element may be a representation or

an interaction mechanism for a task object (such as a letter, a sales order, electronic parts, or a wiring diagram) or a

system object (such as a printer, hard disk, or network connection). It may be possible for the user to directly manipulate

some of these user interface elements.

EXAMPLE 1 User interface elements in a graphical user interface include such things as basic objects (such as

window title bars, menu items, push buttons, image maps, and editable text fields) or containers (such as windows,

grouping boxes, menu bars, menus, groups of mutually-exclusive option buttons, and compound images that are made up

of several smaller images).

EXAMPLE 2 User interface elements in an audio user interface include such things as menus, menu items, messages,

and action prompts.

EXAMPLE 3 User interface elements in tactile interfaces include such things as tactile dots, tactile bars, surfaces,

knobs, and grips.
4 © ISO/IEC 2012 – All rights reserved
---------------------- Page: 10 ----------------------
ISO/IEC TR 13066-3:2012(E)
2.21
WinEvents

mechanism that allows servers and the Windows operating system to notify clients when an accessible object

changes
3 General Description
3.1 General Description

IAccessible2 was developed by IBM in 2006 to complement Microsoft's earlier work on the Microsoft Active

Accessibility (MSAA) API. MSAA provides accessibility services on the Windows® platform. The IAccessible2

set of interfaces allow application developers to leverage their investment in MSAA while also providing

assistive technologies (AT), such as screen readers, reliable access to user interface features not previously

supported by MSAA. ATs implementing only MSAA must use reverse engineering and heuristic techniques,

such as screen scraping, to provide access to features such as rich document editing functions and tables in

documents. While such AT implementations can work, they are customized for each application, expensive to

develop, frequently unreliable, and often must be reworked when new versions of the applications are

released. The additional function IAccessible2 provides over MSAA includes support for rich text, tables,

relationships between objects, self-describing actions, application-specific information, and extensible object

properties to support Web 2.0 applications.

A major requirement of many information technology (IT) vendors is the ability to efficiently create applications

for multiple platforms. IAccessible2 has therefore been harmonized with the UNIX accessibility APIs,

Accessibility Toolkit (ATK) and Assistive Technology Service Provider Interface (AT-SPI), to allow for efficient

multi-platform development. Adding IAccessible2 events and interfaces to MSAA yields application semantics

that are very similar on both Windows and UNIX.

These design principles guided the specification of the IAccessible2 interfaces which are based on the

difference between MSAA and the UNIX Accessibility Toolkit, described in ISO/IEC 13066-4. Application

vendors can incrementally add IAccessible2 interfaces as needed to their MSAA implementation providing

improved accessibility to their application. And Windows assistive technology vendors can keep much of their

MSAA design, only adding a check for these new interfaces before using their legacy heuristic code.

Note that IAccessible2 is the name used to refer to the “set” of interfaces and also a specific API within the set

of interfaces. In this part of ISO/IEC 13066 “IAccessible2” and “IAccessible2 interfaces” refers to the set of

interfaces and “IAccessible2 interface” refers to the specific API.
3.2 Architecture

Since IAccessible2 is an extension of MSAA, described in ISO/IEC 13066-2, its architecture matches that of

MSAA.

MSAA is based on the Windows Component Object Model (COM), which defines a common way for

applications and operating systems to communicate. Applications are considered MSAA servers because they

serve or provide information about their user interfaces (UI). Assistive technology products, such as screen

readers, are called MSAA clients because they consume and interact with application UI information.

The accessible object is the central interface of Microsoft Active Accessibility and is represented by an

IAccessible COM interface and an integer ChildId. MSAA clients use the interface to access, identify, and

manipulate a server’s UI and register to be notified of changes to the server UI through event notifications

known as WinEvents.

An accessible object can be of two types. A parent or container object is represented by a ChildID value of

CHILDID_SELF (or 0 ‘zero’). The children of a parent or container object are simple elements that share the

same IAccessible interface with their parent and are represented by a non-zero ChildID value (usually a

positive sequential number beginning with 1). Simple elements cannot have children of their own. Multiple

levels of accessible objects are used to represent UI elements that are composed of more than two levels of

hierarchy.
© ISO/IEC 2012 – All rights reserved 5
---------------------- Page: 11 ----------------------
ISO/IEC TR 13066-3:2012(E)

As stated in ISO/IEC 13066-2, the system component of the Microsoft Active Accessibility framework,

Oleacc.dll, aids in the communication between accessibility tools (clients) and applications (servers). The

Oleacc.dll provides an implementation of the Microsoft Active Accessibility API, the accessibility system

framework, and the proxy objects for the Windows Operating System standard controls. The

implementation of the Microsoft Accessibility API is an implementation of the IAccessible interface for

Windows Operating System controls. Additional implementations of IAccessible, external to Oleacc.dll, are

provided by applications running on the Windows Operating System. The code boundary indicates the

programmatic boundaries between applications that provide UI accessibility information and accessibility tools

that interact with the UI on behalf of users. The boundary can also be a process boundary when Microsoft

Active Accessibility clients have their own process.
* Also process boundary in case of out of process MSAA Clients
Figure 1

Windows application developers and assistive technology vendors are already familiar with MSAA and their

COM implementations, and for the information provided, it is reliable and works well. So an important feature

of IAccessible2 is that the implementation and semantics of MSAA supporting applications and assistive

technologies are preserved. In fact, IAccessible2 builds on the existing COM foundation to expose new

interfaces, roles, states, and events.
Figure 2

Alternatively, an application might choose to have two servers: one for MSAA and one for IAccessible2.

6 © ISO/IEC 2012 – All rights reserved
---------------------- Page: 12 ----------------------
ISO/IEC TR 13066-3:2012(E)
Figure 3
4 Using the API
4.1 Overview

Similar to MSAA, IAccessible2 developers need to identify whether the role of their code is as a server -- a

provider of IAccessible2 information, or a client – a consumer of IAccessible2 information. Typically AT

systems are IAccessible2 clients, and query the IAccessible2 servers for information which can then be

passed on to the user. In like fashion, servers are usually components in software applications, such as GUI

controls. The controls have roles, state and property information, and values.

For example, a screen reader is an IAccessible2 client. It connects to the IAccessible2 server and, using the

IAccessible2 APIs, interrogates the server for information about the object, such as its name and value or

state, and speaks information about the object to the user in a way that is meaningful. The IAccessible2 server

notifies the client of significant changes to the UI, such as focus changes, through WinEvents.

4.2 User Interface elements

The IAccessible2 interfaces do not support child IDs, i.e. simple element implementations. Full accessible

objects (IAccessible object with ChildID = CHILDID_SELF) must be created for each object that

rfaces must also be implemented.
supports IAccessible2. If necessary, some of the IAccessible2 inte

Therefore MSAA's get_accChild should never return a child ID (other than CHILDID_SELF) for an object that

implements any of the IAccessible2 interfaces. Although the IAccessible2 interface is a subclass of MSAA’s

IAccessible, none of the IAccessible methods are overridden or extended.

Like MSAA, IAccessible2 objects have roles and states. The IAccessible2 interface defines an extended set

of accessible roles and states in addition to the set of MSAA roles and states. In addition, an IAccessible2

object can have properties describing its relationship to other objects, its position within a group of objects, its

locale, and its unique ID.

IAccessible2 provides special interfaces for certain types of accessible objects. These interfaces expose

properties that are unique to the particular type of object supported:
© ISO/IEC 2012 – All rights reserved 7
---------------------- Page: 13 ----------------------
ISO/IEC TR 13066-3:2012(E)

 IAccessibleHyperText provides the number of links in a document or text object within a document. It

will return the link at a particular index.

 IAccessibleHyperLink provides information about a specific link or set of links.

 IAccessibleImage provides the size, coordinates, and description of an image

 IAccessibleTable2 provides information about 2-dimensional tables such as the number of rows and

columns, the table summary, and the currently selected cells.

 IAccessibleText provides information about text such as the total number of text characters, the

attributes of the text, the position of the text caret, and the number of non-contiguous selections.

4.3 Getting and setting focus

IAccessible2 uses the standard Windows/MSAA mechanisms for getting and setting the keyboard focus.

When the focus is on an accessible text object, it is also critical for AT to know the location of the text caret

and to be able to set the text caret. MSAA does not provide a mechanism for getting and setting the location

of the text caret. Using IAccessible2’s IAccessibleText interface, a server can provide the location of the

text caret and a client can set the position of the text caret.
4.4 Communication Mechanisms
Like MSAA, IAccessible2 uses standard Windows interfaces for communication
...

Questions, Comments and Discussion

Ask us and Technical Secretary will try to provide an answer. You can facilitate discussion about the standard in here.