/* 
 * 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 <Accessibility_Event.idl>

module Accessibility {

  /** 
   * The ComponentLayer of a Component instance indicates its relative stacking order
   * with respect to the onscreen visual representation of the UI.
   * ComponentLayer, in combination with Component bounds information, can be used
   * to compute the visibility of all or part of a component.  This is important in
   * programmatic determination of region-of-interest for magnification, and in
   * ¨flat screen review¨ models of the screen, as well as for other uses.
   * Objects residing in two of the ComponentLayer categories support
   * further z-ordering information, with respect to their peers in the same layer:
   * namely, LAYER_WINDOW and LAYER_MDI.  Relative stacking order for other objects within
   * the same layer is not available; the recommended heuristic is ¨first child paints first¨, 
   * in other words, assume that the first siblings in the child list are subject to being
   * overpainted by later siblings if their bounds intersect.
   *
   * The order of layers, from bottom to top, is:
   * \li LAYER_BACKGROUND
   * \li LAYER_WINDOW
   * \li LAYER_MDI
   * \li LAYER_CANVAS
   * \li LAYER_WIDGET
   * \li LAYER_POPUP
   * \li LAYER_OVERLAY
   */
  enum ComponentLayer {
    LAYER_INVALID,/**< Indicates an error condition or uninitialized value. */
    LAYER_BACKGROUND,/**< The bottom-most layer, over which everything else is painted. 
		      * The 'desktop background' is generally in this layer. */
    LAYER_CANVAS,/**< The 'background' layer for most content renderers and UI Component 
		  * containers. */
    LAYER_WIDGET,/**< The layer in which the majority of ordinary 'foreground' widgets reside.*/
    LAYER_MDI,/**< A special layer between LAYER_CANVAS and LAYER_WIDGET, in which the
	       * 'pseudo windows' (e.g. the MDI frames) reside. 
	       * @see Component::getMDIZOrder */
    LAYER_POPUP,/**< A layer for popup window content, above LAYER_WIDGET. */
    LAYER_OVERLAY,/**< The topmost layer. */
    LAYER_WINDOW,/**< The layer in which a toplevel window background usually resides. */
    LAYER_LAST_DEFINED/**< Used only to determine the end of the enumeration. */
  };

  /**
   * The Component interface is implemented by objects which occupy on-screen space, e.g. objects
   * which have onscreen visual representations.  The methods in Component allow clients to identify
   * where the objects lie in the onscreen coordinate system, their relative size, stacking order, and
   * position.  It also provides a mechanism whereby keyboard focus may be transferred to specific
   * user interface elements programmatically.  This is a 2D API, coordinates of 3D objects are projected into the
   * 2-dimensional screen view for purposes of this interface.
   *
   * @note the meaning and defined values of the \c short \c coord_type parameter used by some
   * Component methods is as follows:
   * \li 0 indicates coord_type_xy_screen, coordinates are relative to the display screen, in pixels.
   * \li 1 indicates coord_type_xy_window, coordinates are relative to the current toplevel window, in pixels.
   *
   * @note Events emitted by Component instances include:
   * \li \c "object:bounds-changed"
   * \li \c "object:visible-data-changed"
   */
  interface Component : Bonobo::Unknown {
      
        /** 
	 * @returns \c True if the specified point lies within the Component's bounding box, 
	 * \c False otherwise. 
	 */
        boolean contains (in long x, in long y, in short coord_type);
        /** 
	 * @returns the Accessible child whose bounding box contains the specified point. 
	 */
        Accessible getAccessibleAtPoint (in long x, in long y, in short coord_type);
        /** 
	 * Obtain the Component's bounding box, in pixels, relative to the specified coordinate system. 
	 * @returns a BoundingBox which entirely contains the object's onscreen visual representation.
	 **/
        BoundingBox getExtents (in short coord_type);
        /** 
	 * Obtain the position of the current component in the coordinate system specified
	 * by \c coord_type.
	 * @param coord_type
	 * @param x an out parameter which will be back-filled with the returned x coordinate.
	 * @param y an out parameter which will be back-filled with the returned y coordinate.
	 */
        void getPosition (out long x, out long y, in short coord_type);
        /** 
	 * Obtain the size, in the coordinate system specified by \c coord_type, 
	 * of the rectangular area which fully contains the object's 
	 * visual representation, without accounting for viewport clipping. 
	 * @param width the object's horizontal extents in the specified coordinate system.
	 * @param height the object's vertical extents in the specified coordinate system.
	 */
        void getSize (out long width, out long height);
        /** @returns the ComponentLayer in which this object resides. */
	ComponentLayer getLayer ();
        /** 
	 * Obtain the relative stacking order (i.e. 'Z' order) of an object.
	 * Larger values indicate that an object is on "top" of the stack, therefore
	 * objects with smaller MDIZOrder may be obscured by objects with a larger MDIZOrder,
	 * but not vice-versa. 
	 * @note only relevant for objects in LAYER_MDI or LAYER_WINDOW 
	 * @returns an integer indicating the object's place in the stacking order.
	 */
	short getMDIZOrder ();
        /**
	 * Request that the object obtain keyboard focus.
	 *  
	 * @returns \c True if keyboard focus was successfully transferred to the Component. 
	 */
        boolean grabFocus ();
        /** 
	 * Register an EventListener for notification when this object receives keyboard focus.
	 * @note you probably want to register for ¨focus:¨ events via 
	 * Registry::registerGlobalEventListener instead. 
	 */
        void registerFocusHandler (in EventListener handler);
        /**
	 * Request that an EventListener registered via registerFocusHandler no longer be notified 
	 * when this object receives keyboard focus.
	 */
        void deregisterFocusHandler (in EventListener handler);

        /**
	 * Obtain the alpha value of the component.  An alpha value of 1.0 or greater
	 * indicates that the object is fully opaque, and an alpha value of 0.0 indicates
	 * that the object is fully transparent.  Negative alpha values have no defined
	 * meaning at this time.
	 *
	 * @note alpha values are used in conjunction with Z-order calculations to
	 * determine whether an object wholly or partially obscures another object's 
	 * visual intersection, in the event that their bounds intersect.
	 *
	 * @see STATE_OPAQUE
	 *
	 * @since AT-SPI 1.7.0
	 */
        double getAlpha ();

	/** \cond
	 * unImplemented:
	 *
	 * placeholders for future expansion.
	 */
	void unImplemented ();
	void unImplemented2 ();
	void unImplemented3 ();
        /** \endcond */
  };
};
