/* 
 * 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 ();
	void unImplemented3 ();
	void unImplemented4 ();
	void unImplemented5 ();
	void unImplemented6 ();
    };

  /* Deprecated, DO NOT USE! */
  enum KeyEventType {
    KEY_PRESSED,
    KEY_RELEASED
  };

  enum EventType {
    KEY_PRESSED_EVENT,
    KEY_RELEASED_EVENT,
    BUTTON_PRESSED_EVENT,
    BUTTON_RELEASED_EVENT
  };

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

  enum ModifierType {
    MODIFIER_SHIFT,
    MODIFIER_SHIFTLOCK,
    MODIFIER_CONTROL,
    MODIFIER_ALT,
    MODIFIER_META,
    MODIFIER_META2,
    MODIFIER_META3,
    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< EventType > KeyEventTypeSeq;
  typedef sequence< EventType > EventTypeSeq;

  interface DeviceEventListener : Bonobo::Unknown {
        boolean notifyEvent (in DeviceEvent event);
        void    unImplemented__ ();
        void    unImplemented_2_ ();
        void    unImplemented_3_ ();
        void    unImplemented_4_ ();
        void    unImplemented_5_ ();
        void    unImplemented_6_ ();
  };

  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);
    
  	/**
         * registerDeviceEventListener:
         * @listener: a @DeviceEventListener which will intercept events.
	 * @typeseq:  an @EventTypeSeq indicating which event types to listen for.
	 * Returns: %true if successful, %false if not
         *
         * Register to intercept events, and either pass them on or
         * consume them. To listen to keyboard events use registerKeystrokeListener
	 * instead.
         *
	 **/
        boolean registerDeviceEventListener (in DeviceEventListener listener,
					     in EventTypeSeq typeseq);
    
  	/**
         * deregisterDeviceEventListener:
         * @listener: a @DeviceEventListener which will intercept events.
	 * @typeseq:  an @EventTypeSeq indicating which event types to stop
	 *            listening for.
	 *
	 * Returns: void
         *
         * De-register a previously registered keyboard eventlistener.
         *
	 **/
        void deregisterDeviceEventListener (in DeviceEventListener listener,
					    in EventTypeSeq typeseq);
    
        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 ();
	 void unImplemented3 ();
	 void unImplemented4 ();
    }; 
};

#endif
