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 module Accessibility
  27 {
  28   interface Accessible;
  29
  30   /**
  31    * A struct encapsulating detailed information about an Event.
  32    * This struct supercedes the previous use of the 'any' field
  33    * in EventDetails; the content previously stored in Event::any_data
  34    * is now stored in EventDetails::any_data, and Event::any_data
  35    * points to an instance of the EventDetails structure, if
  36    * the object's implementation supports event detail reporting,
  37    * otherwise Event::any_data contains CORBA_OBJECT_NIL.
  38    *
  39    * @since AT-SPI 1.7.0
  40    */
  41   struct EventDetails {
  42       Application host_application;
  43       Role        source_role;
  44       string      source_name;
  45       any         any_data;
  46   };
  47
  48   /**
  49    * A structure encapsulating information about an event
  50    * for which notification was requested.  Usually such notification
  51    * is requested via a call to Registry::registerGlobalEventListener.
  52    * The structure contains a colon-delimited string indicating the event
  53    * type, a reference to the generating Accessible, two detail fields whose
  54    * interpretation is event-type-specific, and a final field containing
  55    * event-type-specific data.
  56    *
  57    * @note Since AT-SPI 1.7.0 the 'any' field contains an EventDetails
  58    * struct, which encapsulates additional information about the event
  59    * and its generating object.
  60    */
  61   struct Event {
  62     /** A colon-delimited string indicating the type of the event.
  63      *  The string can be interpreted as
  64      *  \c class:type:subtype
  65      *  For instance ¨object:text-changed:insert¨ is an event
  66      *  from the 'Object' class, which corresponds to Accessible objects
  67      *  general, the type of the event is a ¨text-changed¨ event (i.e. a change in the
  68      *  content of an implementor of the Text interface), and the
  69      *  specific subtype of the change is an insertion event.
  70      *
  71      *  Event classes include the following:
  72      *  \li focus:   an object has received keyboard focus.  This event has no type or subtype.
  73      *  \li window:  a toplevel window has changed state.
  74      *  \li object:  an object (i.e. Accessible) has undergone some change in state, content,
  75      *               or hierarchy
  76      *  \li document:a change to a document's content has occurred, or its
  77      *               content loading status has changed.
  78      *  \li mouse:   an event originating from the pointing device.  Rarely used;
  79      *               in most cases clients will wish to register for pointer events via
  80      *               the DeviceEventController::registerDeviceEvent method instead.
  81      *  \li keyboard: an event indicating that the keyboard state (for example, the
  82      *               modifier state) has changed significantly.
  83      *               "keyboard:" events are not sent for individual keystrokes except as
  84      *               a side-effect of certain keys, for instance modifier keys.
  85      *               Clients interested in key events should listen for DeviceEvents
  86      *               via DeviceEventController::registerKeystrokeListener instead.
  87      *
  88      * @note For more information on specific event types, see the documentation for
  89      * each of the individual interfaces supported by some Accessible objects.
  90      *
  91      * @see Accessible, Component, Image, Selection, Table, Text, Value.
  92      */
  93     string     type;
  94     /**
  95      * The Accessible object which is the source of the event.  The source object is the object
  96      * to which the change inferred by the event emission occurs; for instance,
  97      * the object emitting a ¨object:parent-changed¨ event is the child, not the parent.
  98      * Likewise, the event source of an ¨object:children-changed:insert¨ event is the parent,
  99      * not the inserted child.
 100      */
 101     Accessible source;
 102     /** An integer whose meaning is event type dependent.  It may indicate the offset of
 103      * text being inserted, in the case of ¨object:text-changed:insert¨, or the index of a
 104      * newly added child in the case of ¨object:children-changed:add¨.
 105      * @note since most AT-SPI clients react to events via an asynchronous queue, for
 106      * performance reasons, this field may be of limited utility unless the client maintains
 107      * a large client-side cache of the hierarchy and contained data.  This is because by the time
 108      * such an event is asynchronously processed, the state of the originating object may have
 109      * changed.  In other words, the data in the detail1 member is not state-coherent outside
 110      * of the event handler.  More useful results are gotten by examination of the 'any_data' field.
 111      */
 112     long       detail1;
 113     /** see description of detail2 */
 114     long       detail2;
 115     /**
 116      * A generic storage location for event-type-specific data which provides more specific
 117      * information about the event; for instance, in AT-SPI versions prior to 1.7.0,
 118      * in the case of ¨object:text-changed:insert¨ events, this field contains a string
 119      * indicating the inserted text.
 120      *
 121      * @note Since AT-SPI 1.7.0, the data contained in this field is an EventDetails struct.
 122      */
 123     any        any_data;
 124   };
 125
 126   /**
 127    * A generic interface implemented by objects for the
 128    * receipt of event notifications.  EventListener is the interface from which
 129    * Accessibility::Registry is derived, and via which clients of the Registry
 130    * receive notification of changes to an application's user interface and content.
 131    */
 132   interface EventListener : Bonobo::Unknown {
 133     /**
 134      * Synchronously notify an EventListener that an event has occurred, by passing it an
 135      * Event struct.
 136      * @param e The Event about which the listener is being notified.
 137      */
 138     void notifyEvent (in Event e);
 139
 140 /** \cond */
 141     void unImplemented_ ();
 142     void unImplemented2_ ();
 143     void unImplemented3_ ();
 144     void unImplemented4_ ();
 145 /** \endcond */
 146   };
 147 };
 148
 149 #endif