xml/Accessibility_Hyperlink.xml

   1 <node name="/node" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
   2
   3 <tp:title>AT-SPI - Assistive Technology Service Provider Interface </tp:title>
   4 <tp:copyright>Copyright 2008 Novell, Inc.</tp:copyright>
   5 <tp:copyright>Copyright 2001 Sun Microsystems, Inc.</tp:copyright>
   6 <tp:license xmlns="http://www.w3.org/1999/xhtml">
   7   <p>This library is free software; you can redistribute it and/or
   8     modify it under the terms of the GNU Library General Public
   9     License as published by the Free Software Foundation; either
  10     version 2 of the License, or (at your option) any later version.</p>
  11
  12   <p>This library is distributed in the hope that it will be useful,
  13     but WITHOUT ANY WARRANTY; without even the implied warranty of
  14     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15     Library General Public License for more details.</p>
  16
  17   <p>You should have received a copy of the GNU Library General Public
  18     License along with this library; if not, write to the
  19     Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20     Boston, MA 02111-1307, USA.</p>
  21 </tp:license>
  22 <interface name="org.freedesktop.accessibility.Hyperlink">
  23   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  24     <p>Instances of Hyperlink are returned by Hypertext objects, and are
  25       the means by which end users and clients interact with linked, and in
  26       some cases embedded, content.  Hyperlinks may have multiple &quot;anchors&quot;,
  27       where an anchor corresponds to a reference to a particular resource with
  28       a corresponding resource identified (URI).  Hyperlinks may be
  29       queried for their URIs, or queried for the objects corresponding to their
  30       anchors.  The objects thus obtained are instances of Accessible,
  31       and may be queried, and manipulated via the Action interface.   </p>
  32
  33     <p>@note A Hyperlink implementor is normally NOT an Accessible;
  34       the preferred usage is for a Hyperlink's associated &quot;objects&quot;
  35       (accessed via the ::getObject method) are Accessibles.  This means
  36       that Actions such as &quot;open link&quot; are normally invoked on
  37       the result of Hyperlink::getObject rather than directly on the
  38       Hyperlink instance. For historical reasons some implementors of Hyperlink
  39       implement Action as well.  This usage on the part of implementing
  40       applications and toolkits is discouraged, but clients of Hyperlink
  41       should be aware of it and prepared to handle such usage.</p>
  42   </tp:docstring>
  43   <tp:property name="nAnchors" type="n" access="read">
  44   <tp:docstring>
  45     the number of separate anchors associated with this Hyperlink
  46   </tp:docstring>
  47   </tp:property>
  48   <tp:property name="startIndex" type="i" access="read">
  49   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  50     <p>the starting offset within the containing Hypertext content
  51       with which this Hyperlink is associated </p>
  52   </tp:docstring>
  53   </tp:property>
  54   <tp:property name="endIndex" type="i" access="read">
  55   <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  56     <p>the ending offset within the containing Hypertext content
  57       with which this Hyperlink is associated; that is, the offset of the
  58       first element past the range within the Hypertext associated with
  59       this Hyperlink. </p>
  60   </tp:docstring>
  61   </tp:property>
  62   <method name="getObject">
  63     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  64       <p>Gets the i'th object, (where i is an integer between 0 and
  65         Hyperlink::numAnchors - 1, inclusive) associated with a Hyperlink.
  66         The objects returned are usually actionable (i.e. they should implement
  67         Accessibility::Action), and the available actions often include
  68         &quot;open&quot;, &quot;bookmark&quot;, &quot;save link as&quot;, etc.  They may also implement
  69         Accessibility::StreamableContent, although clients can normally use
  70         ::getURI to obtain a resource locator via which the object's
  71         data may be accessed.    </p>
  72
  73       <p>@note the most common application for 'multi anchor'
  74         hyperlinks in HTML is probably &quot;client side imagemaps&quot;.
  75         A clickable image which uses the HTML 'usemap' attribute
  76         should have one anchor for every &lt;area&gt; element that
  77         includes an HREF.  The objects corresponding to these map
  78         areas may implement Accessibility::Component, to represent
  79         their onscreen bounding box, and may expose their 'shape' as
  80         as name-value pair via Accessibility::Accessible::getAttributeSet.    </p>
  81     </tp:docstring>
  82     <arg direction="in" name="i" type="i"/>
  83     <arg direction="out" type="o" tp:type="Accessible">
  84     <tp:docstring>
  85       an Accessible object instance representing theHyperlink's ith anchor, or through which the content associated withthe \c ith anchor can beaccessed.
  86     </tp:docstring>
  87     </arg>
  88   </method>
  89   <method name="getURI">
  90     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  91       <p>Obtain a resource locator ('URI') which can be used to
  92         access the content to which this link &quot;points&quot; or is connected.</p>
  93     </tp:docstring>
  94     <arg direction="in" name="i" type="i"/>
  95     <arg direction="out" type="s">
  96     <tp:docstring>
  97       a string corresponding to the URI of the Hyperlink's'ith' anchor, if one exists, or a NIL string otherwise.
  98     </tp:docstring>
  99     </arg>
 100   </method>
 101   <method name="isValid">
 102     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 103       <p>Check the hyperlink to see if a connection to its backing
 104         content can be established, or if its URI is valid.
 105         @note instances of invalid hyperlinks include links with malformed
 106         URIs, or for which a contact to the service provider
 107         specified in the URI cannot be established.</p>
 108     </tp:docstring>
 109     <arg direction="out" type="b" tp:type="boolean">
 110     <tp:docstring>
 111       \c True if the object's content is available, or\c False if the hyperlink's URI is invalid, or a connection to the resource can not be established.
 112     </tp:docstring>
 113     </arg>
 114   </method>
 115   <method name="unImplemented">
 116     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 117       <p>\cond
 118         unImplemented:    </p>
 119
 120       <p>placeholders for future expansion.</p>
 121     </tp:docstring>
 122   </method>
 123   <method name="unImplemented2">
 124   </method>
 125   <method name="unImplemented3">
 126   </method>
 127   <method name="unImplemented4">
 128   </method>
 129 </interface>
 130 </node>