xml/Accessibility_Component.xml

   1 <node name="/node" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
   2
   3 <tp:title>AT-SPI - Assistive Technology Service Provider Interface </tp:title>
   4 <tp:copyright>Copyright 2008 Novell, Inc.</tp:copyright>
   5 <tp:copyright>Copyright 2001 Sun Microsystems, Inc.</tp:copyright>
   6 <tp:license xmlns="http://www.w3.org/1999/xhtml">
   7   <p>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.</p>
  11
  12   <p>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.</p>
  16
  17   <p>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.</p>
  21 </tp:license>
  22 <tp:enum name="ComponentLayer" type="u">
  23   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  24     <p>The ComponentLayer of a Component instance indicates its relative stacking order
  25       with respect to the onscreen visual representation of the UI.
  26       ComponentLayer, in combination with Component bounds information, can be used
  27       to compute the visibility of all or part of a component.  This is important in
  28       programmatic determination of region-of-interest for magnification, and in
  29       ¨flat screen review¨ models of the screen, as well as for other uses.
  30       Objects residing in two of the ComponentLayer categories support
  31       further z-ordering information, with respect to their peers in the same layer:
  32       namely, LAYER_WINDOW and LAYER_MDI.  Relative stacking order for other objects within
  33       the same layer is not available; the recommended heuristic is ¨first child paints first¨,
  34       in other words, assume that the first siblings in the child list are subject to being
  35       overpainted by later siblings if their bounds intersect.  </p>
  36
  37     <p>The order of layers, from bottom to top, is:
  38       \li LAYER_BACKGROUND
  39       \li LAYER_WINDOW
  40       \li LAYER_MDI
  41       \li LAYER_CANVAS
  42       \li LAYER_WIDGET
  43       \li LAYER_POPUP
  44       \li LAYER_OVERLAY</p>
  45   </tp:docstring>
  46   <tp:enumvalue suffix="LAYER_INVALID">
  47   <tp:docstring>
  48     &lt; Indicates an error condition or uninitialized value.
  49   </tp:docstring>
  50   </tp:enumvalue>
  51   <tp:enumvalue suffix="LAYER_BACKGROUND" value="1">
  52   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  53     <p>&lt; The bottom-most layer, over which everything else is painted.
  54       The 'desktop background' is generally in this layer. </p>
  55   </tp:docstring>
  56   </tp:enumvalue>
  57   <tp:enumvalue suffix="LAYER_CANVAS" value="2">
  58   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  59     <p>&lt; The 'background' layer for most content renderers and UI Component
  60       containers. </p>
  61   </tp:docstring>
  62   </tp:enumvalue>
  63   <tp:enumvalue suffix="LAYER_WIDGET" value="3">
  64   <tp:docstring>
  65     &lt; The layer in which the majority of ordinary 'foreground' widgets reside.
  66   </tp:docstring>
  67   </tp:enumvalue>
  68   <tp:enumvalue suffix="LAYER_MDI" value="4">
  69   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  70     <p>&lt; A special layer between LAYER_CANVAS and LAYER_WIDGET, in which the
  71       'pseudo windows' (e.g. the MDI frames) reside.
  72       @see Component::getMDIZOrder </p>
  73   </tp:docstring>
  74   </tp:enumvalue>
  75   <tp:enumvalue suffix="LAYER_POPUP" value="5">
  76   <tp:docstring>
  77     &lt; A layer for popup window content, above LAYER_WIDGET.
  78   </tp:docstring>
  79   </tp:enumvalue>
  80   <tp:enumvalue suffix="LAYER_OVERLAY" value="6">
  81   <tp:docstring>
  82     &lt; The topmost layer.
  83   </tp:docstring>
  84   </tp:enumvalue>
  85   <tp:enumvalue suffix="LAYER_WINDOW" value="7">
  86   <tp:docstring>
  87     &lt; The layer in which a toplevel window background usually resides.
  88   </tp:docstring>
  89   </tp:enumvalue>
  90   <tp:enumvalue suffix="LAYER_LAST_DEFINED" value="8">
  91   <tp:docstring>
  92     &lt; Used only to determine the end of the enumeration.
  93   </tp:docstring>
  94   </tp:enumvalue>
  95 </tp:enum>
  96 <interface name="org.freedesktop.accessibility.Component">
  97   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  98     <p>The Component interface is implemented by objects which occupy on-screen space, e.g. objects
  99       which have onscreen visual representations.  The methods in Component allow clients to identify
 100       where the objects lie in the onscreen coordinate system, their relative size, stacking order, and
 101       position.  It also provides a mechanism whereby keyboard focus may be transferred to specific
 102       user interface elements programmatically.  This is a 2D API, coordinates of 3D objects are projected into the
 103       2-dimensional screen view for purposes of this interface.  </p>
 104
 105     <p>@note the meaning and defined values of the \c short \c coord_type parameter used by some
 106       Component methods is as follows:
 107       \li 0 indicates coord_type_xy_screen, coordinates are relative to the display screen, in pixels.
 108       \li 1 indicates coord_type_xy_window, coordinates are relative to the current toplevel window, in pixels.  </p>
 109
 110     <p>@note Events emitted by Component instances include:
 111       \li \c &quot;object:bounds-changed&quot;
 112       \li \c &quot;object:visible-data-changed&quot;</p>
 113   </tp:docstring>
 114   <method name="contains">
 115     <arg direction="in" name="x" type="i"/>
 116     <arg direction="in" name="y" type="i"/>
 117     <arg direction="in" name="coord_type" type="n" tp:type="short"/>
 118     <arg direction="out" type="b" tp:type="boolean">
 119     <tp:docstring>
 120       \c True if the specified point lies within the Component's bounding box, \c False otherwise.
 121     </tp:docstring>
 122     </arg>
 123   </method>
 124   <method name="getAccessibleAtPoint">
 125     <arg direction="in" name="x" type="i"/>
 126     <arg direction="in" name="y" type="i"/>
 127     <arg direction="in" name="coord_type" type="n" tp:type="short"/>
 128     <arg direction="out" type="o" tp:type="Accessible">
 129     <tp:docstring>
 130       the Accessible child whose bounding box contains the specified point.
 131     </tp:docstring>
 132     </arg>
 133   </method>
 134   <method name="getExtents">
 135     <tp:docstring>
 136       Obtain the Component's bounding box, in pixels, relative to the specified coordinate system.
 137     </tp:docstring>
 138     <arg direction="in" name="coord_type" type="n" tp:type="short"/>
 139     <arg direction="out" type="(uuuu)" tp:type="BoundingBox">
 140     <tp:docstring>
 141       a BoundingBox which entirely contains the object's onscreen visual representation.
 142     </tp:docstring>
 143     </arg>
 144   </method>
 145   <method name="getPosition">
 146     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 147       <p>Obtain the position of the current component in the coordinate system specified
 148         by \c coord_type.
 149         @param coord_type
 150         @param x an out parameter which will be back-filled with the returned x coordinate.
 151         @param y an out parameter which will be back-filled with the returned y coordinate.</p>
 152     </tp:docstring>
 153     <arg direction="out" name="x" type="i"/>
 154     <arg direction="out" name="y" type="i"/>
 155     <arg direction="in" name="coord_type" type="n" tp:type="short"/>
 156   </method>
 157   <method name="getSize">
 158     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 159       <p>Obtain the size, in the coordinate system specified by \c coord_type,
 160         of the rectangular area which fully contains the object's
 161         visual representation, without accounting for viewport clipping.
 162         @param width the object's horizontal extents in the specified coordinate system.
 163         @param height the object's vertical extents in the specified coordinate system.</p>
 164     </tp:docstring>
 165     <arg direction="out" name="width" type="i"/>
 166     <arg direction="out" name="height" type="i"/>
 167   </method>
 168   <method name="getLayer">
 169     <arg direction="out" type="u" tp:type="ComponentLayer">
 170     <tp:docstring>
 171       the ComponentLayer in which this object resides.
 172     </tp:docstring>
 173     </arg>
 174   </method>
 175   <method name="getMDIZOrder">
 176     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 177       <p>Obtain the relative stacking order (i.e. 'Z' order) of an object.
 178         Larger values indicate that an object is on &quot;top&quot; of the stack, therefore
 179         objects with smaller MDIZOrder may be obscured by objects with a larger MDIZOrder,
 180         but not vice-versa.
 181         @note only relevant for objects in LAYER_MDI or LAYER_WINDOW </p>
 182     </tp:docstring>
 183     <arg direction="out" type="n" tp:type="short">
 184     <tp:docstring>
 185       an integer indicating the object's place in the stacking order.
 186     </tp:docstring>
 187     </arg>
 188   </method>
 189   <method name="grabFocus">
 190     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 191       <p>Request that the object obtain keyboard focus.    </p>
 192     </tp:docstring>
 193     <arg direction="out" type="b" tp:type="boolean">
 194     <tp:docstring>
 195       \c True if keyboard focus was successfully transferred to the Component.
 196     </tp:docstring>
 197     </arg>
 198   </method>
 199   <method name="registerFocusHandler">
 200     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 201       <p>Register an EventListener for notification when this object receives keyboard focus.
 202         @note you probably want to register for ¨focus:¨ events via
 203         Registry::registerGlobalEventListener instead. </p>
 204     </tp:docstring>
 205     <arg direction="in" name="handler" type="o" tp:type="EventListener"/>
 206   </method>
 207   <method name="deregisterFocusHandler">
 208     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 209       <p>Request that an EventListener registered via registerFocusHandler no longer be notified
 210         when this object receives keyboard focus.</p>
 211     </tp:docstring>
 212     <arg direction="in" name="handler" type="o" tp:type="EventListener"/>
 213   </method>
 214   <method name="getAlpha">
 215     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 216       <p>Obtain the alpha value of the component.  An alpha value of 1.0 or greater
 217         indicates that the object is fully opaque, and an alpha value of 0.0 indicates
 218         that the object is fully transparent.  Negative alpha values have no defined
 219         meaning at this time.    </p>
 220
 221       <p>@note alpha values are used in conjunction with Z-order calculations to
 222         determine whether an object wholly or partially obscures another object's
 223         visual intersection, in the event that their bounds intersect.    </p>
 224
 225       <p>@see STATE_OPAQUE    </p>
 226
 227       <p>@since AT-SPI 1.7.0</p>
 228     </tp:docstring>
 229     <arg direction="out" type="d"/>
 230   </method>
 231   <method name="unImplemented">
 232     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 233       <p>\cond
 234         unImplemented:    </p>
 235
 236       <p>placeholders for future expansion.</p>
 237     </tp:docstring>
 238   </method>
 239   <method name="unImplemented2">
 240   </method>
 241   <method name="unImplemented3">
 242   </method>
 243 </interface>
 244 </node>