Share via

WinEvents

  • Article

Microsoft Active Accessibility provides a mechanism called WinEvents that allows the operating system and servers to notify clients when an accessible object changes. There are numerous conditions in which a server notifies a client of a change. Each event constant defined by Active Accessibility describes a condition about which a client is notified.

For example, WinEvents can signal:

  • When an object is created or destroyed.
  • When an object receives or loses focus.
  • When an object's state or location changes.
  • When any of an object's properties change.

Client applications do not receive event notifications automatically; they must specify which events they want to receive by calling SetWinEventHook. With SetWinEventHook, a client registers to receive one or more events and sets a hook function to handle the specified events. Clients can call SetWinEventHook more than once to register different hook functions. Also, clients may reuse the same hook function, or use a different hook function for additional event notifications.

Hook functions are located within the client's code body, in a dynamic-link library (DLL) mapped into the client's process, or in a DLL mapped into the server's process. Each of these methods has advantages and disadvantages. For more information, see In-Context and Out-of-Context Hook Functions.

To notify clients of an event occurrence, servers call NotifyWinEvent. The system checks whether any client applications have set hook functions for the event and calls the appropriate hook functions as necessary.

When the client's hook function is called, it receives a number of parameters that describe the event and the object that generated the event. To gain access to the object that generated the event, the client hook function calls AccessibleObjectFromEvent.

Note  If no clients have registered to receive WinEvents, the performance impact on a server for calling NotifyWinEvent is negligible.

Servers call NotifyWinEvent for changes only in their own accessible objects; they do not call NotifyWinEvent for changes in system-provided user interface elements.

Event-Driven Communication

Clients must register a WinEvent hook before they can receive WinEvent notifications. To avoid unnecessary callbacks and improve performance, clients are advised to register only for the events they need to receive.

Inside the hook procedure, the client can call AccessibleObjectFromEvent to retrieve an IAccessible object for the element to which the event applies. With this object, the client can begin calling IAccessible methods to retrieve information or interact with the UI element.