source: trunk/third/at-spi/idl/Accessibility_Registry.idl @ 18422

/* 
 * AT-SPI - Assistive Technology Service Provider Interface 
 * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
 *
 * Copyright 2001 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
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 */

#include <Bonobo_Unknown.idl>
#include <Accessibility_Event.idl>
#include <Accessibility_Application.idl>
#include <Accessibility_Desktop.idl>

#ifndef _ACCESSIBILITY_REGISTRY_IDL_
#define _ACCESSIBILITY_REGISTRY_IDL_

module Accessibility {

  typedef sequence<Desktop> DesktopSeq;

  interface DeviceEventController;

  interface Registry : EventListener {

        /**
         * registerApplication:
         * @application: a reference to the requesting @Application
         *
         * Register a new application with the accessibility broker.
         *
         **/
        oneway void registerApplication (in Application application);

        /**
         * deregisterApplication:
         * @application: a reference to the @Application 
         * to be deregistered.
         *
         * De-register an application previously registered with the broker.
         *
         **/
        void deregisterApplication (in Application application);

        /**
         * registerGlobalEventListener:
         * @listener: a reference to the requesting @EventListener.
         * @eventName: a string which indicates the type of events about 
         * which the client desires notification.
         *
         * Register a client's interest in (all) application events of 
         * a certain type.
         *
         **/
        void registerGlobalEventListener (in EventListener listener,
                                          in string eventName);

        /**
         * deregisterGlobalEventListener:
         * @listener: the requesting @EventListener
         * @eventName: a string indicating the type of events
         *
         * Request that a previously registered client stop receiving
         * global notifications for events of a certain type.
         *
         **/

        void deregisterGlobalEventListenerAll (in EventListener listener);
        /**
         * deregisterGlobalEventListener:
         * @listener: the requesting @EventListener
         * @eventName: a string indicating the type of events
         *
         * Request that a previously registered client stop receiving
         * global notifications for events of a certain type.
         *
         **/

        void deregisterGlobalEventListener (in EventListener listener, 
                                            in string event_name);
        /** 
         * event types: "Window" "Desktop"
         *              "Window:Create" "Window:Destroy"
         *              "Window:Iconify" "Window:Restore"
         *              "Window:Fullscreen" "Window:Resize"
         *              "Desktop:Create" "Desktop:Destroy"  
         *              "Desktop:Focus" "Desktop:Defocus"
         *              "Desktop:Reorder" 
         *              "Focus"
         *              "GtkWidget:show"
         *              "GObject:notify:<propertyname>" 
         *
         *  ( not sure we should allow these last 2 forms, 
         *    since they are toolkit-specific, but they're powerful )
         *
         **/              

        /**
         * getDesktopCount:
         *
         * Get the current number of desktops.
         * Returns: a short integer indicating the current number of 
         * @Desktops.
         **/
        short getDesktopCount ();

        /**
         * getDesktop:
         * @n: the index of the requested @Desktop.
         *
         * Get the nth accessible desktop. 
         *
         * Returns: a reference to the requested @Desktop.
         **/
        Desktop getDesktop (in short n);

        /**
         * getDesktopList:
         *
         * Get a list of accessible desktops. 
         *
         * Returns: a sequence containing references to
         * the @Desktops.
         **/
        DesktopSeq getDesktopList ();

        /**
         * getDeviceEventController:
         *
         * Returns: an object implementing DeviceEventController
         **/
        DeviceEventController getDeviceEventController ();

        /**
         * unImplemented:
         *
         * placeholders for future expansion.
         */
        void unImplemented ();
        void unImplemented2 ();
    };

  enum KeyEventType {
    KEY_PRESSED,
    KEY_RELEASED
  };

  enum EventType {
    KEY_PRESSED_EVENT,
    KEY_RELEASED_EVENT
  };

  enum KeySynthType {
    KEY_PRESS,
    KEY_RELEASE,
    KEY_PRESSRELEASE,
    KEY_SYM,
    KEY_STRING
  };

  enum ModifierType {
    MODIFIER_SHIFT,
    MODIFIER_ALT,
    MODIFIER_CONTROL,
    MODIFIER_META,
    MODIFIER_META2,
    MODIFIER_META3,
    MODIFIER_SHIFTLOCK,
    MODIFIER_NUMLOCK
  };

  struct EventListenerMode {
    boolean synchronous;
    boolean preemptive;
    boolean global;       
  };

  typedef unsigned long ControllerEventMask;

  struct DeviceEvent {
    EventType type; 
    long  id;
    short hw_code;
    unsigned short modifiers;
    unsigned long timestamp;
    string event_string;
    boolean is_text;
  };

  struct KeyDefinition {
    long keycode;
    long keysym;
    string keystring;
    long unused;
  };    

  typedef sequence< KeyDefinition > KeySet;
  typedef sequence< KeyEventType > KeyEventTypeSeq;

  interface DeviceEventListener : Bonobo::Unknown {
        boolean notifyEvent (in DeviceEvent event);
  };

  interface DeviceEventController : Bonobo::Unknown {

        /**
         * registerKeystrokeListener:
         * @listener: a @DeviceEventListener which will intercept key events.
         * @keys:     a @KeySet indicating which keys to intercept, or KEYSET_ALL_KEYS.
         * @mask:     a @ControllerEventMask filtering the intercepted key events.
         * @type:     an @EventType mask that may created by ORing event types together.
         * @is_synchronous: a @boolean indicating whether the listener should 
         *            receive the events synchronously, potentially consuming them,
         *            or just be notified asynchronously of those events that have
         *            been generated.
         * Returns: %true if successful, %false if not
         *
         * Register to intercept keyboard events, and either pass them on or
         * consume them. 
         *
         **/
        boolean registerKeystrokeListener (in DeviceEventListener listener,
                                        in KeySet keys,
                                        in ControllerEventMask mask,
                                        in KeyEventTypeSeq type,
                                        in EventListenerMode mode);
    
        /**
         * deregisterKeystrokeListener:
         * @listener: a @DeviceEventListener which will intercept key events.
         * @keys:     a @KeySet indicating which keys to intercept, or KEYSET_ALL_KEYS.
         * @mask:     a @ControllerEventMask filtering the intercepted key events.
         * @type:     an @EventType mask that may created by ORing event types together.
         *
         * Returns: void
         *
         * De-register a previously registered keyboard eventlistener.
         *
         **/
        void deregisterKeystrokeListener (in DeviceEventListener listener,
                                          in KeySet keys,
                                          in ControllerEventMask mask,
                                          in KeyEventTypeSeq type);
    
        boolean notifyListenersSync (in DeviceEvent event);

        oneway void notifyListenersAsync (in DeviceEvent event);

        /**
         * generateKeyboardEvent:
         * @keycode: a long integer indicating the keycode of
         *          the keypress to be synthesized.
         * @keystring: an optional UTF-8 string indicating a complex
         *          keyboard input event.
         * @type: a #KeySynthType indicating the type of event(s) to be 
         *          synthesized: a key press, release, press-release pair,
         *          or a complex input string (for instance from an
         *          internationalized or complex text input method, or
         *          a composed character).
         *
         * Note that @keycode may be truncated before being
         *          processed, as keycode length may be platform-dependent
         *          and keycode ranges are generally much smaller than
         *          CORBA_long. 
         * One or the other of @keycode or @keystring are generally NULL, 
         *          (but not both), depending on the value of @type.
         *
         * Returns: void
         *
         * Synthesize a keyboard event.
         *
         **/
         void generateKeyboardEvent (in long keycode, 
                                     in string keystring, 
                                     in KeySynthType type);

        /**
         * generateMouseEvent:
         * @x: a long integer indicating the screen x coord for the mouse event.
         * @y: a long integer indicating the screen y coord for the mouse event.
         * @eventName: a string indicating the type of mouse event, e.g. "button1up"
         * Returns: void
         *
         * Synthesize a mouse event.
         *
         **/
         void generateMouseEvent (in long x, in long y, in string eventName);

         /**
          * unImplemented:
          *
          * placeholders for future expansion.
          */
         void unImplemented ();
         void unImplemented2 ();
    }; 
};

#endif