The Tor Browser / file comparison
comparison: other-licenses/ia2/AccessibleHyperlink.idl
other-licenses/ia2/AccessibleHyperlink.idl
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
equal
deleted
inserted
replaced
| -1:000000000000 | 0:da973c2b9409 |
|---|---|
| 1 /************************************************************************* | |
| 2 * | |
| 3 * File Name (AccessibleHyperlink.idl) | |
| 4 * | |
| 5 * IAccessible2 IDL Specification | |
| 6 * | |
| 7 * Copyright (c) 2007, 2010 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 "AccessibleAction.idl"; | |
| 58 | |
| 59 /** @brief This interface represents hyperlinks. | |
| 60 | |
| 61 This interface represents a hyperlink associated with a single substring | |
| 62 of text or single non-text object. Non-text objects can have either a | |
| 63 single link or a collection of links such as when the non-text object is | |
| 64 an image map. | |
| 65 | |
| 66 Linked objects and anchors are implementation dependent. This interface is derived | |
| 67 from IAccessibleAction. IAccessibleAction::nActions is one greater than the | |
| 68 maximum value for the indices used with the methods of this interface. | |
| 69 | |
| 70 Furthermore, the object that implements this interface has to be connected | |
| 71 implicitly or explicitly with an object that implements IAccessibleText. | |
| 72 IAccessibleHyperlink::startIndex and IAccessibleHyperlink::endIndex are | |
| 73 indices with respect to the text exposed by IAccessibleText. | |
| 74 | |
| 75 This interface provides access to a single object which can have multiple actions. | |
| 76 An example is an image map which is an image with multiple links each of which is | |
| 77 associated with a separate non-overlapping area of the image. This interface could | |
| 78 also be applied to other kinds of objects with multiple actions such as "smart tags" | |
| 79 which are objects, typically strings, which have multiple actions such as | |
| 80 "Activate URI", "Bookmark URI", etc. | |
| 81 | |
| 82 An interesting use case is an image map where each area is associated with multiple | |
| 83 actions, e.g. an image map of smart tags. In this case you would have to implement | |
| 84 two levels of accessible hyperlinks. The first level hyperlinks would only implement | |
| 85 anchor and anchorTarget. The anchors would all reference the image object. The | |
| 86 anchorTargets would reference the second level accessible hyperlink objects. None | |
| 87 of the IAccessibleAction methods would be implemented on the first level hyperlink | |
| 88 objects. The second level hyperlink objects would implement the IAccessibleAction | |
| 89 methods. Their anchors would also reference the image object and their anchorTargets | |
| 90 would reference URLs or the objects that would be activated. | |
| 91 | |
| 92 This use case demonstrates that in some cases there is no need for IAccessibleHyperlink | |
| 93 to derive from IAccessibleAction. As a result it may be removed in a later version of | |
| 94 the IDL and it is suggested that implementations should not rely on the inheritance. | |
| 95 | |
| 96 */ | |
| 97 [object, uuid(01C20F2B-3DD2-400f-949F-AD00BDAB1D41)] | |
| 98 interface IAccessibleHyperlink : IAccessibleAction | |
| 99 { | |
| 100 | |
| 101 /** @brief Returns an object that represents the link anchor, as appropriate | |
| 102 for the link at the specified index. | |
| 103 @param [in] index | |
| 104 A 0 based index identifies the anchor when, as in the case of an image map, | |
| 105 there is more than one link represented by this object. The valid maximal | |
| 106 index is indicated by IAccessibleAction::nActions. | |
| 107 @param [out] anchor | |
| 108 This is an implementation dependent value. For example, for a text link this | |
| 109 method could return the substring of the containing string where the substring | |
| 110 is overridden with link behavior, and for an image link this method could return | |
| 111 an IUnknown VARIANT for IAccessibleImage. See the section about | |
| 112 @ref _variants "VARIANTs" for additional information. | |
| 113 @retval S_OK | |
| 114 @retval E_INVALIDARG if bad [in] passed | |
| 115 */ | |
| 116 [propget] HRESULT anchor | |
| 117 ( | |
| 118 [in] long index, | |
| 119 [out, retval] VARIANT *anchor | |
| 120 ); | |
| 121 | |
| 122 /** @brief Returns an object representing the target of the link, as appropriate | |
| 123 for the link at the specified index. | |
| 124 @param [in] index | |
| 125 A 0 based index identifies the anchor when, as in the case of an image map, | |
| 126 there is more than one link represented by this object. The valid maximal | |
| 127 index is indicated by IAccessibleAction::nActions. | |
| 128 @param [out] anchorTarget | |
| 129 This is an implementation dependent value. For example this method could | |
| 130 return a BSTR VARIANT of the URI. Alternatively this method could return an | |
| 131 IUnknown VARIANT of a COM interface representing a target object to be | |
| 132 activated when the link is activated. See the section about | |
| 133 @ref _variants "VARIANTs" for additional information. | |
| 134 @retval S_OK | |
| 135 @retval E_INVALIDARG if bad [in] passed | |
| 136 */ | |
| 137 [propget] HRESULT anchorTarget | |
| 138 ( | |
| 139 [in] long index, | |
| 140 [out, retval] VARIANT *anchorTarget | |
| 141 ); | |
| 142 | |
| 143 /** @brief Returns the 0 based character offset at which the textual representation of the hyperlink starts. | |
| 144 | |
| 145 The returned value is related to the IAccessibleText interface of the object that | |
| 146 owns this hyperlink. | |
| 147 @param [out] index | |
| 148 @retval S_OK | |
| 149 */ | |
| 150 [propget] HRESULT startIndex | |
| 151 ( | |
| 152 [out, retval] long *index | |
| 153 ); | |
| 154 | |
| 155 /** @brief Returns the 0 based character offset at which the textual representation of the hyperlink ends. | |
| 156 | |
| 157 The returned value is related to the IAccessibleText interface of the object that | |
| 158 owns this hyperlink. The character at the index is not part of the hypertext. | |
| 159 @param [out] index | |
| 160 @retval S_OK | |
| 161 */ | |
| 162 [propget] HRESULT endIndex | |
| 163 ( | |
| 164 [out, retval] long *index | |
| 165 ); | |
| 166 | |
| 167 /** @brief Returns whether the target object referenced by this link is still valid. | |
| 168 | |
| 169 This is a volatile state that may change without sending an appropriate event. | |
| 170 Returns TRUE if the referenced target is still valid and FALSE otherwise. | |
| 171 | |
| 172 This has also been used to indicate whether or not the URI of the anchorTarget | |
| 173 is malformed. | |
| 174 | |
| 175 @param [out] valid | |
| 176 If false, one or more of the object's links are invalid. | |
| 177 If true, all of the object's links are valid. | |
| 178 @retval S_OK | |
| 179 @retval S_FALSE if there is nothing to return, [out] value is FALSE | |
| 180 @note This method is not being used, is deprecated, and should not be implemented or | |
| 181 used. It is likely that this method will be removed in a later version of the IDL. | |
| 182 */ | |
| 183 [propget] HRESULT valid | |
| 184 ( | |
| 185 [out, retval] boolean *valid | |
| 186 ); | |
| 187 } |
