idl/Accessibility_Component.idl

   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 };