* AT-SPI - Assistive Technology Service Provider Interface
* (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
*
- * Copyright 2001 Sun Microsystems Inc.
+ * Copyright 2001, 2002 Sun Microsystems Inc.
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public
#ifndef __ACCESSIBILITY_EVENT_DEFINED__
#define __ACCESSIBILITY_EVENT_DEFINED__
-#include <Bonobo.idl>
-
module Accessibility
{
interface Accessible;
+ /**
+ * A struct encapsulating detailed information about an Event.
+ * This struct supercedes the previous use of the 'any' field
+ * in EventDetails; the content previously stored in Event::any_data
+ * is now stored in EventDetails::any_data, and Event::any_data
+ * points to an instance of the EventDetails structure, if
+ * the object's implementation supports event detail reporting,
+ * otherwise Event::any_data contains CORBA_OBJECT_NIL.
+ *
+ * @since AT-SPI 1.7.0
+ */
+ struct EventDetails {
+ Application host_application;
+ Role source_role;
+ string source_name;
+ any any_data;
+ };
+
+ /**
+ * A structure encapsulating information about an event
+ * for which notification was requested. Usually such notification
+ * is requested via a call to Registry::registerGlobalEventListener.
+ * The structure contains a colon-delimited string indicating the event
+ * type, a reference to the generating Accessible, two detail fields whose
+ * interpretation is event-type-specific, and a final field containing
+ * event-type-specific data.
+ *
+ * @note Since AT-SPI 1.7.0 the 'any' field contains an EventDetails
+ * struct, which encapsulates additional information about the event
+ * and its generating object.
+ */
struct Event {
- string type;
- Accessible target;
- long detail1;
- long detail2;
+ /** A colon-delimited string indicating the type of the event.
+ * The string can be interpreted as
+ * \c class:type:subtype
+ * For instance ¨object:text-changed:insert¨ is an event
+ * from the 'Object' class, which corresponds to Accessible objects
+ * general, the type of the event is a ¨text-changed¨ event (i.e. a change in the
+ * content of an implementor of the Text interface), and the
+ * specific subtype of the change is an insertion event.
+ *
+ * Event classes include the following:
+ * \li focus: an object has received keyboard focus. This event has no type or subtype.
+ * \li window: a toplevel window has changed state.
+ * \li object: an object (i.e. Accessible) has undergone some change in state, content,
+ * or hierarchy
+ * \li document:a change to a document's content has occurred, or its
+ * content loading status has changed.
+ * \li mouse: an event originating from the pointing device. Rarely used;
+ * in most cases clients will wish to register for pointer events via
+ * the DeviceEventController::registerDeviceEvent method instead.
+ * \li keyboard: an event indicating that the keyboard state (for example, the
+ * modifier state) has changed significantly.
+ * "keyboard:" events are not sent for individual keystrokes except as
+ * a side-effect of certain keys, for instance modifier keys.
+ * Clients interested in key events should listen for DeviceEvents
+ * via DeviceEventController::registerKeystrokeListener instead.
+ *
+ * @note For more information on specific event types, see the documentation for
+ * each of the individual interfaces supported by some Accessible objects.
+ *
+ * @see Accessible, Component, Image, Selection, Table, Text, Value.
+ */
+ string type;
+ /**
+ * The Accessible object which is the source of the event. The source object is the object
+ * to which the change inferred by the event emission occurs; for instance,
+ * the object emitting a ¨object:parent-changed¨ event is the child, not the parent.
+ * Likewise, the event source of an ¨object:children-changed:insert¨ event is the parent,
+ * not the inserted child.
+ */
+ Accessible source;
+ /** An integer whose meaning is event type dependent. It may indicate the offset of
+ * text being inserted, in the case of ¨object:text-changed:insert¨, or the index of a
+ * newly added child in the case of ¨object:children-changed:add¨.
+ * @note since most AT-SPI clients react to events via an asynchronous queue, for
+ * performance reasons, this field may be of limited utility unless the client maintains
+ * a large client-side cache of the hierarchy and contained data. This is because by the time
+ * such an event is asynchronously processed, the state of the originating object may have
+ * changed. In other words, the data in the detail1 member is not state-coherent outside
+ * of the event handler. More useful results are gotten by examination of the 'any_data' field.
+ */
+ long detail1;
+ /** see description of detail2 */
+ long detail2;
+ /**
+ * A generic storage location for event-type-specific data which provides more specific
+ * information about the event; for instance, in AT-SPI versions prior to 1.7.0,
+ * in the case of ¨object:text-changed:insert¨ events, this field contains a string
+ * indicating the inserted text.
+ *
+ * @note Since AT-SPI 1.7.0, the data contained in this field is an EventDetails struct.
+ */
+ any any_data;
};
+ /**
+ * A generic interface implemented by objects for the
+ * receipt of event notifications. EventListener is the interface from which
+ * Accessibility::Registry is derived, and via which clients of the Registry
+ * receive notification of changes to an application's user interface and content.
+ */
interface EventListener : Bonobo::Unknown {
- oneway void notifyEvent (in Event e);
- };
+ /**
+ * Synchronously notify an EventListener that an event has occurred, by passing it an
+ * Event struct.
+ * @param e The Event about which the listener is being notified.
+ */
+ void notifyEvent (in Event e);
+/** \cond */
+ void unImplemented_ ();
+ void unImplemented2_ ();
+ void unImplemented3_ ();
+ void unImplemented4_ ();
+/** \endcond */
+ };
};
#endif
projects / platform / core / uifw / at-spi2-atk.git / blobdiff