other-licenses/ia2/AccessibleTextSelectionContainer.idl

   1 /*************************************************************************
   2  *
   3  *  File Name (accessibleTextSelectionContainer.idl)
   4  *
   5  *  IAccessible2 IDL Specification
   6  *
   7  *  Copyright (c) 2007, 2022 Linux Foundation
   8  *  Copyright (c) 2006 IBM Corporation
   9  *  Copyright (c) 2000, 2006 Sun Microsystems, Inc.
  10  *  All rights reserved.
  11  *
  12  *
  13  *  Redistribution and use in source and binary forms, with or without
  14  *  modification, are permitted provided that the following conditions
  15  *  are met:
  16  *
  17  *   1. Redistributions of source code must retain the above copyright
  18  *      notice, this list of conditions and the following disclaimer.
  19  *
  20  *   2. Redistributions in binary form must reproduce the above
  21  *      copyright notice, this list of conditions and the following
  22  *      disclaimer in the documentation and/or other materials
  23  *      provided with the distribution.
  24  *
  25  *   3. Neither the name of the Linux Foundation nor the names of its
  26  *      contributors may be used to endorse or promote products
  27  *      derived from this software without specific prior written
  28  *      permission.
  29  *
  30  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
  31  *  CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
  32  *  INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  33  *  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  34  *  DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
  35  *  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  36  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  37  *  NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  38  *  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  39  *  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  40  *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  41  *  OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  42  *  EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  43  *
  44  *  This BSD License conforms to the Open Source Initiative "Simplified
  45  *  BSD License" as published at:
  46  *  http://www.opensource.org/licenses/bsd-license.php
  47  *
  48  *  IAccessible2 is a trademark of the Linux Foundation. The IAccessible2
  49  *  mark may be used in accordance with the Linux Foundation Trademark
  50  *  Policy to indicate compliance with the IAccessible2 specification.
  51  *
  52  ************************************************************************/
  53
  54 import "objidl.idl";
  55 import "oaidl.idl";
  56 import "oleacc.idl";
  57 import "AccessibleText.idl";
  58
  59 /**
  60  This structure represents a single  text selection within an accessibility
  61  subtree. This could be within a document, or the subtree of a document. This
  62  selection is defined by two points in the content, where each one is defined by
  63  an accessible object supporting the IAccessibleTextInterface and an
  64  IAccessibleText character offset relative to it.
  65
  66  The end object must appear after the start object in the accessibility tree,
  67  i.e. the end object must be reachable from the start object by navigating
  68  forward (next, first child etc).
  69
  70  This struct also contains a `startIsActive` boolean, to communicate if the
  71  start of the selection is the active point or not.
  72
  73  The active point corresponds to the user's focus or point of interest. The user
  74  moves the active point to expand or collapse the range. The anchor point is
  75  the other point of the range and typically remains constant. In most cases,
  76  anchor is the start of the range and active is the end. However, when selecting
  77  backwards (e.g. pressing shift+left arrow in a text field), the start of the
  78  range is the active point, as the user moves this to manipulate the selection.
  79  */
  80 typedef struct IA2TextSelection {
  81   IAccessibleText* startObj;
  82   long startOffset;
  83   IAccessibleText* endObj;
  84   long endOffset;
  85   boolean startIsActive;
  86 } IA2TextSelection;
  87
  88 /**
  89  @brief an interface to get and set text selections in a document.
  90  this interface can be supported on any object that also supports the
  91  IAccessibleText and/or IAccessibleHypertext interfaces. This could be a
  92  document, any subtree of a document, or a text input control.
  93 */
  94 [object, uuid(2118B599-733F-43D0-A569-0B31D125ED9A)]
  95 interface IAccessibleTextSelectionContainer : IUnknown
  96 {
  97   /**
  98    @brief Returns an array of selections within this subtree.
  99    @param [out] selections
 100      The array of selections, allocated by the server. The client must free it
 101      with CoTaskMemFree. The selections returned will be cropped to fit entirely
 102      within this subtree, i.e. to only reference descendant objects, even if the
 103      physical selection may reach outside of this subtree. In the case where the
 104      physical selection is entirely outside the subtree, an empty array will be
 105      returned.
 106    @param [out] nSelections
 107      the array length
 108    @retval S_OK
 109    @retval S_FALSE returned if there are no selections within this subtree, or
 110      the physical selection is entirely outside of this subtree.
 111   */
 112   [propget] HRESULT selections
 113     (
 114       [out, size_is(,*nSelections)] IA2TextSelection **selections,
 115       [out, retval] long *nSelections
 116     );
 117
 118   /**
 119    @brief makes 1 or more selections within this subtree denoted by the given
 120    array of IA2TextSelections.
 121    Any existing physical selection (inside or outside this subtree) is replaced
 122    by the new selections. All objects within the given selection ranges must be
 123    descendants of this subtree, otherwise E_INVALIDARG will be returned.
 124    @param [in] nSelections
 125      The length of the array containing the selection ranges.
 126    @param [in] selections
 127      The array of selection ranges.
 128    @retval S_OK Returned if the selections were made successfully.
 129    @retval S_FALSE Returned if the selections could not be made.
 130    @retval E_INVALIDARG Returned if any of the input arguments are invalid, or
 131      any of the objects in the given ranges are outside of this subtree.
 132    */
 133   HRESULT setSelections
 134   (
 135       [in] long nSelections,
 136       [in, size_is(nSelections)] IA2TextSelection* selections
 137       );
 138
 139 }