Share via

Object State Constants

  • Article

The following values, defined in oleacc.h, describe the states of objects. An object is associated with one or more of these state values at any time. The following object state constants are not used: STATE_SYSTEM_ALERT_HIGH, STATE_SYSTEM_ALERT_MEDIUM, STATE_SYSTEM_ALERT_LOW, and STATE_SYSTEM_FLOATING.

Clients retrieve an object's state by calling IAccessible::get_accState, which returns an integer that is a combination of the following bit flags. Clients call GetStateText with the state value to retrieve a localized string that describes the object's state.

When the state of an object changes, servers should call NotifyWinEvent with the EVENT_OBJECT_STATECHANGE WinEvent. However, objects with the STATE_SYSTEM_INVISIBLE, STATE_SYSTEM_FOCUSED, and STATE_SYSTEM_ SELECTED object state constants have their own WinEvents. For these objects, do not use EVENT_OBJECT_STATECHANGE. Instead, use the individual WinEvents. For more information, see STATE_SYSTEM_INVISIBLE, STATE_SYSTEM_FOCUSED, and STATE_SYSTEM_SELECTED.

The following are object state constants:

  • STATE_SYSTEM_ALERT_HIGH
    (This object state constant is not supported.)

    Indicates important information to convey immediately to the user. For example, when a battery-level indicator reaches a critically low level, it generates a high-level alert. As a result, a blind access utility announces this information immediately to the user, and a screen magnification program scrolls the screen so that the battery indicator is in view. This state is also appropriate for any prompt or operation that must be completed before the user can continue.

  • STATE_SYSTEM_ALERT_MEDIUM
    (This object state constant is not supported.)

    Indicates important information that is not conveyed immediately to the user. For example, when a battery-level indicator is starting to reach a low level, it generates a medium-level alert. A blind access utility then generates 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_ALERT_LOW
    (This object state constant is not supported.)

    Indicates low-priority information that is not important to the user. This state is used, for example, when Word changes the appearance of the TipWizard button on its toolbar to indicate that it has a hint for the user.

  • STATE_SYSTEM_ANIMATED
    The object's appearance changes rapidly or constantly. Graphics that are occasionally animated are described as ROLE_SYSTEM_GRAPHIC with the State property set to STATE_SYSTEM_ANIMATED. This state is used to indicate that the object's location is changing.

  • STATE_SYSTEM_BUSY
    The control cannot accept input at this time.

  • STATE_SYSTEM_CHECKED
    The object's check box is selected.

  • STATE_SYSTEM_COLLAPSED
    Children of this object that have the ROLE_SYSTEM_OUTLINEITEM role are hidden.

  • STATE_SYSTEM_DEFAULT
    This state represents the default button in a window.

  • STATE_SYSTEM_EXPANDED
    Children of this object that have the ROLE_SYSTEM_OUTLINEITEM role are displayed.

  • STATE_SYSTEM_EXTSELECTABLE
    Indicates that an object extends its selection using SELFLAG_EXTENDSELECTION in the IAccessible::accSelect method.

  • STATE_SYSTEM_FLOATING
    (This object state constant is not supported.)

    The object is not clipped to the boundary of its parent object and does not move automatically when the parent moves.

  • STATE_SYSTEM_FOCUSABLE
    The object is on the active window and is ready to receive keyboard focus.

  • STATE_SYSTEM_FOCUSED
    The object has the keyboard focus. Do not confuse object focus with object selection. For more information, see Selection and Focus Properties and Methods. For objects with this object state, send EVENT_OBJECT_SHOW, or EVENT_OBJECT_HIDE WinEvents to notify client applications about state changes. Do not use EVENT_OBJECT_STATECHANGE.

  • STATE_SYSTEM_HASPOPUP
    Object displays a pop-up menu or window when invoked.

  • STATE_SYSTEM_HOTTRACKED
    The object is hot-tracked by the mouse, which means that its appearance has changed to indicate that the mouse pointer is located over it.

  • STATE_SYSTEM_INVISIBLE
    The object is programmatically hidden. For example, menu itmes are programmatically hidden until a user activates the menu. Because objects with this state are not available to users, client applications should not communicate information about the object to users. However, if client applications find an object with this state, they should check to see if STATE_SYSTEM_OFFSCREEN is also set. If this second state is defined, then clients can communicate the information about the object to users. For example, a list box can have both STATE_SYSTEM_INVISIBLE and STATE_SYSTEM_OFFSCREEN set. In this case, the client application can communicate all items in the list to users.

    If a client application is navigating through an IAccessible tree and encounters a parent object that is invisible, Active Accessibility will not expose information about any possible children of the parent as long as the parent is invisible.

  • STATE_SYSTEM_LINKED
    Indicates that the object is formatted as a hyperlink. The object role will usually be ROLE_SYSTEM_TEXT.

  • STATE_SYSTEM_MARQUEED
    Indicates scrolling or moving text or graphics.

  • STATE_SYSTEM_MIXED
    Indicates that the state of a three-state check box or toolbar button is not determined. The check box is neither checked nor unchecked and is therefore in the third or mixed state.

  • STATE_SYSTEM_MOVEABLE
    Indicates that the object can be moved. For example, a user can click on the titlebar for the object and drag the object to a new location.

  • STATE_SYSTEM_MULTISELECTABLE
    Indicates that the object accepts multiple selected items; SELFLAG_ADDSELECTION for the IAccessible::accSelect method is valid.

  • STATE_SYSTEM_NORMAL
    Indicates that the object does not have another state assigned to it.

  • STATE_SYSTEM_OFFSCREEN
    The object is clipped, or scrolled out of view, but not programmatically hidden. If the user makes the viewport larger, more of the object will be visible on the computer screen.

  • STATE_SYSTEM_PRESSED
    The object is pressed.

  • STATE_SYSTEM_PROTECTED
    The object is a password-protected edit control.

  • STATE_SYSTEM_READONLY
    The object is designated read-only.

  • STATE_SYSTEM_SELECTABLE
    The object accepts selection.

  • STATE_SYSTEM_SELECTED
    The object is selected.

  • STATE_SYSTEM_SELFVOICING
    The object or child uses text-to-speech (TTS) technology for description purposes. A speech-based accessibility aid does not announce information when an object with this state has the focus because the object automatically announces information.

  • STATE_SYSTEM_SIZEABLE
    The object can be resized. For example, a user could change the size of a window by clicking the border with a mouse and dragging the mouse.

  • STATE_SYSTEM_TRAVERSED
    The object is a hyperlink that has been visited (previously clicked) by a user.

  • STATE_SYSTEM_UNAVAILABLE
    The object is unavailable.