Constants and Enumerated Types


This section contains information on the following constants and enumerated types used with Active Accessibility.

Object Identifiers

The oleacc.dll dynamic-link library recognizes and provides the following standard object identifiers (defined in winable.h). The system reserves zero and all negative values for standard objects.

Clients will receive and use these values to identify parts of a window. Servers use these values to identify the corresponding parts of a window, but must provide positive values to identify any other objects they employ within an application.

OBJID_ALERT
Refers to an alert associated with a window or application.
OBJID_CARET
Refers to the text insertion bar (caret) in the window.
OBJID_CLIENT
Refers to the window's client area. In most cases, the operating system controls the frame elements and the client object contains all elements that the application controls. List boxes use OBJID_CLIENT for item notifications.
OBJID_CURSOR
Refers to the mouse pointer. There is only one mouse pointer in the system and it is not a child of any window.
OBJID_HSCROLL
Refers to the window's horizontal scroll bar.
OBJID_MENU
Refers to the window's menu bar.
OBJID_SIZEGRIP
Refers to the window's size grip, an optional frame component located at the lower right corner of the window frame.
OBJID_SOUND
Refers to a sound object. Sound objects do not have screen locations or children, but do have name and state attributes. They are children of the application playing the sound.
OBJID_SYSMENU
Refers to the window's system menu.
OBJID_TITLEBAR
Refers to the window's title bar.
OBJID_VSCROLL
Refers to the window's vertical scroll bar.
OBJID_WINDOW
Refers to the window itself rather than a child object.

Object Roles

The following values (defined in oleacc.h) describe the role of objects within an application.

ROLE_SYSTEM_ALERT
This is an alert object. This role should be used only for objects that embody an alert but are not associated with another object such as a graphic, text, or sound.
ROLE_SYSTEM_APPLICATION
This object appears to the user as a main window for an application.
ROLE_SYSTEM_BORDER
This object is a window border; because of implementation constraints, the entire border is represented by a single object, rather than by separate objects for each side.
ROLE_SYSTEM_BUTTONDROPDOWN
This object is a button that drops down a list of items.
ROLE_SYSTEM_BUTTONDROPDOWNGRID
This object is a button that drops down a grid.
ROLE_SYSTEM_BUTTONMENU
This object is a button that drops down a menu.
ROLE_SYSTEM_CARET
This is the system object for the caret.
ROLE_SYSTEM_CELL
This object is a cell within a table.
ROLE_SYSTEM_CHARACTER
This object is a social interaction character or agent.
ROLE_SYSTEM_CHART
This object is a graphical image used to represent data.
ROLE_SYSTEM_CHECKBUTTON
This object appears to the user to function as a check box control; that is, an option that can be turned on or off independently of other options.
ROLE_SYSTEM_CLIENT
This object is a window's client area.
ROLE_SYSTEM_COLUMN
This object is a column of cells within a table.
ROLE_SYSTEM_COLUMNHEADER
This object appears to the user to function as a column header, providing a visual label for a column in a table, and might allow the user to select or adjust values for the entire column.
ROLE_SYSTEM_COMBOBOX
This object appears to the user to function as a combo box; that is, a text box with an associated list box, which can be dropped, or not.
ROLE_SYSTEM_CURSOR
This is the system object for the mouse pointer.
ROLE_SYSTEM_DIAL
This object appears to the user as a dial or knob. This can be a read-only object as well, showing a value like a speedometer.
ROLE_SYSTEM_DIALOG
This object appears to the user to function as a dialog box or message box.
ROLE_SYSTEM_DOCUMENT
This object appears to the user as a document window. A document window is always contained within an application window. This applies only to multiple-document interface (MDI) windows and refers to the object that contains the MDI title bar, and so on.
ROLE_SYSTEM_DROPLIST
This object appears to the user to function as a drop-down list box; that is, it shows one item and allows the user to display and select another from a list of alternative values.
ROLE_SYSTEM_GRAPHIC
This object appears to the user as a picture.
ROLE_SYSTEM_GRIP
This object is a mouse pointer target that, when activated, causes something to happen for as long as the target is activated. For example, in Windows 95, the user can click and drag around a sizing grip in the lower-right corner of each window, thus resizing the window.
ROLE_SYSTEM_GROUPING
This object logically groups other objects. There might or might not be a parent-child relationship between the grouping object and the objects it contains.
ROLE_SYSTEM_HELP
This is an object that displays Help in the form of a ToolTip, quick tip or Help balloon.
ROLE_SYSTEM_HOTKEYFIELD
This object appears to the user to function as a hot-key field; that is, it allows the user to enter a combination or sequence of keystrokes, which are then described by the hot-key field.
ROLE_SYSTEM_LINK
This object is a link to something else. This object might look like text or a graphic, but acts like a button.
ROLE_SYSTEM_LIST
This object appears to the user to function as a list box, allowing the user to choose between one or more choices.
ROLE_SYSTEM_LISTITEM
This object functions as an item in a list box or the list portion of a combo box, drop-down list box, or drop-down combo box.
ROLE_SYSTEM_MENUBAR
This is the menu "bar" usually located under the title bar.
ROLE_SYSTEM_MENUITEM
This object appears to the user to function as a menu item; that is, an entry in a menu that the user can choose to carry out a command, select an option, or display another menu. (Functionally, a menu item can be equivalent to a push button, radio button, check box, or menu.)
ROLE_SYSTEM_MENUPOPUP
This object appears to the user to function as a menu; that is, a window that can appear or disappear depending on some user action, and which displays a list of choices.
ROLE_SYSTEM_OUTLINE
This object appears to the user to function as an outline or tree structure, possibly allowing the user to expand and collapse branches.
ROLE_SYSTEM_OUTLINEITEM
This object is an item in an outline or tree.
ROLE_SYSTEM_PAGETAB
This object appears to the user to function as a page tab. Normally the only child of a pagetab control is a ROLE_SYSTEM_GROUPING object that contains the contents of the associated page.
ROLE_SYSTEM_PANE
This object appears to the user to act as a pane within a frame or document window. These objects are areas of a window that have separate contents from other areas of the window. Additionally, users can navigate between panes and within the contents of the current pane, but cannot magically navigate between items in different panes. Thus, panes represent a level of grouping lower than frame windows or documents, but above individual controls. Typically the user navigates between panes by pressing TAB, F6, or CTRL+TAB, depending on the context.
ROLE_SYSTEM_PROGRESSBAR
This object appears to the user to function as a progress bar, dynamically showing the user the percent complete of an operation in progress. This control usually takes no user input.
ROLE_SYSTEM_PUSHBUTTON
This object appears to the user to function as a push button control.
ROLE_SYSTEM_RADIOBUTTON
This object appears to the user to function as an option button (also called a radio button); that is, one of a group of mutually exclusive options. All objects sharing a single parent that have this attribute are assumed to be part of single mutually exclusive group; You can use ROLE_SYSTEM_GROUPING objects to divide them into separate groups when necessary.
ROLE_SYSTEM_ROW
This object is a row of cells within a table.
ROLE_SYSTEM_ROWHEADER
This object appears to the user to function as a row header, providing a visual label for a table row, and might allow the user to select or adjust values for the entire row.
ROLE_SYSTEM_SCROLLBAR
This object is a vertical or horizontal scroll bar, either part of the client area or used in a control.
ROLE_SYSTEM_SEPARATOR
This is any object used to visually divide a space into two regions, such as a separator menu item or a bar dividing split panes within a window.
ROLE_SYSTEM_SLIDER
This object appears to the user to function as a slider, allowing the user to adjust a setting in given increments between given minimum and maximum values.
ROLE_SYSTEM_SOUND
This object is a system sound, associated with various system events.
ROLE_SYSTEM_SPINBUTTON
This object appears to the user to function as a spin box; that is, a control that allows the user to select next and previous (or "higher" and "lower") values from a list of appropriate values. The value can be displayed in a separate control ("buddy control") associated with the spin box.
ROLE_SYSTEM_STATICTEXT
This object appears to the user as static text. You cannot modify or select static text.
ROLE_SYSTEM_STATUSBAR
This object appears to the user to function as a status bar; that is, an area that displays information about the current operation, state of the application, or selected object. The status bar can have multiple fields, and can show different sets of one or more values.
ROLE_SYSTEM_TABLE
This object is a table containing rows and columns of cells, and optionally row headers and column headers.
ROLE_SYSTEM_TEXT
This object appears to the user as text that can be selected. It can be editable or read-only.
ROLE_SYSTEM_TITLEBAR
This object is a title or caption bar for the application.
ROLE_SYSTEM_TOOLBAR
This object appears to the user to function as a toolbar; that is, a grouping of controls that remains visible on the screen or within a window.
ROLE_SYSTEM_WINDOW
This object is the window frame, which usually consists of child objects such as a title bar, client, and so on.

Object State Constants

The following values (defined in oleacc.h) describe the states of objects within an application.

STATE_SYSTEM_ALERT_HIGH
It is important that this information be conveyed to the user immediately. For example, a battery level indicator reaching a critical level conveys truly urgent information, so a blind access utility should announce this information immediately, and a screen magnification program should scroll the screen so that this indicator is in view. This is also appropriate for any prompt or operation that must be completed before the user can continue.
STATE_SYSTEM_ALERT_LOW
This information is of low priority, so the user need not be immediately informed that it occurred; this can be a user option provided by the accessibility aid. For example, when Microsoft Word changes the appearance of the TipWizard button on its toolbar to indicate that it has a hint for the user, some users might want to know about this but others might not. Another example is helpful information that appears on an application's status bar when the user is in the middle of an operation.
STATE_SYSTEM_ALERT_MEDIUM
The user should be informed that this information is available, but the informational content need not be conveyed immediately. For example, when a battery level indicator reaches a low level, it should generate a medium-level alert. Blind access utilities could then generate a sound to let the user know that important information is available, without actually interrupting the user's work. The user could then query the alert information at his or her leisure.
STATE_SYSTEM_ANIMATED
Object's appearance is changing rapidly or constantly. (This alert should not be used if the object's location alone is changing.)
STATE_SYSTEM_BUSY
Control cannot accept input at this time.
STATE_SYSTEM_CHECKED
Object's check box is selected.
STATE_SYSTEM_COLLAPSED
Objects within this object that have the ROLE_SYSTEM_OUTLINEITEM role are hidden.
STATE_SYSTEM_DEFAULT
Default button or menu item.
STATE_SYSTEM_EXPANDED
Objects within this object that have the ROLE_SYSTEM_OUTLINEITEM role are displayed.
STATE_SYSTEM_EXTSELECTABLE
Object can extend its selection using SELFLAG_EXTENDSELECTION in the IAccessible::accSelect method.
STATE_SYSTEM_FLOATING
Object is not clipped to the boundary of its parent object, and is not assumed to move automatically when the parent moves. An event must be sent whenever the object changes location in screen coordinates; if an object does not have this attribute, an event must be triggered only when it moves relative to its parent.
STATE_SYSTEM_FOCUSABLE
Object can accept the input focus.
STATE_SYSTEM_FOCUSED
Item is focused. Do not confuse object focus with object selection. For more information, see Accessible Object Selection and Focus
STATE_SYSTEM_HOTTRACKED
Item is hot-tracked by the mouse, meaning that it has a special appearance used to indicate the mouse pointer is located over it.
STATE_SYSTEM_INVISIBLE
Object is hidden or invisible. This attribute is used for objects which currently not visible. Object which are never visible should be set as STATE_SYSTEM_OFFSCREEN. This state only reflects the items which are known to be invisible by the application. An object can be considered visible - the STATE_SYSTEM_INVISIBLE flag is not set - and yet be obscured by another application and not be visible to the user. For example, a object that appears in the main window of an application might be obsurced by a dialog. This object is considered visible. However, a list of files names in a list box might contain several hundred names, but only a few are visible to the user. The rest are clipped by the parent and should have STATE_SYSTEM_INVISIBLE set.
STATE_SYSTEM_MARQUEED
Scrolling or moving text.
STATE_SYSTEM_MIXED
Three-state check box or toolbar button.
STATE_SYSTEM_MULTISELECTABLE
Object can accept multiple selected items (that is, SELFLAG_ADDSELECTION for the IAccessible::accSelect method is valid).
STATE_SYSTEM_OFFSCREEN
This object has no on-screen representation. A sound or alert object would have this state.
STATE_SYSTEM_PRESSED
Item is pressed.
STATE_SYSTEM_READONLY
Item is read-only.
STATE_SYSTEM_SELECTABLE
Object can accept selection.
STATE_SYSTEM_SELECTED
Item is currently selected.
STATE_SYSTEM_SELFVOICING
Object or child can use Text To Speech (TTS) to voice itself. A speech-based accessibility aid would be advised not to announce information when this object is focused. This would be very frequent, and would be very distracting. However, when the focus is not on this object and it is referenced, the accessibility aid can provide information about the object for screen review purposes.
STATE_SYSTEM_UNAVAILABLE
Object is unavailable.

Navigation Constants

The following values (defined in oleacc.h) indicate physical or logical directions when navigating from one location or object to another by using the IAccessible::accNavigate method.

NAVDIR_DOWN
Locations or objects physically below the current one.
NAVDIR_FIRSTCHILD
Go to the first child of this object.
NAVDIR_LASTCHILD
Go to the last child of this object.
NAVDIR_LEFT
Locations or objects physically to the left of the current one.
NAVDIR_NEXT
The next logical location or object, generally a "sibling" to the current object. This ordering should be the navigational order, although in some cases it can represent logical relationships. It should always seem reasonable to the user. It is not necessarily the indexing order used with child. For example, in a dialog box, the TAB key takes you to the next logical control, although this can be represented in any number of different physical directions.
NAVDIR_PREVIOUS
The previous logical location or object. This ordering should be the navigational order, although in some cases it can represent logical relationships. It should always seem reasonable to the user. It is not necessarily the indexing order used with child. In a dialog box, the SHIFT+TAB key combination takes you to the previous logical control, although this might be in any number of physical directions visually on the screen. For example, in vertical toolbars, logically the previous button is often the button physically above (NAVDIR_UP) the current one, whereas in horizontal toolbars, logically the previous button is generally the button physically to the left (NAVDIR_LEFT) of the current one.
NAVDIR_RIGHT
Locations or objects physically to the right of the current one.
NAVDIR_UP
Locations or objects physically above the current one.

Return Values

This table lists the values that all the IAccessible interface methods can return.

DISP_E_MEMBERNOTFOUND
The current object does not support the requested property or action. For example, a push button returns this value if you request its Value property, since it has none.
E_INVALIDARG
One or more arguments was invalid. This error can occur when the caller attempts to identify a child object using an identifier that the server doesn't support (child ID when the server uses strings, or vice versa). This error can also result when a client attempts to identify a child object within an object that has no children.
E_FAIL
An unknown or generic error occurred.
E_NOTIMPL
The method is not implemented. This value can occur when a client calls a method that isn't yet supported in that operating system.
E_OUTOFMEMORY
The method was unable to allocate memory required to complete an operation crucial to its success.
S_FALSE
The method succeeded in part. This can happen when the method itself succeeded, but the requested information isn't available. For example, this return value will result if you call the IAccessible::accHitTest method to retrieve a child object at a given point and the specified point is not within the parent object.
S_OK
The method succeeded.

Like all COM error codes, you can use the SUCCEEDED and FAILED macros to test the HRESULT return values that Active Accessibility API elements return. Although these macros provide a simple way to test for a method's overall success or failure, always check the output parameters that you pass with a method call. For example, when one of a method's output parameters is a pointer, you can get a successful return value (such as S_FALSE) but still receive a NULL pointer in an output parameter.

SELFLAG

typedef enum tagSELFLAG
{
    SELFLAG_NONE            = 0,
    SELFLAG_TAKEFOCUS       = 1,
    SELFLAG_TAKESELECTION   = 2,
    SELFLAG_EXTENDSELECTION = 4,
    SELFLAG_ADDSELECTION    = 8,
    SELFLAG_REMOVESELECTION = 16
} SELFLAG;

Describes how an accessible object will become selected or take focus. These values are used with the IAccessible::accSelect method.

SELFLAG_NONE
Used only to test for argument validity.
SELFLAG_TAKEFOCUS
The object will take the input focus and become the selection anchor. This value does not alter the selection unless specified by other flags, so it is useful when altering the input focus without changing the selection itself (that is, moving the focus by pressing the arrow keys while holding down the CTRL key in File Manager or a Windows 95® folder, or maneuvering the input-focus cell in a multicell selection within a spreadsheet application such as Microsoft Excel).
To select a range of objects and put the focus on the last object: This requires two calls: in the first, specify the SELFLAG_TAKEFOCUS on the starting object; in the second, specify a combination of the SELFLAG_EXTENDSELECTION and SELFLAG_TAKEFOCUS on the last object.
SELFLAG_TAKESELECTION
The object becomes the only selected object in the container. Valid flag combinations are:
NONE
TAKE FOCUS
TAKE SELECTION
ADD SELECTION
REMOVE SELECTION
EXTEND SELECTION
TAKE FOCUS and TAKE SELECTION
TAKE FOCUS and ADD SELECTION
TAKE FOCUS and REMOVE SELECTION
TAKE FOCUS and EXTEND SELECTION
ADD SELECTION and EXTEND SELECTION
REMOVE SELECTION and EXTEND SELECTION
TAKE FOCUS, ADD SELECTION, and EXTEND SELECTION
TAKE FOCUS, REMOVE SELECTION, and EXTEND SELECTION
Invalid flag combinations are:
ADDSELECTION and REMOVESELECTION
ADDSELECTION and TAKESELECTION
REMOVESELECTION and TAKESELECTION
EXTENDSELECTION and TAKESELECTION
SELFLAG_EXTENDSELECTION
The current selection will be logically extended to include this object. If specified with SELFLAG_ADDSELECTION, all objects logically between the current anchor and the selection become selected. If specified with SELFLAG_REMOVESELECTION, the selection of those objects is canceled. If neither SELFLAG_ADDSELECTION nor SELFLAG_REMOVESELECTION are specified, all objects logically between the current anchor and the selection take on the anchor object's selection state. That is, the objects are added to or removed from the selection depending on the state of the object at the selection anchor (that is, adding or removing items by pressing SHIFT+CLICK or SHIFT+SPACE selection in File Manager, a Windows 95 folder, or an extended-selection list box).
SELFLAG_ADDSELECTION
Not valid with SELFLAG_REMOVESELECTION. The current object will be added individually to the current selection, possibly resulting in a disjoint selection (that is, adding or removing items by pressing CTRL+CLICK or CTRL+SPACE selection of an unselected object in a multiselect list box or in the Windows Explorer).
SELFLAG_REMOVESELECTION
Not valid with SELFLAG_ADDSELECTION. The current object will be removed individually from the current selection, and might result in a noncontiguous selection (that is, adding or removing items by pressing CTRL+CLICK or CTRL+SPACE selection of a selected object in a multiselect list box or in the Windows Explorer).

© 1997 Microsoft Corporation. All rights reserved. Legal Notices.