other-licenses/ia2/Accessible2.idl

   1 /*************************************************************************
   2  *
   3  *  File Name (Accessible2.idl)
   4  *
   5  *  IAccessible2 IDL Specification
   6  *
   7  *  Copyright (c) IBM Corp. 2007
   8  *  Copyright (c) Sun Microsystems, Inc. 2000, 2006
   9  *
  10  *  This library is free software; you can redistribute it and/or
  11  *  modify it under the terms of the GNU Lesser General Public
  12  *  License version 2.1, as published by the Free Software Foundation; either
  13  *  version 2.1 of the License, or (at your option) any later version.
  14  *
  15  *  This library is distributed in the hope that it will be useful,
  16  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18  *  Lesser General Public License for more details.
  19  *
  20  *  You should have received a copy of the GNU Lesser General Public
  21  *  License along with this library; if not, write to the Free Software
  22  *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02110-1301  USA
  23  *
  24  ************************************************************************/
  25
  26 /** @mainpage
  27
  28  @section _interfaces Interfaces
  29   IAccessible2\n
  30   IAccessibleAction\n
  31   IAccessibleApplication\n
  32   IAccessibleComponent\n
  33   IAccessibleHypertext\n
  34   IAccessibleHyperlink\n
  35   IAccessibleImage\n
  36   IAccessibleRelation\n
  37   IAccessibleTable\n
  38   IAccessibleText\n
  39   IAccessibleEditableText\n
  40   IAccessibleValue
  41
  42  @section _structs Structs
  43   IA2Locale\n
  44   IA2TableModelChange\n
  45   IA2TextSegment
  46
  47  @section _enums Enums
  48   ::IA2CoordinateType values define the requested coordinate type (screen or parent window).\n
  49   ::IA2EventID values identify events.\n
  50   ::IA2Role values define roles.\n
  51   ::IA2ScrollType values define where to place an object or substring on the screen.\n
  52   ::IA2TableModelChangeType values describe the kinds of changes made to a table (insert, delete, update).\n
  53   ::IA2TextBoundaryType values define the requested text unit (character, word, sentence, line, paragraph).
  54
  55  @section _constants Constants
  56   @ref grpRelations\n
  57   @ref grpStates\n
  58
  59  @section _license License
  60   @ref _licensePage "LGPL"
  61
  62  @page _licensePage License
  63   IAccessible2 IDL Specification
  64
  65   Copyright (c) IBM Corp. 2006\n
  66   Copyright (c) Sun Microsystems, Inc. 2000, 2006
  67
  68   This library is free software; you can redistribute it and/or
  69   modify it under the terms of the GNU Lesser General Public
  70   License version 2.1, as published by the Free Software Foundation; either
  71   version 2.1 of the License, or (at your option) any later version.
  72
  73   This library is distributed in the hope that it will be useful,
  74   but WITHOUT ANY WARRANTY; without even the implied warranty of
  75   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  76   Lesser General Public License for more details.
  77
  78   You should have received a copy of the GNU Lesser General Public
  79   License along with this library; if not, write to the Free Software
  80   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02110-1301  USA
  81
  82   You may also refer to http://www.gnu.org/licenses/lgpl.html
  83
  84 **/
  85
  86 import "objidl.idl";
  87 import "oaidl.idl";
  88 import "oleacc.idl";
  89 import "AccessibleRelation.idl";
  90 import "AccessibleStates.idl";
  91 import "IA2CommonTypes.idl";
  92
  93 /// A structure defining the locale of an accessible object.
  94 typedef struct {
  95   BSTR language; ///< ISO 639-1 Alpha-2 two character language code
  96   BSTR country;  ///< ISO 3166-1 Alpha-2 two character country code
  97   BSTR variant;  ///< Application specific variant of the locale
  98 } IA2Locale;
  99
 100 /** This interface must always be provided for objects that support some
 101  portion of the collection of the IAccessible2 interfaces.
 102
 103  IAccessible2 is a subclass of MSAA's IAccessible.  This is a matter of
 104  convenience, i.e. an IAccessible2 is an IAccessible so MSAA methods can be
 105  easily accessed. None of MSAA's IAccessible methods are overridden or extended.
 106  */
 107 [object, uuid(E89F726E-C4F4-4c19-BB19-B647D7FA8478)]
 108 interface IAccessible2 : IAccessible
 109 {
 110
 111   /** @brief Returns the number of accessible relations for this object.
 112    @param [out] nRelations
 113   */
 114   [propget] HRESULT nRelations
 115     (
 116      [out, retval] long *nRelations
 117     );
 118
 119   /** @brief Returns one accessible relation for this object.
 120    @param [in] relationIndex
 121      0-based
 122    @param [out] relation
 123   */
 124   [propget] HRESULT relation
 125     (
 126      [in] long relationIndex,
 127      [out, retval] IAccessibleRelation **relation
 128     );
 129
 130   /** @brief Returns multiple accessible relations for this object.
 131    @param [in] maxRelations
 132     maximum number of relations to get
 133    @param [out] relation
 134     array of accessible relation objects
 135    @param [out] nRelations
 136     length of array (not more than maxRelations)
 137   */
 138   [propget] HRESULT relations
 139     (
 140      [in] long maxRelations,
 141      [out, size_is(maxRelations), length_is(*nRelations)]
 142        IAccessibleRelation **relation,
 143      [out, retval] long *nRelations
 144     );
 145
 146   /** @brief Returns the role of an IAccessible2 object.
 147
 148    Note:  For convenience MSAA roles are also passed through this method so the
 149     AT doesn't have to also fetch roles through MSAA's get_accRole.
 150    @param [out] role
 151     The role of an IAccessible2 object.
 152   */
 153   HRESULT role
 154     (
 155      [out, retval] long *role
 156     );
 157
 158   /** @brief Makes an object visible on the screen.
 159    @param [in] scrollType
 160     Defines where the object should be placed on the screen.
 161   */
 162   HRESULT scrollTo
 163     (
 164      [in] enum IA2ScrollType scrollType
 165     );
 166
 167   /** @brief Moves the top left of an object to a specified location.
 168
 169    Note: S_FALSE is returned if the object is already at the specified location.
 170    @param [in] coordinateType
 171     Specifies whether the coordinates are relative to the screen or the parent object.
 172    @param [in] x
 173     Defines the x coordinate.
 174    @param [in] y
 175     Defines the y coordinate.
 176   */
 177   HRESULT scrollToPoint
 178     (
 179      [in] enum IA2CoordinateType coordinateType,
 180          [in] long x,
 181          [in] long y
 182     );
 183
 184   /** @brief Returns grouping information.
 185
 186    Used for tree items, list items, tab panel labels, radio buttons, etc.
 187    Also used for collectons of non-text objects.
 188
 189    @param [out] groupLevel
 190     0-based
 191    @param [out] similarItemsInGroup
 192     1-based
 193    @param [out] positionInGroup
 194     0-based
 195   */
 196   [propget] HRESULT groupPosition
 197     (
 198      [out] long *groupLevel,
 199      [out] long *similarItemsInGroup,
 200      [out, retval] long *positionInGroup
 201     );
 202
 203   /** @brief Returns the bit strip containing any IAccessible2 states.
 204    @param [out] states
 205   */
 206   [propget] HRESULT states
 207     (
 208          [out, retval] AccessibleStates *states
 209     );
 210
 211   /** @brief Returns the extended role.
 212
 213    An extended role is a role which is dynamically generated by the application.
 214    It is not predefined by the IAccessible2 specification.
 215
 216    @param [out] extendedRole
 217   */
 218   [propget] HRESULT extendedRole
 219     (
 220          [out, retval] BSTR *extendedRole
 221     );
 222
 223   /** @brief Returns the localized extended role.
 224    @param [out] localizedExtendedRole
 225   */
 226   [propget] HRESULT localizedExtendedRole
 227     (
 228          [out, retval] BSTR *localizedExtendedRole
 229     );
 230
 231   /** @brief Returns the number of extended states.
 232    @param [out] nExtendedStates
 233   */
 234   [propget] HRESULT nExtendedStates
 235     (
 236      [out, retval] long *nExtendedStates
 237     );
 238
 239   /** @brief Returns the extended states (array of strings).
 240
 241    An extended state is a state which is dynamically generated by the application.
 242    It is not predefined by the IAccessible2 specification.
 243
 244    @param [in] maxExtendedStates
 245    @param [out] extendedStates
 246    @param [out] nExtendedStates
 247   */
 248   [propget] HRESULT extendedStates
 249     (
 250      [in] long maxExtendedStates,
 251      [out, size_is(,maxExtendedStates), length_is(,*nExtendedStates)] BSTR **extendedStates,
 252      [out, retval] long *nExtendedStates
 253     );
 254
 255   /** @brief Returns the localized extended states (array of strings).
 256    @param [in] maxLocalizedExtendedStates
 257    @param [out] localizedExtendedStates
 258    @param [out] nLocalizedExtendedStates
 259   */
 260   [propget] HRESULT localizedExtendedStates
 261     (
 262      [in] long maxLocalizedExtendedStates,
 263      [out, size_is(,maxLocalizedExtendedStates), length_is(,*nLocalizedExtendedStates)] BSTR **localizedExtendedStates,
 264      [out, retval] long *nLocalizedExtendedStates
 265     );
 266
 267   /** @brief Returns the unique ID.
 268
 269    The uniqueID is an identifier for this object, is unique within the
 270    current window, and remains the same for the lifetime of the accessible
 271    object. This is the same value that is passed in the idChild parameter of
 272    the WinEventProc callback function for any events that occur on the object,
 273    and is typically a negative number. Using negative numbers prevents the ID
 274    from conflicting with the use of positive numbers that might possibly be
 275    used to indicate a direct child N of the window's root accessible object,
 276    and thus the implementation of get_accChild() can differentiate between
 277    requests for direct child N vs. a descendant lower in the hierarchy with a
 278    given uniqueID.  This is important because get_accChild() is used by
 279    AccessibleObjectFromEvent() to retrieve the accessible object which fired
 280    the event by starting from the window's root accessible object.
 281
 282    This value is provided so the AT can have access to it even when not
 283    handling an event for the object.
 284
 285    An example of when this value is useful if the AT wants to build a cache.
 286    The AT could cache the uniqueIDs in addition to other data being cached.
 287    When an event is fired the AT could map that to its internal model.  Thus,
 288    if there's a REORDER/SHOW/HIDE event the AT knows which part of the internal
 289    structure has been invalidated and can refetch just that part.
 290
 291    This value can also be used by and AT to determine when the current control
 292    has changed. If the role is the same for two controls that are adjacent in
 293    the tab order, this can be used to detect the new control.
 294
 295    Another use of this value by an AT is to identify when a grouping object has
 296    changed, e.g. when moving from a radio button in one group to a radio button in a
 297    different group.
 298
 299    @param [out] uniqueID
 300   */
 301   [propget] HRESULT uniqueID
 302     (
 303      [out, retval] long *uniqueID
 304     );
 305
 306   /** @brief Returns the window handle for the parent window which contains this object.
 307
 308    This is the same window handle which will be passed for any events that occur on the
 309    object, but is cached in the accessible object for use when it would be helpful to
 310    access the window handle in cases where an event isn't fired on this object.
 311
 312    A use case is when a screen reader is grabbing an entire web page on a page load.
 313    Without the availability of windowHandle, the AT would have to get the window handle
 314    by using WindowFromAccessibleObject on each IAccessible, which is slow because it's
 315    implemented by oleacc.dll as a loop which crawls up the ancestor chain and looks for
 316    a ROLE_WINDOW object, mapping that back to a window handle.
 317
 318    @param [out] windowHandle
 319   */
 320   [propget] HRESULT windowHandle
 321     (
 322      [out, retval] HWND *windowHandle
 323     );
 324
 325   /** @brief Returns the index of this object in its parent object.
 326    @param [out] indexInParent
 327   */
 328   [propget] HRESULT indexInParent
 329     (
 330      [out, retval] long *indexInParent
 331     );
 332
 333   /** @brief Returns the IA2Locale of the accessible object.
 334    @param [out] locale
 335   */
 336   [propget] HRESULT locale
 337     (
 338      [out, retval] IA2Locale *locale
 339     );
 340
 341   /** @brief Returns the attributes specific to this IAccessible2 object, such as a cell's formula.
 342    @param [out] attributes
 343   */
 344   [propget] HRESULT attributes
 345     (
 346      [out, retval] BSTR *attributes
 347     );
 348
 349 }
 350