idl/Accessibility_Application.idl

   1 /*
   2  * AT-SPI - Assistive Technology Service Provider Interface
   3  * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
   4  *
   5  * Copyright 2001-2004 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_APPLICATION_DEFINED__
  24 #define __ACCESSIBILITY_APPLICATION_DEFINED__
  25
  26 #include <Accessibility_Accessible.idl>
  27
  28 module Accessibility {
  29
  30   /**
  31    * An interface identifying an object which is the root of the
  32    * user interface Accessible hierarchy associated with a running application.
  33    * Children of Application are typically, but not exclusively,
  34    * top-level windows.
  35    * @note It is possible for an element deeper in an Accessibility stack to
  36    * implement Application, for instance in the case of "embedded applications"
  37    * which draw into toplevel windows associated with other applications
  38    * from the user's point of view.
  39    */
  40   interface Application : Accessible {
  41
  42     /**
  43      * A string indicating the type of user interface toolkit
  44      * which is used by the application.
  45      * @note Ordinarily clients of ::Application should be
  46      * toolkit-agnostic, dependencies on this property should
  47      * be avoided where possible.
  48      **/
  49     readonly attribute string toolkitName;
  50
  51     /**
  52      * A string indicating the version number of the application's
  53      * accessibility bridge implementation.
  54      **/
  55     readonly attribute string version;
  56
  57     /**
  58      * The application instance's unique ID as assigned by the registry.
  59      **/
  60     attribute long id;
  61
  62     /**
  63      * @param listener: an ::EventListener object which will receive the requested
  64      *            events from the application's toolkits via toolit 'bridges'
  65      * @param eventName: a UTF-8 string indicating the type of (toolkit-specific) event
  66      *            being requested.  Not all applications can generate toolkit events of
  67      *            a given type.
  68      *
  69      * Register with this application's toolkit for "toolkit-specific" event notifications.
  70      * @note
  71      *       For most event support, clients should use non-toolkit-specific events
  72      *       whenever possible, via ::Registry::registerGlobalEventListener - this method
  73      *       is provided as a 'back door' when generic names do not exist for the events in
  74      *       question.
  75      **/
  76     void registerToolkitEventListener (in EventListener listener, in string eventName);
  77
  78     /**
  79      * registerObjectEventListener:
  80      * @param listener: an ::EventListener object which will receive the requested
  81      *            events
  82      * @param eventName: a UTF-8 string indicating the type of (toolkit-specific) event
  83      *            being requested.
  84      * Register with this application toolkit for "Accessibility::Accessible"
  85      * event notifications.
  86      * @note: SUBJECT TO DEPRECATION.
  87      **/
  88     void registerObjectEventListener (in EventListener listener, in string eventName);
  89
  90     /**
  91      * Request that the application temporarily stop sending events.
  92      * In most cases this should pause the application's main event loop.
  93      *
  94      * @returns: \c true if the request succeeded, \c false otherwise.
  95      *
  96      * @note: This method is not implemented in most toolkits, and therefore should be treated with caution.
  97      **/
  98     boolean       pause ();
  99
 100     /**
 101      * Request that the application resume sending events.
 102      *
 103      * @returns: \c True if the request succeeded, \c False otherwise.
 104      **/
 105     boolean       resume ();
 106
 107     /**
 108      * Gets the locale in which the application is currently operating.
 109      * For the current message locale, use \a lctype LOCALE_TYPE_MESSAGES.
 110      *
 111      * @param lctype The LocaleType for which the locale is queried.
 112      * @returns a string compliant with the POSIX standard for locale description.
 113      **/
 114     string       getLocale (in LOCALE_TYPE lctype);
 115
 116     /**\cond (This comment tells doxygen not to document these) */
 117     void          unImplemented_ ();
 118     void          unImplemented2_ ();
 119     void          unImplemented3_ ();
 120     /**\endcond */
 121   };
 122 };
 123
 124 #endif