home *** CD-ROM | disk | FTP | other *** search
/ PC Welt 2006 November (DVD) / PCWELT_11_2006.ISO / casper / filesystem.squashfs / usr / share / idl / at-spi-1.0 / Accessibility_Event.idl < prev    next >
Encoding:
Text File  |  2006-08-22  |  6.8 KB  |  150 lines
  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
  150.