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: (not documented yet)
Constants
PBAccessEvent_LABEL_CHANGED
PBAccessEvent_LABEL_CHANGED = 1
(not documented yet)
PBAccessEvent_TEXT_CHANGED
PBAccessEvent_TEXT_CHANGED = 2
(not documented yet)
PBAccessEvent_DESCRIPTION_CHANGED
PBAccessEvent_DESCRIPTION_CHANGED = 3
(not documented yet)
PBAccessEvent_CHECK_STATE_CHANGED
PBAccessEvent_CHECK_STATE_CHANGED = 4
(not documented yet)
PBAccessEvent_SELECTION_STATE_CHANGED
PBAccessEvent_SELECTION_STATE_CHANGED = 5
(not documented yet)
PBAccessEvent_SELECTED_ITEM_CHANGED
PBAccessEvent_SELECTED_ITEM_CHANGED = 6
(not documented yet)
PBAccessEvent_FOCUSED_ITEM_CHANGED
PBAccessEvent_FOCUSED_ITEM_CHANGED = 7
(not documented yet)
PBAccessEvent_HANDLE_INFO_CHANGED
PBAccessEvent_HANDLE_INFO_CHANGED = 8
(not documented yet)
PBAccessEvent_HANDLE_POSITION_CHANGED
PBAccessEvent_HANDLE_POSITION_CHANGED = 9
(not documented yet)
PBAccessEvent_BUTTON_INVOKED
PBAccessEvent_BUTTON_INVOKED = 10
(not documented yet)
PBAccessEvent_HANDLE_START_DRAG
PBAccessEvent_HANDLE_START_DRAG = 11
(not documented yet)
PBAccessEvent_HANDLE_END_DRAG
PBAccessEvent_HANDLE_END_DRAG = 12
(not documented yet)
PBAccessHandleType
Enumeration/bitset of type uint8_t: (not documented yet)
Constants
PBAccessHandleType_SLIDE
PBAccessHandleType_SLIDE = 1
(not documented yet)
PBAccessHandleType_RESIZE
PBAccessHandleType_RESIZE = 2
(not documented yet)
PBAccessHandleType_MOVE
PBAccessHandleType_MOVE = 3
(not documented yet)
PBAccessHandleType_ROTATE
PBAccessHandleType_ROTATE = 4
(not documented yet)
PBAccessHandleSides
Enumeration/bitset of type uint8_t: (not documented yet)
Constants
PBAccessHandleSide_LEFT
PBAccessHandleSide_LEFT = 1<<0
(not documented yet)
PBAccessHandleSide_RIGHT
PBAccessHandleSide_RIGHT = 1<<1
(not documented yet)
PBAccessHandleSide_TOP
PBAccessHandleSide_TOP = 1<<2
(not documented yet)
PBAccessHandleSide_BOTTOM
PBAccessHandleSide_BOTTOM = 1<<3
(not documented yet)
PBAccessMoveHandleFlags
Enumeration/bitset of type uint8_t: (not documented yet)
Constants
PBAccessMoveHandle_RELATIVE
PBAccessMoveHandle_RELATIVE = 1<<0
(not documented yet)
PBAccessMoveHandle_PRESERVE_ASPECT_RATIO
PBAccessMoveHandle_PRESERVE_ASPECT_RATIO = 1<<1
(not documented yet)
PBAccessMoveHandle_ANCHOR_CENTER
PBAccessMoveHandle_ANCHOR_CENTER = 1<<2
(not documented yet)
PBAccessSelectAction
Enumeration/bitset of type uint8_t: (not documented yet)
Constants
PBAccessSelect_SELECT
PBAccessSelect_SELECT = 0
(not documented yet)
PBAccessSelect_ADD_TO_SELECTION
PBAccessSelect_ADD_TO_SELECTION = 1
(not documented yet)
PBAccessSelect_REMOVE_FROM_SELECTION
PBAccessSelect_REMOVE_FROM_SELECTION = 2
(not documented yet)
PBAccessHandleAxis
Enumeration/bitset of type uint8_t: (not documented yet)
Constants
PBAccessHandleAxis_X
PBAccessHandleAxis_X = 1
(not documented yet)
PBAccessHandleAxis_Y
PBAccessHandleAxis_Y = 2
(not documented yet)
PBAccessHandleAxis_Z
PBAccessHandleAxis_Z = 3
(not documented yet)
PBAccessRole
Enumeration/bitset of type uint16_t: (not documented yet)
Constants
PBAccessRole_DECORATIVE
PBAccessRole_DECORATIVE = 0
(not documented yet)
PBAccessRole_UNSUPPORTED
PBAccessRole_UNSUPPORTED = 1
(not documented yet)
PBAccessRole_TEXT
PBAccessRole_TEXT = 2
(not documented yet)
PBAccessRole_IMAGE
PBAccessRole_IMAGE = 3
(not documented yet)
PBAccessRole_BUTTON
PBAccessRole_BUTTON = 4
(not documented yet)
PBAccessRole_RADIO_GROUP
PBAccessRole_RADIO_GROUP = 5
(not documented yet)
PBAccessRole_RADIO_BUTTON
PBAccessRole_RADIO_BUTTON = 6
(not documented yet)
PBAccessRole_LIST_VIEW
PBAccessRole_LIST_VIEW = 7
(not documented yet)
PBAccessRole_LIST_ITEMS
PBAccessRole_LIST_ITEMS = 8
(not documented yet)
PBAccessRole_LIST_ITEM
PBAccessRole_LIST_ITEM = 9
(not documented yet)
PBAccessRole_CHECKBOX
PBAccessRole_CHECKBOX = 10
(not documented yet)
PBAccessRole_SCROLL_VIEW
PBAccessRole_SCROLL_VIEW = 11
(not documented yet)
PBAccessRole_HANDLE
PBAccessRole_HANDLE = 12
(not documented yet)
PBAccessRole_CONTAINER
PBAccessRole_CONTAINER = 13
(not documented yet)
PBAccessRole_POPUP_BUTTON
PBAccessRole_POPUP_BUTTON = 14
(not documented yet)
PBAccessRole_WINDOW
PBAccessRole_WINDOW = 15
(not documented yet)
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.
See Also
PBMessageGetPropCheckState
Structure: (not documented yet)
Fields
checkState (PBCheckState): (not documented yet)
PBMessageGetPropHandleInfo
Structure: (not documented yet)
Fields
type (PBAccessHandleType): (not documented yet)
sides (PBAccessHandleSides): (not documented yet)
PBMessageGetPropHandlePosition
Structure: (not documented yet)
Fields
[in] axis (PBAccessHandleAxis): (not documented yet)
maximum (double): (not documented yet)
value (double): (not documented yet)
PBMessageGetPropRole
Structure: (not documented yet)
Fields
role (PBAccessRole): (not documented yet)
PBMessageGetPropElement
Structure: (not documented yet)
Fields
element (nullable owned PBElement): (not documented yet)
PBMessageGetPropString
Structure: (not documented yet)
Fields
string (string buffer): (not documented yet)
PBMessageGetPropBool
Structure: (not documented yet)
Fields
b (bool): (not documented yet)
PBMessageInteractMoveHandle
Structure: (not documented yet)
Fields
[in] axis (PBAccessHandleAxis): (not documented yet)
[in] flags (PBAccessMoveHandleFlags): (not documented yet)
[in] value (double): (not documented yet)
PBMessageInteractSelectItem
Structure: (not documented yet)
Fields
[in] item (nullable referenced PBElement): (not documented yet)
[in] action (PBAccessSelectAction): (not documented yet)
PBMessageInteractSelectSelf
Structure: (not documented yet)
Fields
[in] action (PBAccessSelectAction): (not documented yet)
PBMessageInteractSetCheckState
Structure: (not documented yet)
Fields
[in] checkState (PBCheckState): (not documented yet)
PBRemoteWindowInformation
Structure: (not documented yet)
Fields
bounds (PBRectangle): (not documented yet)
screenID (PBScreenID): (not documented yet)
isHidden (bool): (not documented yet)
type (PBWindowType): (not documented yet)
flags (PBWindowFlags): (not documented yet)
decorationInsets (PBRectangle): (not documented yet)
PBElementReportEvent
Function: (not documented yet)
Syntax (C/C++)
void PBElementReportEvent(PBElementRef element, PBAccessEvent event);
Syntax (Python)
ElementReportEvent(element, event)
Parameters and Return Values
[in] element (referenced PBElement): (not documented yet)
[in] event (PBAccessEvent): (not documented yet)
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): (not documented yet)
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): (not documented yet)
[out] success (bool): (not documented yet)
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): (not documented yet)
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): (not documented yet)
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): (not documented yet)
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.