/* 
 * 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 <Event.idl>
#include <Application.idl>
#include <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 ();

    };

  enum KeyEventType {
    KEY_PRESSED,
    KEY_RELEASED
  };

  enum EventType {
    KEY_PRESSED_EVENT,
    KEY_RELEASED_EVENT
  };

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

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

  struct ControllerEventMask {
    unsigned long value;
    unsigned short refcount;
  };

  struct KeyStroke {
    long keyID;
    short keycode;
    unsigned long timestamp;
    KeyEventType type; 
    unsigned short modifiers;
  };

  struct DeviceEvent {
    long eventID;
    short hw_code;
    unsigned long timestamp;
    EventType type; 
    unsigned short modifiers;
  };

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

  interface KeystrokeListener : Bonobo::Unknown {
        boolean keyEvent (in KeyStroke key);
  };

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

  interface DeviceEventController : Bonobo::Unknown {

  	/**
         * registerKeystrokeListener:
         * @listener: a @KeystrokeListener 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: void
         *
         * Register to intercept keyboard events, and either pass them on or
         * consume them. 
         *
	 **/
        void registerKeystrokeListener (in KeystrokeListener listener,
					in KeySet keys,
					in ControllerEventMask mask,
					in KeyEventTypeSeq type,
					in boolean is_synchronous);
    
  	/**
         * deregisterKeystrokeListener:
         * @listener: a @KeystrokeListener 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: void
         *
         * De-register a previously registered keyboard eventlistener.
         *
	 **/
        void deregisterKeystrokeListener (in KeystrokeListener listener,
					in KeySet keys,
					in ControllerEventMask mask,
					in KeyEventTypeSeq type,
					in boolean is_synchronous);
    
        boolean notifyListenersSync (in DeviceEvent event);

        oneway void notifyListenersAsync (in DeviceEvent event);

        /**
         * generateKeyEvent:
         * @keycode: a long integer indicating the keycode of
	 *          the keypress to be synthesized.
	 *
	 * Note that this long may be truncated before being
	 *          processed, as keycode length may be platform-dependent
	 *          and keycode ranges are generally much smaller than
	 *          CORBA_long. 
	 *
         * Returns: void
         *
         * Synthesize a keypress event.
         *
         **/
         void generateKeyEvent (in long keycode, 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);
    }; 
};

#endif