data-id=reading-pdf-files-through-msaa

Reading PDF Files Through MSAA

Microsoft Active Accessibility defines the IAccessible interface to applications. This interface consists of a set of methods and properties that are defined in the MSAA documentation.

Acrobat implements and exports a set of IAccessible objects of different types to represent a document, its pages, and other elements of the document hierarchy.

An MSAA client can retrieve an IAccessible object for a user interface element in the following four ways:

• Set a WinEvent hook, receive a notification, and call AccessibleObjectFromEvent to retrieve an IAccessible interface pointer for the user interface element that generated the event. See Handling event notifications for details.
• Call AccessibleObjectFromWindow and pass the user interface element’s window handle. Each open document in Acrobat is associated with its own window handle.
• Call AccessibleObjectFromPoint and pass a screen location that lies within the user interface element’s bounding rectangle.
• Call an IAccessible method such as accNavigate or get_accParent to move to a different IAccessible object.

data-id=acrobat-implementation-of-iaccessible-objects

Acrobat implementation of IAccessible objects

Each type of IAccessible object has a different implementation of the standard methods:

• Links, tables, and form fields are explicitly identified through MSAA.
• Headers, paragraphs, and other elements of document structure are only represented implicitly.

Note

These elements are explicit in the DOM interface; see Reading PDF Files Through the DOM Interface.

For each document, Acrobat builds a tree of IAccessible objects representing the document and its internal structure. Because there is just one window handle associated with the document, Acrobat posts all event notifications to that window. In each notification, a childID identifies an IAccessible object for an element in the document. For example, when the user tabs to the next link, the EVENT_OBJECT_FOCUS notification includes a childID that is the UID of the link object. See Handling event notifications.

The following interfaces are exported from the IAccessible object by Acrobat:

data-id=10950

data-id=igetpddomnode-interface

IGetPDDomNode interface

This interface exports one function, get_PDDomNode, which returns a DOM object. The methods described in Reading PDF Files Through the DOM Interface” can then be used on this object.

data-id=get-pddomnode

get_PDDomNode

Returns a DOM object. For more information, see Reading PDF Files Through the DOM Interface.

varID is the same as for the other MSAA methods (see Descriptive properties and methods)

HRESULT get_PDDomNode(
VARIANT varID,
IPDDomNode **ppDispDoc);

data-id=iselecttext-interface

ISelectText interface

In Acrobat 7.0, the ISelectText interface is an interface exported by the IAccessible objects. It exports one function, selectText, that sets the text selection, but specifies the end location via IAccessible objects instead of DOM nodes. The ISelectText interface is available from the root IAccessible object.

data-id=selecttext

selectText

Sets the text selection. startAccID and endAccID are the accID identifiers for the starting and ending IAccessible elements, and startIndex and endIndex are zero-based indexes into the text of those IAccessible objects.

LRESULT selectText(
long startAccID,
long startIndex,
long endAccID,
long endIndex);

data-id=99842

data-id=identifying-iaccessible-objects-in-a-document

Identifying IAccessible objects in a document

You can identify the type of an IAccessible object by using the get_accRole method to get its Role attribute. However, you must also distinguish individual objects from others of the same type. You can do this by means of a unique identifier (UID) defined by Acrobat.

The IAccessible objects defined by Acrobat export a private interface, IAccID, defined in the file IAccID.h. It contains one function, get_accID. Use this UID to determine when two IAccessible objects refer to the same element in the document.

When a value-change notification or a focus notification has a non-zero childID, the value of childID is the UID of one of the objects on the page or document. Use the UID to uniquely identify the object that is the target of the notification.

data-id=get-accid

get_accID

Returns an identifier that is unique within the open document or page.

HRESULT get_accID(long *id);

Parameters

Returns

Always returns s_ok.

Example

IAccID *pID;
 long uid;
 /* query for the IAccID interface */
 RESULT hr = pObj->QueryInterface (IID_IAccID,
                                         reinterpret_cast<void **>(&pID));
 if (!FAILED(hr))
 {
         pID->get_accID(&uid);
         pID->Release();
 }

Note

If you obtained the IAccessible object via a call to AccessibleObjectFrom XXX, it is not possible to query directly for this private interface. In that case, you must use this alternate code:

IServiceProvider *sp = NULL;
 hr = n->QueryInterface(IID_IServiceProvider, (LPVOID*)&sp);
 if (SUCCEEDED(hr) && sp) {
         hr = sp->QueryService(SID_AccID, IID_IAccID, (LPVOID*)&pID);
         sp->Release();
 }

data-id=29922

data-id=iaccessible-method-summary

IAccessible method summary

This section provides a brief syntax summary of the IAccessible interface methods as defined by MSAA. All methods return HRESULT. The methods and properties are organized into the following groups:

• Navigation and hierarchy
• Descriptive properties and methods
• Selection and focus
• Spatial mapping

data-id=73526

data-id=navigation-and-hierarchy

Navigation and hierarchy

This section provides information on the APIs used in navigation and to traverse the hierarchy.

data-id=accnavigate

accNavigate

Traverses to another user interface element within a container and retrieves the object. All visual objects support this method.

accNavigate (long navDir, VARIANT varStart, VARIANT* pvarEnd);

Properties

Returns

HRESULT

data-id=get-accchild

get_accChild

Retrieves an IDispatch interface pointer for the specified child, if one exists. All objects support this property.

get_accChild (VARIANT varChildID, IDispatch** ppdispChild);

Properties

Returns

HRESULT

data-id=get-accchildcount

get_accChildCount

Retrieves the number of children that belong to this object. All objects support this property.

get_accChildCount (long* pcountChildren);

Properties

Returns

HRESULT

data-id=get-accparent

get_accParent

Retrieves an IDispatch interface pointer for the parent of this object. All objects support this property.

get_accParent (IDispatch** ppdispParent);

Properties

Returns

HRESULT

data-id=89440

data-id=descriptive-properties-and-methods

Descriptive properties and methods

This section provides information on the descriptive APIs.

data-id=accdodefaultaction

accDoDefaultAction

Performs the object’s default action. Not all objects have a default action.

accDoDefaultAction (VARIANT varID);

Properties

Returns

HRESULT

data-id=get-accdefaultaction

get_accDefaultAction

Retrieves a string that describes the object’s default action. Not all objects have a default action.

get_accDefaultAction(VARIANT varID, BSTR* pszDefaultAction);

Properties

Returns

HRESULT

data-id=get-accdescription

get_accDescription

Retrieves a string that describes the visual appearance of the object. Not all objects have a description.

get_accDescription (VARIANT varID, BSTR* pszDescription);

Properties

Returns

HRESULT

data-id=get-accname

get_accName

Retrieves the name of the object. All objects have a name.

get_accName (VARIANT varID, BSTR* pszName );

Properties

Returns

HRESULT

data-id=get-accrole

get_accRole

Retrieves the role of the object. All objects have a role.

get_accRole (VARIANT varID, VARIANT* pvarRole );

Properties

Returns

HRESULT

data-id=get-accstate

get_accState

Retrieves the state of the object. All objects have a state.

get_accState (VARIANT varID, VARIANT* pvarState );

Properties

Returns

HRESULT

data-id=get-accvalue

get_accValue

Retrieves the value of the object. Not all objects have a value.

get_accValue (VARIANT varID, BSTR* pszValue );

Properties

Returns

HRESULT

data-id=22290

data-id=selection-and-focus

Selection and focus

This section provides information on the selection and focus APIs.

data-id=accselect

accSelect

Modifies the selection or moves the keyboard focus of the object. All objects that support selection or receive the keyboard focus support this method.

accSelect (long flagsSelect, VARIANT varID);

Properties

Returns

HRESULT

data-id=get-accfocus

get_accFocus

Retrieves the object that has the keyboard focus. All objects that receive the keyboard focus support this property.

get_accFocus (VARIANT* pvarID);

Properties

Returns

HRESULT

data-id=get-accselection

get_accSelection

Retrieves the selected children of the object. All objects that support selection support this property.

get_accSelection (VARIANT* pvarChildren);

Properties

Returns

HRESULT

data-id=57514

data-id=spatial-mapping

Spatial mapping

data-id=acclocation

accLocation

Retrieves the object’s current screen location. All visual objects support this method.

accLocation (long* pxLeft, long* pyTop, long* pcxWidth, long* pcyHeight, VARIANT varID );

Properties

Returns

HRESULT

data-id=acchittest

accHitTest

Retrieves the object at a specific screen location. All visual objects support this method.

accHitTest (long, long, VARIANT* pvarID);

Properties

Returns

HRESULT

data-id=88342

data-id=iaccessible-object-types-for-pdf

IAccessible object types for PDF

This section describes the MSAA IAccessible object types that are defined to represent PDF documents and their elements. For each object, its methods are listed along with notes on how the implementation is specific to the object type.

Note

Methods that are not listed are not implemented for a given object type.

The objects are:

• PDF Document
• PDF Page
• PDF Protected Document
• Empty PDF Document
• PDF Structure Element
• PDF Content Element
• PDF Comment
• PDF Link
• PDF Text Form Field
• PDF Button Form Field
• PDF CheckBox Form Field
• PDF RadioButton Form Field
• PDF ComboBox Form Field
• PDF List Box Form Field
• PDF Digital Signature Form Field
• PDF Caret

The following are some general notes:

• PDF form fields generally correspond closely to standard user interface elements described in the MSAA SDK document. The IAccessible objects of form fields attempt to match the behavior described in Appendix A, “Supported User Interface Elements,” of the MSAA document. An exception is the PDF combo box, which has a much simpler structure.
• Form fields, links, and comments, as well as the document as a whole, can take keyboard focus. Subparts of the document (sections, paragraphs, and so on) cannot take focus.
• A document’s contents may be only partially visible on the screen. The get_accLocation method for a given object returns the screen location of the visible part of the object only. You can use this method to determine which portions of the content are visible.

data-id=39396

data-id=pdf-document

PDF Document

Represents the contents of an entire PDF document. The subtree of IAccessible objects beneath the PDF Document object reflects the logical structure of the document.

Note

Content that is not part of the logical structure, such as page headers and footers, is not presented through the MSAA interface.

data-id=89992

data-id=pdf-page

PDF Page

Represents the contents of one page of a PDF document. The subtree of IAccessible objects beneath the PDF Page node reflects the logical structure of the page.

Note

Content that is not part of the logical structure, such as page headers and footers, is not presented through the MSAA interface.

data-id=72837

data-id=pdf-protected-document

PDF Protected Document

Represents a protected document. When the permissions associated with a document disable accessibility, the contents are not exported through the MSAA interface. The IAccessible object for such a document informs the client that the document is protected.

data-id=10863

data-id=empty-pdf-document

Empty PDF Document

Represents an empty or apparently empty document. A PDF file may have no contents to export through MSAA if, for instance, the file is a scanned image that has not been run through an optical character recognition (OCR) tool. The IAccessible object for empty documents and pages informs the client that there may be a problem, even if the document or page is genuinely empty.

data-id=77828

data-id=pdf-structure-element

PDF Structure Element

Represents a subtree of the logical structure tree for the document. It might correspond to a paragraph, a heading, a chapter, a span of text within a word, or a figure.

data-id=23328

data-id=pdf-content-element

PDF Content Element

Corresponds to a leaf node of the logical structure tree for the document. It corresponds to marking commands in the page content stream.

data-id=22500

data-id=pdf-comment

PDF Comment

Corresponds to a comment, such as a text note or highlight comment, attached to the document.

Note

PDF comments cover a range of objects, many of which do not map into the standard MSAA roles. The IAccessible object captures the most important properties of comments.

data-id=55866

data-id=pdf-link

PDF Link

Corresponds to a link in the document.

data-id=40546

data-id=pdf-text-form-field

PDF Text Form Field

Corresponds to a text form field in the document.

data-id=91493

data-id=pdf-button-form-field

PDF Button Form Field

Corresponds to a button form field in the document.

data-id=13511

data-id=pdf-checkbox-form-field

PDF CheckBox Form Field

Corresponds to a checkbox form field in the document.

data-id=19394

data-id=pdf-radiobutton-form-field

PDF RadioButton Form Field

Corresponds to a radio button form field in the document.

data-id=25792

data-id=pdf-combobox-form-field

PDF ComboBox Form Field

Corresponds to a combo box form field in the document. It can represent either the combo box itself, or a list item in a combo box.

data-id=20747

data-id=pdf-list-box-form-field

PDF List Box Form Field

Corresponds to a list box form field in the document. It can represent either the list box itself or a list item in a list box.

data-id=91488

data-id=pdf-digital-signature-form-field

PDF Digital Signature Form Field

Corresponds to a digital signature form field in the document.

data-id=49405

data-id=pdf-caret

PDF Caret

Represents a caret (text cursor). If a document contains the system caret because focus is within an editable text field or an editable ComboBox field, clients can obtain an IAccessible object for the caret to determine where it is located.