Accessibility and Automation

PBRemote

Opaque object handle: An object that lets you navigate and control the workspace's user interface hierarchy. The remote tracks a single PBElement (from any app in the workspace). With the remote, you can send operations to the element, query its properties, as well as switch to a different element to track.

This object maintains an internal reference count. When the reference count reaches zero, the object will be automatically deallocated. To increment the reference count, call PBRemoteRetain; to decrement the reference count, call PBRemoteRelease. These functions are thread-safe.

PBAccessEvent

Enumeration/bitset of type uint16_t:

Constants

PBAccessEvent_LABEL_CHANGED

PBAccessEvent_LABEL_CHANGED = 1

PBAccessEvent_TEXT_CHANGED

PBAccessEvent_TEXT_CHANGED = 2

PBAccessEvent_DESCRIPTION_CHANGED

PBAccessEvent_DESCRIPTION_CHANGED = 3

PBAccessEvent_CHECK_STATE_CHANGED

PBAccessEvent_CHECK_STATE_CHANGED = 4

PBAccessEvent_SELECTION_STATE_CHANGED

PBAccessEvent_SELECTION_STATE_CHANGED = 5

PBAccessEvent_SELECTED_ITEM_CHANGED

PBAccessEvent_SELECTED_ITEM_CHANGED = 6

PBAccessEvent_FOCUSED_ITEM_CHANGED

PBAccessEvent_FOCUSED_ITEM_CHANGED = 7

PBAccessEvent_HANDLE_INFO_CHANGED

PBAccessEvent_HANDLE_INFO_CHANGED = 8

PBAccessEvent_HANDLE_POSITION_CHANGED

PBAccessEvent_HANDLE_POSITION_CHANGED = 9

PBAccessEvent_BUTTON_INVOKED

PBAccessEvent_BUTTON_INVOKED = 10

PBAccessEvent_HANDLE_START_DRAG

PBAccessEvent_HANDLE_START_DRAG = 11

PBAccessEvent_HANDLE_END_DRAG

PBAccessEvent_HANDLE_END_DRAG = 12

PBAccessHandleType

Enumeration/bitset of type uint8_t:

Constants

PBAccessHandleType_SLIDE

PBAccessHandleType_SLIDE = 1

PBAccessHandleType_RESIZE

PBAccessHandleType_RESIZE = 2

PBAccessHandleType_MOVE

PBAccessHandleType_MOVE = 3

PBAccessHandleType_ROTATE

PBAccessHandleType_ROTATE = 4

PBAccessHandleSides

Enumeration/bitset of type uint8_t:

Constants

PBAccessHandleSide_LEFT

PBAccessHandleSide_LEFT = 1<<0

PBAccessHandleSide_RIGHT

PBAccessHandleSide_RIGHT = 1<<1

PBAccessHandleSide_TOP

PBAccessHandleSide_TOP = 1<<2

PBAccessHandleSide_BOTTOM

PBAccessHandleSide_BOTTOM = 1<<3

PBAccessMoveHandleFlags

Enumeration/bitset of type uint8_t:

Constants

PBAccessMoveHandle_RELATIVE

PBAccessMoveHandle_RELATIVE = 1<<0

PBAccessMoveHandle_PRESERVE_ASPECT_RATIO

PBAccessMoveHandle_PRESERVE_ASPECT_RATIO = 1<<1

PBAccessMoveHandle_ANCHOR_CENTER

PBAccessMoveHandle_ANCHOR_CENTER = 1<<2

PBAccessSelectAction

Enumeration/bitset of type uint8_t:

Constants

PBAccessSelect_SELECT

PBAccessSelect_SELECT = 0

PBAccessSelect_ADD_TO_SELECTION

PBAccessSelect_ADD_TO_SELECTION = 1

PBAccessSelect_REMOVE_FROM_SELECTION

PBAccessSelect_REMOVE_FROM_SELECTION = 2

PBAccessHandleAxis

Enumeration/bitset of type uint8_t:

Constants

PBAccessHandleAxis_X

PBAccessHandleAxis_X = 1

PBAccessHandleAxis_Y

PBAccessHandleAxis_Y = 2

PBAccessHandleAxis_Z

PBAccessHandleAxis_Z = 3

PBAccessRole

Enumeration/bitset of type uint16_t:

Constants

PBAccessRole_DECORATIVE

PBAccessRole_DECORATIVE = 0

PBAccessRole_UNSUPPORTED

PBAccessRole_UNSUPPORTED = 1

PBAccessRole_TEXT

PBAccessRole_TEXT = 2

PBAccessRole_IMAGE

PBAccessRole_IMAGE = 3

PBAccessRole_BUTTON

PBAccessRole_BUTTON = 4

PBAccessRole_RADIO_GROUP

PBAccessRole_RADIO_GROUP = 5

PBAccessRole_RADIO_BUTTON

PBAccessRole_RADIO_BUTTON = 6

PBAccessRole_LIST_VIEW

PBAccessRole_LIST_VIEW = 7

PBAccessRole_LIST_ITEMS

PBAccessRole_LIST_ITEMS = 8

PBAccessRole_LIST_ITEM

PBAccessRole_LIST_ITEM = 9

PBAccessRole_CHECKBOX

PBAccessRole_CHECKBOX = 10

PBAccessRole_SCROLL_VIEW

PBAccessRole_SCROLL_VIEW = 11

PBAccessRole_HANDLE

PBAccessRole_HANDLE = 12

PBAccessRole_CONTAINER

PBAccessRole_CONTAINER = 13

PBAccessRole_POPUP_BUTTON

PBAccessRole_POPUP_BUTTON = 14

PBAccessRole_WINDOW

PBAccessRole_WINDOW = 15

PBRemoteFindFlags

Enumeration/bitset of type uint32_t: Flags for PBRemoteFind.

Constants

PBRemoteFind_DIRECT_DESCENDENTS_ONLY

PBRemoteFind_DIRECT_DESCENDENTS_ONLY = 1<<0

Only search the direct children of the tracked element. Do not recurse into their descendents as well.

PBMessageGetPropCheckState

Structure:

Fields

checkState (PBCheckState):

PBMessageGetPropHandleInfo

Structure:

Fields

type (PBAccessHandleType):

[in] item (nullable referenced PBElement):

bounds (PBRectangle):

screenID (PBScreenID):

isHidden (bool):

type (PBWindowType):

flags (PBWindowFlags):

decorationInsets (PBRectangle):

PBElementReportEvent

Function:

Syntax (C/C++)

void PBElementReportEvent(PBElementRef element, PBAccessEvent event);

Syntax (Python)

ElementReportEvent(element, event)

Parameters and Return Values

[in] element (referenced PBElement):

[in] event (PBAccessEvent):

PBRemoteCreate

Function: Create a remote to navigate and interact with the workspace's user interface.

Syntax (C/C++)

PBRemotePtr _Nullable PBRemoteCreate();

Syntax (Python)

RemoteCreate() -> (remote)

Parameters and Return Values

[out] remote (nullable owned PBRemote): Null is returned on failure. You must release the remote when you no longer need it with PBRemoteRelease.

Discussion

See PBRemote for an overview of the purpose and capabilities of a remote.

PBRemoteToWorkspace

Function: Change a remote's tracked element to the root of the workspace.

Syntax (C/C++)

void PBRemoteToWorkspace(PBRemoteRef remote);

Syntax (Python)

RemoteToWorkspace(remote)

Parameters and Return Values

[in] remote (referenced PBRemote):

Discussion

The layout children of the workspace element are the open windows of the workspace. When enumerating windows, you likely will want to check which are visible using PBRemoteIsHidden.

PBRemoteToActiveWindow

Function: Change a remote's tracked element to the root element of the active window.

Syntax (C/C++)

bool PBRemoteToActiveWindow(PBRemoteRef remote);

Syntax (Python)

RemoteToActiveWindow(remote) -> (success)

Parameters and Return Values

[in] remote (referenced PBRemote):

[out] success (bool):

PBRemoteToWindowWithID

Function: Change a remote's tracked element to the root element of the window with a given ID.

Syntax (C/C++)

bool PBRemoteToWindowWithID(PBRemoteRef remote, uint64_t windowID);

Syntax (Python)

RemoteToWindowWithID(remote, windowID) -> (success)

Parameters and Return Values

[in] remote (referenced PBRemote): The remote.

[in] windowID (uint64_t): The window identifier. This can be obtained through several sources, such as passing PBWorkspaceRun_CONNECT to PBWorkspaceRun.

[out] success (bool):

PBRemoteToNextTabStop

Function: Change a remote's tracked element to the next tab stop in the window after it.

Syntax (C/C++)

bool PBRemoteToNextTabStop(PBRemoteRef remote);

Syntax (Python)

RemoteToNextTabStop(remote) -> (success)

Parameters and Return Values

[in] remote (referenced PBRemote): The remote.

[out] success (bool): Whether the tracked element could be updated.

PBRemoteToPriorTabStop

Function: Change a remote's tracked element to the next tab stop in the window before it.

Syntax (C/C++)

bool PBRemoteToPriorTabStop(PBRemoteRef remote);

Syntax (Python)

RemoteToPriorTabStop(remote) -> (success)

Parameters and Return Values

[in] remote (referenced PBRemote): The remote.

[out] success (bool): Whether the tracked element could be updated.

PBRemoteToFirstLayoutChild

Function: Change a remote's tracked element to first layout child element of the current element.

Syntax (C/C++)

bool PBRemoteToFirstLayoutChild(PBRemoteRef remote);

Syntax (Python)

RemoteToFirstLayoutChild(remote) -> (success)

Parameters and Return Values

[in] remote (referenced PBRemote): The remote.

[out] success (bool): Whether the tracked element could be updated.

PBRemoteToLastLayoutChild

Function: Change a remote's tracked element to last layout child element of the current element.

Syntax (C/C++)

bool PBRemoteToLastLayoutChild(PBRemoteRef remote);

Syntax (Python)

RemoteToLastLayoutChild(remote) -> (success)

Parameters and Return Values

[in] remote (referenced PBRemote): The remote.

[out] success (bool): Whether the tracked element could be updated.

PBRemoteToNextLayoutSibling

Function: Change a remote's tracked element to next sibling of the current element in its layout parent.

Syntax (C/C++)

bool PBRemoteToNextLayoutSibling(PBRemoteRef remote);

Syntax (Python)

RemoteToNextLayoutSibling(remote) -> (success)

Parameters and Return Values

[in] remote (referenced PBRemote): The remote.

[out] success (bool): Whether the tracked element could be updated.

PBRemoteToPriorLayoutSibling

Function: Change a remote's tracked element to previous sibling of the current element in its layout parent.

Syntax (C/C++)

bool PBRemoteToPriorLayoutSibling(PBRemoteRef remote);

Syntax (Python)

RemoteToPriorLayoutSibling(remote) -> (success)

Parameters and Return Values

[in] remote (referenced PBRemote): The remote.

[out] success (bool): Whether the tracked element could be updated.

PBRemoteToLayoutParent

Function: Change a remote's tracked element to its layout parent.

Syntax (C/C++)

bool PBRemoteToLayoutParent(PBRemoteRef remote);

Syntax (Python)

RemoteToLayoutParent(remote) -> (success)

Parameters and Return Values

[in] remote (referenced PBRemote): The remote.

[out] success (bool): Whether the tracked element could be updated.

PBRemoteToContainingWindow

Function: Change a remote's tracked element to window containing the current tracked element.

Syntax (C/C++)

bool PBRemoteToContainingWindow(PBRemoteRef remote);

Syntax (Python)

RemoteToContainingWindow(remote) -> (success)

Parameters and Return Values

[in] remote (referenced PBRemote): The remote.

[out] success (bool): Whether the tracked element could be updated.

Discussion

If the tracked element was destroyed, then this function will use the window that used to contain it.

PBRemoteToKeyboardFocus

Function: Change a remote's tracked element to the element with keyboard focus in the current window.

Syntax (C/C++)

bool PBRemoteToKeyboardFocus(PBRemoteRef remote);

Syntax (Python)

RemoteToKeyboardFocus(remote) -> (success)

Parameters and Return Values

[in] remote (referenced PBRemote): The remote.

[out] success (bool): Whether the tracked element could be updated.

PBRemoteWindowInvokeCommand

Function: Invoke a command on the window containing the remote's target.

Syntax (C/C++)

bool PBRemoteWindowInvokeCommand(PBRemoteRef remote, PBCommandID commandID, 
    PBModifierKeys modifiers);

Syntax (Python)

RemoteWindowInvokeCommand(remote, commandID, modifiers) -> (success)

Parameters and Return Values

[in] remote (referenced PBRemote): The remote.

[in] commandID (PBCommandID): The command identifier. This can be a standard value, or value defined by the target window.

[in] modifiers (PBModifierKeys): The modifier keys value to pass to the command handler.

[out] success (bool): If the command could not be invoked (for example, if it is disabled) then false is returned.

PBRemoteWindowGetCommandByIndex

Function: Get the identifier of a command registered in the target's window.

Syntax (C/C++)

PBCommandID PBRemoteWindowGetCommandByIndex(PBRemoteRef remote, uintptr_t index);

Syntax (Python)

RemoteWindowGetCommandByIndex(remote, index) -> (commandID)

Parameters and Return Values

[in] remote (referenced PBRemote): The remote.

[in] index (uintptr_t): The index of the command.

[out] commandID (PBCommandID): The command identifier. 0 is returned if no such command exists.

Discussion

Indices start at 0 and assigned sequentially. Indices past the final command will cause this function to return 0.

The function is used to obtain command identifiers. Unlike indices, the meaning of a given command ID should not change between versions of an application.

PBRemoteWindowGetCommandInformation

Function: Get information about a command registered in a window.

Syntax (C/C++)

MutStr PBRemoteWindowGetCommandInformation(PBRemoteRef remote, 
    PBCommandID commandID, /* output */ PBCommandFlags * _Nullable __restrict flags);

Syntax (Python)

RemoteWindowGetCommandInformation(remote, commandID) -> (name, flags)

Parameters and Return Values

[in] remote (referenced PBRemote): The remote.

[in] commandID (PBCommandID): The identifier of the command.

[out] name (owned string): The name of the command. Free with PBHeapFree.

[optional-out] flags (PBCommandFlags): The flags giving the state of the command.

PBRemoteGetLabel

Function: Get the label of the tracked element in the remote.

Syntax (C/C++)

MutStr PBRemoteGetLabel(PBRemoteRef remote);

Syntax (Python)

RemoteGetLabel(remote) -> (label)

Parameters and Return Values

[in] remote (referenced PBRemote): The remote.

[out] label (owned string): The label. Free the pointer with PBHeapFree.

Discussion

The system will query the tracked element for its label by sending it the PBMsg_GET_PROP_LABEL message.

PBRemoteGetText

Function: Get the text of the tracked element in the remote.

Syntax (C/C++)

MutStr PBRemoteGetText(PBRemoteRef remote);

Syntax (Python)

RemoteGetText(remote) -> (text)

Parameters and Return Values

[in] remote (referenced PBRemote): The remote.

[out] text (owned string): The text. Free the pointer with PBHeapFree.

Discussion

The system will query the tracked element for its text by sending it the PBMsg_GET_PROP_TEXT message.

PBRemoteGetCheckState

Function: Get the check state of the tracked element in the remote.

Syntax (C/C++)

PBCheckState PBRemoteGetCheckState(PBRemoteRef remote);

Syntax (Python)

RemoteGetCheckState(remote) -> (checkState)

Parameters and Return Values

[in] remote (referenced PBRemote): The remote.

[out] checkState (PBCheckState): The check state.

Discussion

The system will query the tracked element for its check state by sending it the PBMsg_GET_PROP_CHECK_STATE message.

PBRemoteGetRole

Function: Get the role of the tracked element in the remote.

Syntax (C/C++)

PBAccessRole PBRemoteGetRole(PBRemoteRef remote);

Syntax (Python)

RemoteGetRole(remote) -> (role)

Parameters and Return Values

[in] remote (referenced PBRemote): The remote.

[out] role (PBAccessRole): The check state.

Discussion

The system will query the tracked element for its role by sending it the PBMsg_GET_PROP_ROLE message.

PBRemoteIsDisabled

Function: Get the state of the disabled flag of the tracked element in the remote.

Syntax (C/C++)

bool PBRemoteIsDisabled(PBRemoteRef remote);

Syntax (Python)

RemoteIsDisabled(remote) -> (disabled)

Parameters and Return Values

[in] remote (referenced PBRemote): The remote.

[out] disabled (bool):

PBRemoteIsHidden

Function: Get the state of the hidden flag of the tracked element in the remote.

Syntax (C/C++)

bool PBRemoteIsHidden(PBRemoteRef remote);

Syntax (Python)

RemoteIsHidden(remote) -> (hidden)

Parameters and Return Values

[in] remote (referenced PBRemote): The remote.

[out] hidden (bool):

PBRemoteFind

Function: Find an element to make the tracked element of a remote.

Syntax (C/C++)

bool PBRemoteFind(PBRemoteRef remote, PBAccessRole role, ConstStr label, 
    ConstStr automationID, PBRemoteFindFlags flags);

Syntax (Python)

RemoteFind(remote, role, label, automationID, flags) -> (success)

Parameters and Return Values

[in] remote (referenced PBRemote): The remote.

[in] role (PBAccessRole): The role to search for.

[in] label (referenced string): The label to search for. If this is an empty string, the system does not check labels.

[in] automationID (referenced string): The automation ID to search for. If this is an empty string, the system does not check automation IDs.

[in] flags (PBRemoteFindFlags): A bitwise OR of flags determining the operation of the function.

[out] success (bool): True if a matching element was found and tracked in the remote.

Discussion

The system searches all the descendents of the current tracked element.

If multiple matches are found, the first is selected.

PBRemoteInteractInvoke

Function: Invoke the tracked element.

Syntax (C/C++)

bool PBRemoteInteractInvoke(PBRemoteRef remote);

Syntax (Python)

RemoteInteractInvoke(remote) -> (success)

Parameters and Return Values

[in] remote (referenced PBRemote): The remote.

[out] success (bool): True if a PBMsg_INTERACT_INVOKE message was delivered to the tracked element. This may fail if the element was disabled or destroyed. This value does not indicate if the element actually has done anything in response to processing the message.

PBRemoteInteractSendKeyboardInput

Function: Send keyboard input to the tracked element.

Syntax (C/C++)

bool PBRemoteInteractSendKeyboardInput(PBRemoteRef remote, 
    PBMessageKeyboard message, bool up);

Syntax (Python)

RemoteInteractSendKeyboardInput(remote, message, up) -> (success)

Parameters and Return Values

[in] remote (referenced PBRemote): The remote.

[in] message (PBMessageKeyboard): The keyboard message data. All fields of the structure must be initialized; the system will not fill anything automatically.

[in] up (bool): True if a PBMsg_KEY_UP message is to be sent; false for a PBMsg_KEY_DOWN message. If true, the text field of the message must be empty.

[out] success (bool): True if a PBMsg_KEY_UP or PBMsg_KEY_DOWN message was delivered to the tracked element. This may fail if the element was disabled or destroyed. This value does not indicate if the element actually has done anything in response to processing the message.

Discussion

A PBMsg_KEY_UP or PBMsg_KEY_DOWN message will be sent to the tracked element if it is not disabled.

The message will not propagate to the ancestors of the element and nor will the keyboard input be used for processing keyboard shortcuts registered in the window or similar.

Guide

API Reference