AccessibleTextSelectionContainer.idl (6045B)
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 }