home *** CD-ROM | disk | FTP | other *** search
/ PC Welt 2006 November (DVD) / PCWELT_11_2006.ISO / casper / filesystem.squashfs / usr / share / idl / at-spi-1.0 / Accessibility_Component.idl < prev    next >
Encoding:
Text File  |  2006-08-22  |  7.6 KB  |  171 lines
  1. /* 
  2.  * AT-SPI - Assistive Technology Service Provider Interface 
  3.  * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
  4.  *
  5.  * Copyright 2001 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. #include <Accessibility_Event.idl>
  24.  
  25. module Accessibility {
  26.  
  27.   /** 
  28.    * The ComponentLayer of a Component instance indicates its relative stacking order
  29.    * with respect to the onscreen visual representation of the UI.
  30.    * ComponentLayer, in combination with Component bounds information, can be used
  31.    * to compute the visibility of all or part of a component.  This is important in
  32.    * programmatic determination of region-of-interest for magnification, and in
  33.    * ┬¿flat screen review┬¿ models of the screen, as well as for other uses.
  34.    * Objects residing in two of the ComponentLayer categories support
  35.    * further z-ordering information, with respect to their peers in the same layer:
  36.    * namely, LAYER_WINDOW and LAYER_MDI.  Relative stacking order for other objects within
  37.    * the same layer is not available; the recommended heuristic is ┬¿first child paints first┬¿, 
  38.    * in other words, assume that the first siblings in the child list are subject to being
  39.    * overpainted by later siblings if their bounds intersect.
  40.    *
  41.    * The order of layers, from bottom to top, is:
  42.    * \li LAYER_BACKGROUND
  43.    * \li LAYER_WINDOW
  44.    * \li LAYER_MDI
  45.    * \li LAYER_CANVAS
  46.    * \li LAYER_WIDGET
  47.    * \li LAYER_POPUP
  48.    * \li LAYER_OVERLAY
  49.    */
  50.   enum ComponentLayer {
  51.     LAYER_INVALID,/**< Indicates an error condition or uninitialized value. */
  52.     LAYER_BACKGROUND,/**< The bottom-most layer, over which everything else is painted. 
  53.               * The 'desktop background' is generally in this layer. */
  54.     LAYER_CANVAS,/**< The 'background' layer for most content renderers and UI Component 
  55.           * containers. */
  56.     LAYER_WIDGET,/**< The layer in which the majority of ordinary 'foreground' widgets reside.*/
  57.     LAYER_MDI,/**< A special layer between LAYER_CANVAS and LAYER_WIDGET, in which the
  58.            * 'pseudo windows' (e.g. the MDI frames) reside. 
  59.            * @see Component::getMDIZOrder */
  60.     LAYER_POPUP,/**< A layer for popup window content, above LAYER_WIDGET. */
  61.     LAYER_OVERLAY,/**< The topmost layer. */
  62.     LAYER_WINDOW,/**< The layer in which a toplevel window background usually resides. */
  63.     LAYER_LAST_DEFINED/**< Used only to determine the end of the enumeration. */
  64.   };
  65.  
  66.   /**
  67.    * The Component interface is implemented by objects which occupy on-screen space, e.g. objects
  68.    * which have onscreen visual representations.  The methods in Component allow clients to identify
  69.    * where the objects lie in the onscreen coordinate system, their relative size, stacking order, and
  70.    * position.  It also provides a mechanism whereby keyboard focus may be transferred to specific
  71.    * user interface elements programmatically.  This is a 2D API, coordinates of 3D objects are projected into the
  72.    * 2-dimensional screen view for purposes of this interface.
  73.    *
  74.    * @note the meaning and defined values of the \c short \c coord_type parameter used by some
  75.    * Component methods is as follows:
  76.    * \li 0 indicates coord_type_xy_screen, coordinates are relative to the display screen, in pixels.
  77.    * \li 1 indicates coord_type_xy_window, coordinates are relative to the current toplevel window, in pixels.
  78.    *
  79.    * @note Events emitted by Component instances include:
  80.    * \li \c "object:bounds-changed"
  81.    * \li \c "object:visible-data-changed"
  82.    */
  83.   interface Component : Bonobo::Unknown {
  84.       
  85.         /** 
  86.      * @returns \c True if the specified point lies within the Component's bounding box, 
  87.      * \c False otherwise. 
  88.      */
  89.         boolean contains (in long x, in long y, in short coord_type);
  90.         /** 
  91.      * @returns the Accessible child whose bounding box contains the specified point. 
  92.      */
  93.         Accessible getAccessibleAtPoint (in long x, in long y, in short coord_type);
  94.         /** 
  95.      * Obtain the Component's bounding box, in pixels, relative to the specified coordinate system. 
  96.      * @returns a BoundingBox which entirely contains the object's onscreen visual representation.
  97.      **/
  98.         BoundingBox getExtents (in short coord_type);
  99.         /** 
  100.      * Obtain the position of the current component in the coordinate system specified
  101.      * by \c coord_type.
  102.      * @param coord_type
  103.      * @param x an out parameter which will be back-filled with the returned x coordinate.
  104.      * @param y an out parameter which will be back-filled with the returned y coordinate.
  105.      */
  106.         void getPosition (out long x, out long y, in short coord_type);
  107.         /** 
  108.      * Obtain the size, in the coordinate system specified by \c coord_type, 
  109.      * of the rectangular area which fully contains the object's 
  110.      * visual representation, without accounting for viewport clipping. 
  111.      * @param width the object's horizontal extents in the specified coordinate system.
  112.      * @param height the object's vertical extents in the specified coordinate system.
  113.      */
  114.         void getSize (out long width, out long height);
  115.         /** @returns the ComponentLayer in which this object resides. */
  116.     ComponentLayer getLayer ();
  117.         /** 
  118.      * Obtain the relative stacking order (i.e. 'Z' order) of an object.
  119.      * Larger values indicate that an object is on "top" of the stack, therefore
  120.      * objects with smaller MDIZOrder may be obscured by objects with a larger MDIZOrder,
  121.      * but not vice-versa. 
  122.      * @note only relevant for objects in LAYER_MDI or LAYER_WINDOW 
  123.      * @returns an integer indicating the object's place in the stacking order.
  124.      */
  125.     short getMDIZOrder ();
  126.         /**
  127.      * Request that the object obtain keyboard focus.
  128.      *  
  129.      * @returns \c True if keyboard focus was successfully transferred to the Component. 
  130.      */
  131.         boolean grabFocus ();
  132.         /** 
  133.      * Register an EventListener for notification when this object receives keyboard focus.
  134.      * @note you probably want to register for ┬¿focus:┬¿ events via 
  135.      * Registry::registerGlobalEventListener instead. 
  136.      */
  137.         void registerFocusHandler (in EventListener handler);
  138.         /**
  139.      * Request that an EventListener registered via registerFocusHandler no longer be notified 
  140.      * when this object receives keyboard focus.
  141.      */
  142.         void deregisterFocusHandler (in EventListener handler);
  143.  
  144.         /**
  145.      * Obtain the alpha value of the component.  An alpha value of 1.0 or greater
  146.      * indicates that the object is fully opaque, and an alpha value of 0.0 indicates
  147.      * that the object is fully transparent.  Negative alpha values have no defined
  148.      * meaning at this time.
  149.      *
  150.      * @note alpha values are used in conjunction with Z-order calculations to
  151.      * determine whether an object wholly or partially obscures another object's 
  152.      * visual intersection, in the event that their bounds intersect.
  153.      *
  154.      * @see STATE_OPAQUE
  155.      *
  156.      * @since AT-SPI 1.7.0
  157.      */
  158.         double getAlpha ();
  159.  
  160.     /** \cond
  161.      * unImplemented:
  162.      *
  163.      * placeholders for future expansion.
  164.      */
  165.     void unImplemented ();
  166.     void unImplemented2 ();
  167.     void unImplemented3 ();
  168.         /** \endcond */
  169.   };
  170. };
  171.