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 callAccessibleObjectFromEvent
to retrieve anIAccessible
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 asaccNavigate
orget_accParent
to move to a differentIAccessible
object.
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:
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.
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);
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.
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);
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.
get_accID¶
Returns an identifier that is unique within the open document or page.
HRESULT get_accID(long *id);
Parameters
id |
(Filled by the method) Returns the unique identifier of the |
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();
}
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:
Descriptive properties and methods¶
This section provides information on the descriptive APIs.
accDoDefaultAction¶
Performs the object’s default action. Not all objects have a default action.
accDoDefaultAction (VARIANT varID);
Properties
|
|
Returns
HRESULT
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
|
|
pszDefaultAction [out, retval] |
Returns a localized string that describes the default action for the object, or |
Returns
HRESULT
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
|
|
pszDescription [out, retval] |
Returns a localized string that describes the object, or |
Returns
HRESULT
get_accName¶
Retrieves the name of the object. All objects have a name.
get_accName (VARIANT varID, BSTR* pszName );
Properties
|
|
pszName [out, retval] |
Returns a localized string that contains the name of the object. |
Returns
HRESULT
get_accRole¶
Retrieves the role of the object. All objects have a role.
get_accRole (VARIANT varID, VARIANT* pvarRole );
Properties
|
|
pvarRole [out, retval] |
Returns a structure that contain an object role constant in its |
Returns
HRESULT
get_accState¶
Retrieves the state of the object. All objects have a state.
get_accState (VARIANT varID, VARIANT* pvarState );
Properties
|
|
pvarRole [out, retval] |
Returns a structure that contain an object state constant in its |
Returns
HRESULT
get_accValue¶
Retrieves the value of the object. Not all objects have a value.
get_accValue (VARIANT varID, BSTR* pszValue );
Properties
|
|
pszValue [out, retval] |
Returns a localized string that contains the current value of the object. |
Returns
HRESULT
Selection and focus¶
This section provides information on the selection and focus APIs.
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
|
Flags that control how the selection or focus operation is performed. A logical OR of these
|
|
|
Returns
HRESULT
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
pvarID [out, retval] |
Returns the address of a |
Returns
HRESULT
get_accSelection¶
Retrieves the selected children of the object. All objects that support selection support this property.
get_accSelection (VARIANT* pvarChildren);
Properties
pvarChildren [out, retval] |
Returns the address of a |
Returns
HRESULT
Spatial mapping¶
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
pxLeft, pxTop [out] |
Return the x and y screen coordinates of the upper-left boundary of the object’s location. (The origin is the upper left corner of the screen.) |
pxWidth, pxHeight [in] |
Return the object’s width and height in pixels. |
|
|
Returns
HRESULT
accHitTest¶
Retrieves the object at a specific screen location. All visual objects support this method.
accHitTest (long, long, VARIANT* pvarID);
Properties
pxLeft, pxTop [in] |
The x and y screen coordinates of the point to test. (The origin is the upper left corner of the screen.) |
|
Address of a
|
Returns
HRESULT
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:
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.
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.
Method |
Implementation notes |
---|---|
accHitTest |
Returns the object at a given location if the location is within the document’s bounding box. |
accLocation |
Returns the screen coordinates of the visible part of the document. |
accNavigate |
Does not support spatial navigation ( |
accSelect |
For |
get_accChild |
Returns a child object. |
get_accChildCount |
Returns the number of child objects beneath this one. |
get_accDescription |
The description contains the full path name of the document and the number of pages it contains: “fileName, XXX pages”. |
get_accFocus |
Returns the object that has the keyboard focus if it is this object or its child. |
get_accParent |
The parent is |
get_accRole |
The role is |
get_accSelection |
Returns |
get_accState |
The state is |
get_accValue |
If the root of the structure tree has an |
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.
Method |
Implementation notes |
---|---|
accHitTest |
Returns the object at the given location if the location is within the page’s bounding box. |
accLocation |
Returns the screen coordinates of the visible part of the page. |
accNavigate |
Does not support spatial navigation ( |
accSelect |
For |
get_accChild |
Returns a child object. |
get_accChildCount |
Returns the number of child objects beneath this one. |
get_accDescription |
The description contains the full path name of the document and the page number of the page: “fileName, page XXX”. |
get_accFocus |
Returns the object that has the keyboard focus if it is this object or its child. |
get_accParent |
The parent is |
get_accRole |
A custom role, |
get_accSelection |
Returns |
get_accState |
The state is |
get_accValue |
If the root of the structure tree has an |
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.
Method |
Implementation notes |
---|---|
accHitTest |
Returns |
accLocation |
The screen coordinates of the visible part of the document. |
accNavigate |
Does not support spatial navigation ( |
accSelect |
Returns |
get_accChildCount |
The child count is 0. |
get_accFocus |
Returns |
get_accName |
The name is “Alert: Protection Failure”. |
get_accParent |
The parent is |
get_accRole |
The role is |
get_accSelection |
Returns |
get_accState |
The state is |
get_accValue |
The value is “This document’s security settings prevent access.” |
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.
Method |
Implementation notes |
---|---|
accHitTest |
Returns |
accLocation |
Returns the screen coordinates of the visible part of the document. |
accNavigate |
Does not support spatial navigation ( |
accSelect |
Returns |
get_accChildCount |
The child count is 0. |
get_accFocus |
Returns |
get_accName |
The name is “Alert: Empty document”. |
get_accParent |
The parent is |
get_accRole |
The role is |
get_accSelection |
Returns |
get_accState |
The state is |
get_accValue |
The value is “This document appears to be empty. It may be a scanned image that needs OCR or it may have malformed structure.” |
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.
Method |
Implementation notes |
---|---|
accDoDefaultAction |
If the element has state |
accHitTest |
Returns this object or any child at the given location if the location is within the bounding box of this object. |
accLocation |
Returns the screen coordinates of the visible part of the subtree. |
accNavigate |
Only spatial navigation ( |
accSelect |
For |
get_accChild |
Returns a child object. |
get_accChildCount |
Returns the number of child objects beneath this one. If the node has an |
get_accDefaultAction |
If the element has state |
get_accFocus |
Returns the object that has the keyboard focus if it is this object or its child. |
get_accParent |
The parent is either another structure element or the document structure root. |
get_accRole |
The role is one of:
|
get_accSelection |
Returns |
get_accState |
The state is a logical OR of one or more of the following:
|
get_accValue |
If this node has an |
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.
Method |
Implementation notes |
---|---|
accDoDefaultAction |
If the element has state |
accHitTest |
Returns this object if the given location is within the bounding box of this object. |
accLocation |
Returns the screen coordinates of the visible part of the element. |
accNavigate |
Does not support spatial navigation ( |
accSelect |
For |
get_accChildCount |
The child count is 0. |
get_accDefaultAction |
If the element has state |
get_accFocus |
Returns the object that has the keyboard focus if it is this object or its child. |
get_accParent |
The parent is either a structure element or the document structure root. |
get_accRole |
The role is one of:
|
get_accSelection |
Returns |
get_accState |
The state is a logical OR of one or more of the following:
|
get_accValue |
If this node has an |
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.
Method |
Implementation notes |
---|---|
accDoDefaultAction |
The default action depends on the type of comment. It can, for example, open or close a popup. |
accHitTest |
Returns this object if the given location is within the bounding box of this object. |
accLocation |
Returns the screen coordinates of the visible part of the object. |
accNavigate |
Does not support spatial navigation ( |
accSelect |
Supports |
get_accChildCount |
The child count is 0. |
get_accDefaultAction |
Describes the default action, which depends on the type of comment. |
get_accDescription |
For file attachment and sound comments, a description of the icon for the comment. |
get_accFocus |
Returns the object that has the keyboard focus if it is this object or its child. |
get_accName |
|
get_accParent |
The parent is either a structure element or the document structure root. |
get_accRole |
The role is one of:
|
get_accSelection |
Returns |
get_accState |
The state is a logical OR of one or more of the following:
|
get_accValue |
|
PDF Link¶
Corresponds to a link in the document.
Method |
Implementation notes |
---|---|
accDoDefaultAction |
Performs the link’s action. |
accHitTest |
Returns this object or any child at the given location if the location is within the bounding box of this object. |
accLocation |
Returns the screen coordinates of the visible part of the object. |
accNavigate |
Does not support spatial navigation ( |
accSelect |
Supports |
get_accChild |
Returns a child object. |
get_accChildCount |
Returns the number of children. If the node has an |
get_accDefaultAction |
Describes the action defined for this link. |
get_accFocus |
Returns the object that has the keyboard focus if it is this object or its child. |
get_accName |
If there is an |
get_accParent |
The parent is either a structure element or the document structure root. |
get_accRole |
The role is |
get_accSelection |
Returns |
get_accState |
The state is a logical OR of the following:
|
get_accValue |
The value is a unique identifier for each link. |
PDF Text Form Field¶
Corresponds to a text form field in the document.
Method |
Implementation notes |
---|---|
accDoDefaultAction |
Sets focus to the text field for editing. |
accHitTest |
Returns this object if the given location is within the bounding box of this object. |
accLocation |
Returns the screen coordinates of the visible part of the object. |
accNavigate |
Does not support spatial navigation ( |
accSelect |
Supports |
get_accChildCount |
The child count is 0. |
get_accDefaultAction |
The default action is “DoubleClick”, which sets the keyboard focus to this field. |
get_accFocus |
Returns the object that has the keyboard focus if it is this object or its child. |
get_accName |
The user name (short description) of the form field. |
get_accParent |
Returns the parent object. |
get_accRole |
The role is |
get_accState |
The state of the text field is a logical OR of one of more of:
|
get_accValue |
The value is the text in the text field. |
PDF Button Form Field¶
Corresponds to a button form field in the document.
Method |
Implementation notes |
---|---|
accDoDefaultAction |
Presses the button. |
accHitTest |
Returns this object if the given location is within the bounding box of this object. |
accLocation |
Returns the screen coordinates of the visible part of the object. |
accNavigate |
Does not support spatial navigation ( |
accSelect |
Supports |
get_accChildCount |
The child count is 0. |
get_accDefaultAction |
The default action is “Press”. |
get_accFocus |
Returns the object that has the keyboard focus if it is this object or its child. |
get_accName |
The user name of the form field (short description). |
get_accParent |
Returns the parent object. |
get_accRole |
The role is |
get_accState |
The state of the button is a logical OR of one or more of:
|
PDF CheckBox Form Field¶
Corresponds to a checkbox form field in the document.
Method |
Implementation notes |
---|---|
accDoDefaultAction |
Checks or unchecks the box. |
accHitTest |
Returns this object if the given location is within the bounding box of this object. |
accLocation |
Returns the screen coordinates of the visible part of the object. |
accNavigate |
Does not support spatial navigation ( |
accSelect |
Supports |
get_accChildCount |
The child count is 0. |
get_accDefaultAction |
|
get_accFocus |
Returns the object that has the keyboard focus if it is this object or its child. |
get_accName |
The user name (short description) of the form field. |
get_accParent |
Returns the parent object. |
get_accRole |
The role is |
get_accState |
The state of the check box is a logical OR of one or more of:
|
PDF RadioButton Form Field¶
Corresponds to a radio button form field in the document.
Method |
Implementation notes |
---|---|
accDoDefaultAction |
Clicks the radio button. |
accHitTest |
Returns this object if the given location is within the bounding box of this object. |
accLocation |
Returns the screen coordinates of the visible part of the object. |
accNavigate |
Does not support spatial navigation ( |
accSelect |
Supports |
get_accChildCount |
The child count is 0. |
get_accDefaultAction |
The default action is “Check”. |
get_accFocus |
Returns the object that has the keyboard focus if it is this object or its child. |
get_accName |
The user name (short description) of the form field. |
get_accParent |
Returns the parent object. |
get_accRole |
The role is |
get_accState |
The state of the radio button is a logical OR of one or more of:
|
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.
Method |
Implementation notes |
---|---|
accDoDefaultAction |
|
accHitTest |
|
accLocation |
|
accNavigate |
|
accSelect |
|
get_accChild |
|
get_accChildCount |
|
get_accDefaultAction |
|
get_accFocus |
|
get_accName |
|
get_accParent |
|
get_accSelection |
|
get_accRole |
|
get_accState |
|
get_accValue |
|
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.
Method |
Implementation notes |
---|---|
accDoDefaultAction |
|
accHitTest |
|
accLocation |
|
accNavigate |
|
accSelect |
|
get_accChild |
|
get_accChildCount |
|
get_accDefaultAction |
|
get_accFocus |
|
get_accName |
|
get_accParent |
|
get_accRole |
|
get_accState |
|
get_accSelection |
|
get_accValue |
|
PDF Digital Signature Form Field¶
Corresponds to a digital signature form field in the document.
Method |
Implementation notes |
---|---|
accDoDefaultAction |
Signs the document if the signature field is unsigned and has either been opened with Acrobat or the document has permissions that allow signing. If the document is signed, the default action brings up a dialog box containing the signature information. |
accHitTest |
Returns this object if the given location is within the bounding box of this object. |
accLocation |
Returns the screen coordinates of the visible part of the object. |
accNavigate |
Does not support spatial navigation ( |
accSelect |
Supports |
get_accChildCount |
The child count is 0. |
get_accDefaultAction |
Returns |
get_accFocus |
Returns the object that has the keyboard focus if it is this object or its child. |
get_accName |
The user name (short description) of the form field. |
get_accParent |
Returns the parent object. |
get_accRole |
The Digital Signature form field does not map to any of the existing roles, and a custom role, |
get_accState |
The
|
get_accValue |
The |
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.
Method |
Implementation notes |
---|---|
accHitTest |
Returns this object if the given location is within the bounding box of this object. |
accLocation |
Returns the screen coordinates of the caret, both when the caret is in a form field and when it is in the document. |
get_accChildCount |
The child count is 0. |
get_accDescription |
The description is a string containing the index of the character in the field that follows the caret. If the caret is at the beginning of the field, the description string is “0”. If the caret follows the first character, the description string is “1”. |
get_accParent |
The parent is the field containing the caret. However, the caret |
get_accRole |
The role is |
get_accState |
The state is 0. |
get_accValue |
The value is the current value of the Text field or ComboBox form field containing the caret. |