other-licenses/ia2/AccessibleHyperlink.idl

   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 }