wxRuby Documentation Home

# Wx::Accessible

The Accessible class allows Widgets applications, and
Widgets itself, to return extended information about user interface elements
to client applications such as screen readers. This is the
main way in which Widgets implements accessibility features.

At present, only Microsoft Active Accessibility is supported
by this class.

To use this class, derive from Accessible, implement appropriate
functions, and associate an object of the class with a
window using Window#set_accessible.

All functions return an indication of success, failure, or not implemented
using values of the AccStatus enum type.

If you return ACC_NOT_IMPLEMENTED from any function, the system will try to
implement the appropriate functionality. However this will not work with
all functions.

Most functions work with an object id, which can be zero to refer to
‘this’ UI element, or greater than zero to refer to the nth child element.
This allows you to specify elements that don’t have a corresponding Window or
Accessible; for example, the sash of a splitter window.

For details on the semantics of functions and types, please refer to the
Microsoft Active Accessibility 1.2 documentation.

This class is compiled into Widgets only if the USE_ACCESSIBILITY setup
symbol is set to 1.

## Derived from

Object

## Data structures

Functions return a AccStatus error code, which
may be one of the following:

typedef enum { ACC_FAIL, // The function failed ACC_FALSE, // The function returned false ACC_OK, // The function completed successfully ACC_NOT_IMPLEMENTED, // The function is not implemented ACC_NOT_SUPPORTED // The function is not supported } AccStatus

Directions of navigation are represented by
the following:

typedef enum { NAVDIR_DOWN, NAVDIR_FIRSTCHILD, NAVDIR_LASTCHILD, NAVDIR_LEFT, NAVDIR_NEXT, NAVDIR_PREVIOUS, NAVDIR_RIGHT, NAVDIR_UP } NavDir

The role of a user interface element is represented
by the following type:

typedef enum { ROLE_NONE, ROLE_SYSTEM_ALERT, ROLE_SYSTEM_ANIMATION, ROLE_SYSTEM_APPLICATION, ROLE_SYSTEM_BORDER, ROLE_SYSTEM_BUTTONDROPDOWN, ROLE_SYSTEM_BUTTONDROPDOWNGRID, ROLE_SYSTEM_BUTTONMENU, ROLE_SYSTEM_CARET, ROLE_SYSTEM_CELL, ROLE_SYSTEM_CHARACTER, ROLE_SYSTEM_CHART, ROLE_SYSTEM_CHECKBUTTON, ROLE_SYSTEM_CLIENT, ROLE_SYSTEM_CLOCK, ROLE_SYSTEM_COLUMN, ROLE_SYSTEM_COLUMNHEADER, ROLE_SYSTEM_COMBOBOX, ROLE_SYSTEM_CURSOR, ROLE_SYSTEM_DIAGRAM, ROLE_SYSTEM_DIAL, ROLE_SYSTEM_DIALOG, ROLE_SYSTEM_DOCUMENT, ROLE_SYSTEM_DROPLIST, ROLE_SYSTEM_EQUATION, ROLE_SYSTEM_GRAPHIC, ROLE_SYSTEM_GRIP, ROLE_SYSTEM_GROUPING, ROLE_SYSTEM_HELPBALLOON, ROLE_SYSTEM_HOTKEYFIELD, ROLE_SYSTEM_INDICATOR, ROLE_SYSTEM_LINK, ROLE_SYSTEM_LIST, ROLE_SYSTEM_LISTITEM, ROLE_SYSTEM_MENUBAR, ROLE_SYSTEM_MENUITEM, ROLE_SYSTEM_MENUPOPUP, ROLE_SYSTEM_OUTLINE, ROLE_SYSTEM_OUTLINEITEM, ROLE_SYSTEM_PAGETAB, ROLE_SYSTEM_PAGETABLIST, ROLE_SYSTEM_PANE, ROLE_SYSTEM_PROGRESSBAR, ROLE_SYSTEM_PROPERTYPAGE, ROLE_SYSTEM_PUSHBUTTON, ROLE_SYSTEM_RADIOBUTTON, ROLE_SYSTEM_ROW, ROLE_SYSTEM_ROWHEADER, ROLE_SYSTEM_SCROLLBAR, ROLE_SYSTEM_SEPARATOR, ROLE_SYSTEM_SLIDER, ROLE_SYSTEM_SOUND, ROLE_SYSTEM_SPINBUTTON, ROLE_SYSTEM_STATICTEXT, ROLE_SYSTEM_STATUSBAR, ROLE_SYSTEM_TABLE, ROLE_SYSTEM_TEXT, ROLE_SYSTEM_TITLEBAR, ROLE_SYSTEM_TOOLBAR, ROLE_SYSTEM_TOOLTIP, ROLE_SYSTEM_WHITESPACE, ROLE_SYSTEM_WINDOW } AccRole

Objects are represented by the following type:

typedef enum { OBJID_WINDOW = 0×00000000, OBJID_SYSMENU = 0xFFFFFFFF, OBJID_TITLEBAR = 0xFFFFFFFE, OBJID_MENU = 0xFFFFFFFD, OBJID_CLIENT = 0xFFFFFFFC, OBJID_VSCROLL = 0xFFFFFFFB, OBJID_HSCROLL = 0xFFFFFFFA, OBJID_SIZEGRIP = 0xFFFFFFF9, OBJID_CARET = 0xFFFFFFF8, OBJID_CURSOR = 0xFFFFFFF7, OBJID_ALERT = 0xFFFFFFF6, OBJID_SOUND = 0xFFFFFFF5 } AccObject

Selection actions are identified by
this type:

typedef enum { ACC_SEL_NONE = 0, ACC_SEL_TAKEFOCUS = 1, ACC_SEL_TAKESELECTION = 2, ACC_SEL_EXTENDSELECTION = 4, ACC_SEL_ADDSELECTION = 8, ACC_SEL_REMOVESELECTION = 16 } AccSelectionFlags

States are represented by the following:

#define ACC_STATE_SYSTEM_ALERT_HIGH 0×00000001 #define ACC_STATE_SYSTEM_ALERT_MEDIUM 0×00000002 #define ACC_STATE_SYSTEM_ALERT_LOW 0×00000004 #define ACC_STATE_SYSTEM_ANIMATED 0×00000008 #define ACC_STATE_SYSTEM_BUSY 0×00000010 #define ACC_STATE_SYSTEM_CHECKED 0×00000020 #define ACC_STATE_SYSTEM_COLLAPSED 0×00000040 #define ACC_STATE_SYSTEM_DEFAULT 0×00000080 #define ACC_STATE_SYSTEM_EXPANDED 0×00000100 #define ACC_STATE_SYSTEM_EXTSELECTABLE 0×00000200 #define ACC_STATE_SYSTEM_FLOATING 0×00000400 #define ACC_STATE_SYSTEM_FOCUSABLE 0×00000800 #define ACC_STATE_SYSTEM_FOCUSED 0×00001000 #define ACC_STATE_SYSTEM_HOTTRACKED 0×00002000 #define ACC_STATE_SYSTEM_INVISIBLE 0×00004000 #define ACC_STATE_SYSTEM_MARQUEED 0×00008000 #define ACC_STATE_SYSTEM_MIXED 0×00010000 #define ACC_STATE_SYSTEM_MULTISELECTABLE 0×00020000 #define ACC_STATE_SYSTEM_OFFSCREEN 0×00040000 #define ACC_STATE_SYSTEM_PRESSED 0×00080000 #define ACC_STATE_SYSTEM_PROTECTED 0×00100000 #define ACC_STATE_SYSTEM_READONLY 0×00200000 #define ACC_STATE_SYSTEM_SELECTABLE 0×00400000 #define ACC_STATE_SYSTEM_SELECTED 0×00800000 #define ACC_STATE_SYSTEM_SELFVOICING 0×01000000 #define ACC_STATE_SYSTEM_UNAVAILABLE 0×02000000

Event identifiers that can be sent via Accessible#notify_event are
as follows:

#define ACC_EVENT_SYSTEM_SOUND 0×0001 #define ACC_EVENT_SYSTEM_ALERT 0×0002 #define ACC_EVENT_SYSTEM_FOREGROUND 0×0003 #define ACC_EVENT_SYSTEM_MENUSTART 0×0004 #define ACC_EVENT_SYSTEM_MENUEND 0×0005 #define ACC_EVENT_SYSTEM_MENUPOPUPSTART 0×0006 #define ACC_EVENT_SYSTEM_MENUPOPUPEND 0×0007 #define ACC_EVENT_SYSTEM_CAPTURESTART 0×0008 #define ACC_EVENT_SYSTEM_CAPTUREEND 0×0009 #define ACC_EVENT_SYSTEM_MOVESIZESTART 0×000A #define ACC_EVENT_SYSTEM_MOVESIZEEND 0×000B #define ACC_EVENT_SYSTEM_CONTEXTHELPSTART 0×000C #define ACC_EVENT_SYSTEM_CONTEXTHELPEND 0×000D #define ACC_EVENT_SYSTEM_DRAGDROPSTART 0×000E #define ACC_EVENT_SYSTEM_DRAGDROPEND 0×000F #define ACC_EVENT_SYSTEM_DIALOGSTART 0×0010 #define ACC_EVENT_SYSTEM_DIALOGEND 0×0011 #define ACC_EVENT_SYSTEM_SCROLLINGSTART 0×0012 #define ACC_EVENT_SYSTEM_SCROLLINGEND 0×0013 #define ACC_EVENT_SYSTEM_SWITCHSTART 0×0014 #define ACC_EVENT_SYSTEM_SWITCHEND 0×0015 #define ACC_EVENT_SYSTEM_MINIMIZESTART 0×0016 #define ACC_EVENT_SYSTEM_MINIMIZEEND 0×0017 #define ACC_EVENT_OBJECT_CREATE 0×8000 #define ACC_EVENT_OBJECT_DESTROY 0×8001 #define ACC_EVENT_OBJECT_SHOW 0×8002 #define ACC_EVENT_OBJECT_HIDE 0×8003 #define ACC_EVENT_OBJECT_REORDER 0×8004 #define ACC_EVENT_OBJECT_FOCUS 0×8005 #define ACC_EVENT_OBJECT_SELECTION 0×8006 #define ACC_EVENT_OBJECT_SELECTIONADD 0×8007 #define ACC_EVENT_OBJECT_SELECTIONREMOVE 0×8008 #define ACC_EVENT_OBJECT_SELECTIONWITHIN 0×8009 #define ACC_EVENT_OBJECT_STATECHANGE 0×800A #define ACC_EVENT_OBJECT_LOCATIONCHANGE 0×800B #define ACC_EVENT_OBJECT_NAMECHANGE 0×800C #define ACC_EVENT_OBJECT_DESCRIPTIONCHANGE 0×800D #define ACC_EVENT_OBJECT_VALUECHANGE 0×800E #define ACC_EVENT_OBJECT_PARENTCHANGE 0×800F #define ACC_EVENT_OBJECT_HELPCHANGE 0×8010 #define ACC_EVENT_OBJECT_DEFACTIONCHANGE 0×8011 #define ACC_EVENT_OBJECT_ACCELERATORCHANGE 0×8012

## Methods

- Accessible.new
- Accessible#do_default_action
- Accessible#get_child
- Accessible#get_child_count
- Accessible#get_default_action
- Accessible#get_description
- Accessible#get_focus
- Accessible#get_help_text
- Accessible#get_keyboard_shortcut
- Accessible#get_location
- Accessible#get_name
- Accessible#get_parent
- Accessible#get_role
- Accessible#get_selections
- Accessible#get_state
- Accessible#get_value
- Accessible#get_window
- Accessible#hit_test
- Accessible#navigate
- Accessible#notify_event
- Accessible#select
- Accessible#set_window

### Accessible.new

Accessible.new(%(arg-type)Window% win = nil)

Constructor, taking an optional window. The object can be associated with
a window later.

destructor()

Destructor.

### Accessible#do_default_action

AccStatus do_default_action(%(arg-type)Integer% childId)

Performs the default action for the object. childId is 0 (the action for this object)
or greater than 0 (the action for a child). Return ACC_NOT_SUPPORTED if there
is no default action for this window (e.g. an edit control).

### Accessible#get_child

AccStatus get_child(%(arg-type)Integer% childId, Accessible child)

Gets the specified child (starting from 1). If child is NULL and the return value is ACC_OK,
this means that the child is a simple element and not an accessible object.

### Accessible#get_child_count

AccStatus get_child_count(%(arg-type)Integer% childCount)

Returns the number of children in childCount.

### Accessible#get_default_action

AccStatus get_default_action(%(arg-type)Integer% childId, String actionName)

Gets the default action for this object (0) or a child (greater than 0).
Return ACC_OK even if there is no action. actionName is the action, or the empty
string if there is no action. The retrieved string describes the action that is performed on an object,
not what the object does as a result. For example, a toolbar button that prints
a document has a default action of “Press” rather than “Prints the current document.”

### Accessible#get_description

AccStatus get_description(%(arg-type)Integer% childId, String description)

Returns the description for this object or a child.

### Accessible#get_focus

AccStatus get_focus(%(arg-type)Integer% childId, Accessible child)

Gets the window with the keyboard focus. If childId is 0 and child is NULL, no object in
this subhierarchy has the focus. If this object has the focus, child should be ‘this’.

### Accessible#get_help_text

AccStatus get_help_text(%(arg-type)Integer% childId, String helpText)

Returns help text for this object or a child, similar to tooltip text.

### Accessible#get_keyboard_shortcut

AccStatus get_keyboard_shortcut(%(arg-type)Integer% childId, String shortcut)

Returns the keyboard shortcut for this object or child.
Return e.g. ALT+K.

### Accessible#get_location

AccStatus get_location(%(arg-type)Rect% rect, Integer elementId)

Returns the rectangle for this object (id is 0) or a child element (id is greater than 0).
rect is in screen coordinates.

### Accessible#get_name

AccStatus get_name(%(arg-type)Integer% childId, String name)

Gets the name of the specified object.

### Accessible#get_parent

AccStatus get_parent(%(arg-type)Accessible% parent)

Returns the parent of this object, or NULL.

### Accessible#get_role

AccStatus get_role(%(arg-type)Integer% childId, AccRole role)

Returns a role constant describing this object. See Accessible for a list
of these roles.

### Accessible#get_selections

AccStatus get_selections(%(arg-type)Variant% selections)

Gets a variant representing the selected children
of this object.

Acceptable values are:

- a null variant (IsNull() returns TRUE)
- a list variant (GetType() == T(“list”))
- an integer representing the selected child element,
  or 0 if this object is selected (GetType() == T(“long”))
- a “void*” pointer to a Accessible child object

### Accessible#get_state

AccStatus get_state(%(arg-type)Integer% childId, Integer state)

Returns a state constant. See Accessible for a list
of these states.

### Accessible#get_value

AccStatus get_value(%(arg-type)Integer% childId, String strValue)

Returns a localized string representing the value for the object
or child.

### Accessible#get_window

Window get_window()

Returns the window associated with this object.

### Accessible#hit_test

AccStatus hit_test(%(arg-type)Point% pt, Integer childId, Accessible childObject)

Returns a status value and object id to indicate whether the given point was on this or
a child object. Can return either a child object, or an integer
representing the child element, starting from 1.

pt is in screen coordinates.

### Accessible#navigate

AccStatus navigate(%(arg-type)NavDir% navDir, Integer fromId, Integer toId, Accessible toObject)

Navigates from fromId to toId_/_toObject.

### Accessible#notify_event

notify_event(%(arg-type)Integer% eventType, Window window, AccObject objectType, Integer objectType)

Allows the application to send an event when something changes in an accessible object.

### Accessible#select

AccStatus select(%(arg-type)Integer% childId, AccSelectionFlags selectFlags)

Selects the object or child. See Accessible for a list
of the selection actions.

### Accessible#set_window

set_window(%(arg-type)Window% window)

Sets the window associated with this object.

[This page automatically generated from the Textile source at 2023-06-09 00:45:30 +0000]