This section contains information on the following constants and enumerated types used with Active Accessibility.
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.
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.
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.
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.
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.
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.