idl/Accessibility_Event.idl

   1 /*
   2  * AT-SPI - Assistive Technology Service Provider Interface
   3  * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
   4  *
   5  * Copyright 2001, 2002 Sun Microsystems Inc.
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Library General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Library General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Library General Public
  18  * License along with this library; if not, write to the
  19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22
  23 #ifndef __ACCESSIBILITY_EVENT_DEFINED__
  24 #define __ACCESSIBILITY_EVENT_DEFINED__
  25
  26 #include <Bonobo_Unknown.idl>
  27
  28 module Accessibility
  29 {
  30   interface Accessible;
  31
  32   /**
  33    * A struct encapsulating detailed information about an Event.
  34    * This struct supercedes the previous use of the 'any' field
  35    * in EventDetails; the content previously stored in Event::any_data
  36    * is now stored in EventDetails::any_data, and Event::any_data
  37    * points to an instance of the EventDetails structure, if
  38    * the object's implementation supports event detail reporting,
  39    * otherwise Event::any_data contains CORBA_OBJECT_NIL.
  40    *
  41    * @since AT-SPI 1.7.0
  42    */
  43   struct EventDetails {
  44       Application host_application;
  45       Role        source_role;
  46       string      source_name;
  47       any         any_data;
  48   };
  49
  50   /**
  51    * A structure encapsulating information about an event
  52    * for which notification was requested.  Usually such notification
  53    * is requested via a call to Registry::registerGlobalEventListener.
  54    * The structure contains a colon-delimited string indicating the event
  55    * type, a reference to the generating Accessible, two detail fields whose
  56    * interpretation is event-type-specific, and a final field containing
  57    * event-type-specific data.
  58    *
  59    * @note Since AT-SPI 1.7.0 the 'any' field contains an EventDetails
  60    * struct, which encapsulates additional information about the event
  61    * and its generating object.
  62    */
  63   struct Event {
  64     /** A colon-delimited string indicating the type of the event.
  65      *  The string can be interpreted as
  66      *  \c class:type:subtype
  67      *  For instance ¨object:text-changed:insert¨ is an event
  68      *  from the 'Object' class, which corresponds to Accessible objects
  69      *  general, the type of the event is a ¨text-changed¨ event (i.e. a change in the
  70      *  content of an implementor of the Text interface), and the
  71      *  specific subtype of the change is an insertion event.
  72      *
  73      *  Event classes include the following:
  74      *  \li focus:   an object has received keyboard focus.  This event has no type or subtype.
  75      *  \li window:  a toplevel window has changed state.
  76      *  \li object:  an object (i.e. Accessible) has undergone some change in state, content,
  77      *               or hierarchy
  78      *  \li document:a change to a document's content has occurred, or its
  79      *               content loading status has changed.
  80      *  \li mouse:   an event originating from the pointing device.  Rarely used;
  81      *               in most cases clients will wish to register for pointer events via
  82      *               the DeviceEventController::registerDeviceEvent method instead.
  83      *  \li keyboard: an event indicating that the keyboard state (for example, the
  84      *               modifier state) has changed significantly.
  85      *               "keyboard:" events are not sent for individual keystrokes except as
  86      *               a side-effect of certain keys, for instance modifier keys.
  87      *               Clients interested in key events should listen for DeviceEvents
  88      *               via DeviceEventController::registerKeystrokeListener instead.
  89      *
  90      * @note For more information on specific event types, see the documentation for
  91      * each of the individual interfaces supported by some Accessible objects.
  92      *
  93      * @see Accessible, Component, Image, Selection, Table, Text, Value.
  94      */
  95     string     type;
  96     /**
  97      * The Accessible object which is the source of the event.  The source object is the object
  98      * to which the change inferred by the event emission occurs; for instance,
  99      * the object emitting a ¨object:parent-changed¨ event is the child, not the parent.
 100      * Likewise, the event source of an ¨object:children-changed:insert¨ event is the parent,
 101      * not the inserted child.
 102      */
 103     Accessible source;
 104     /** An integer whose meaning is event type dependent.  It may indicate the offset of
 105      * text being inserted, in the case of ¨object:text-changed:insert¨, or the index of a
 106      * newly added child in the case of ¨object:children-changed:add¨.
 107      * @note since most AT-SPI clients react to events via an asynchronous queue, for
 108      * performance reasons, this field may be of limited utility unless the client maintains
 109      * a large client-side cache of the hierarchy and contained data.  This is because by the time
 110      * such an event is asynchronously processed, the state of the originating object may have
 111      * changed.  In other words, the data in the detail1 member is not state-coherent outside
 112      * of the event handler.  More useful results are gotten by examination of the 'any_data' field.
 113      */
 114     long       detail1;
 115     /** see description of detail2 */
 116     long       detail2;
 117     /**
 118      * A generic storage location for event-type-specific data which provides more specific
 119      * information about the event; for instance, in AT-SPI versions prior to 1.7.0,
 120      * in the case of ¨object:text-changed:insert¨ events, this field contains a string
 121      * indicating the inserted text.
 122      *
 123      * @note Since AT-SPI 1.7.0, the data contained in this field is an EventDetails struct.
 124      */
 125     any        any_data;
 126   };
 127
 128   /**
 129    * A generic interface implemented by objects for the
 130    * receipt of event notifications.  EventListener is the interface from which
 131    * Accessibility::Registry is derived, and via which clients of the Registry
 132    * receive notification of changes to an application's user interface and content.
 133    */
 134   interface EventListener : Bonobo::Unknown {
 135     /**
 136      * Synchronously notify an EventListener that an event has occurred, by passing it an
 137      * Event struct.
 138      * @param e The Event about which the listener is being notified.
 139      */
 140     void notifyEvent (in Event e);
 141
 142 /** \cond */
 143     void unImplemented_ ();
 144     void unImplemented2_ ();
 145     void unImplemented3_ ();
 146     void unImplemented4_ ();
 147 /** \endcond */
 148   };
 149 };
 150
 151 #endif