2 * AT-SPI - Assistive Technology Service Provider Interface
3 * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
5 * Copyright 2001 Sun Microsystems, Inc.
7 * 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.
12 * 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.
17 * 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.
23 #include <Accessibility_Accessible.idl>
25 module Accessibility {
28 * Instances of Hyperlink are returned by Hypertext objects, and are
29 * the means by which end users and clients interact with linked, and in
30 * some cases embedded, content. Hyperlinks may have multiple "anchors",
31 * where an anchor corresponds to a reference to a particular resource with
32 * a corresponding resource identified (URI). Hyperlinks may be
33 * queried for their URIs, or queried for the objects corresponding to their
34 * anchors. The objects thus obtained are instances of Accessible,
35 * and may be queried, and manipulated via the Action interface.
37 * @note A Hyperlink implementor is normally NOT an Accessible;
38 * the preferred usage is for a Hyperlink's associated "objects"
39 * (accessed via the ::getObject method) are Accessibles. This means
40 * that Actions such as "open link" are normally invoked on
41 * the result of Hyperlink::getObject rather than directly on the
42 * Hyperlink instance. For historical reasons some implementors of Hyperlink
43 * implement Action as well. This usage on the part of implementing
44 * applications and toolkits is discouraged, but clients of Hyperlink
45 * should be aware of it and prepared to handle such usage.
47 interface Hyperlink : Bonobo::Unknown {
48 /** the number of separate anchors associated with this Hyperlink */
49 readonly attribute short nAnchors;
51 * the starting offset within the containing Hypertext content
52 * with which this Hyperlink is associated
54 readonly attribute long startIndex;
56 * 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
61 readonly attribute long endIndex;
63 * Gets the i'th object, (where i is an integer between 0 and
64 * Hyperlink::numAnchors - 1, inclusive) associated with a Hyperlink.
65 * The objects returned are usually actionable (i.e. they should implement
66 * Accessibility::Action), and the available actions often include
67 * "open", "bookmark", "save link as", etc. They may also implement
68 * Accessibility::StreamableContent, although clients can normally use
69 * ::getURI to obtain a resource locator via which the object's
70 * data may be accessed.
72 * @note the most common application for 'multi anchor'
73 * hyperlinks in HTML is probably "client side imagemaps".
74 * A clickable image which uses the HTML 'usemap' attribute
75 * should have one anchor for every <area> element that
76 * includes an HREF. The objects corresponding to these map
77 * areas may implement Accessibility::Component, to represent
78 * their onscreen bounding box, and may expose their 'shape' as
79 * as name-value pair via Accessibility::Accessible::getAttributeSet.
81 * @returns an Accessible object instance representing the
82 * Hyperlink's ith anchor, or through which the content associated with
83 * the \c ith anchor can be
86 Accessible getObject (in long i);
88 * Obtain a resource locator ('URI') which can be used to
89 * access the content to which this link "points" or is connected.
90 * @returns a string corresponding to the URI of the Hyperlink's
91 * 'ith' anchor, if one exists, or a NIL string otherwise.
93 string getURI (in long i);
95 * Check the hyperlink to see if a connection to its backing
96 * content can be established, or if its URI is valid.
97 * @note instances of invalid hyperlinks include links with malformed
98 * URIs, or for which a contact to the service provider
99 * specified in the URI cannot be established.
100 * @returns \c True if the object's content is available, or
101 * \c False if the hyperlink's URI is invalid, or
102 * a connection to the resource can not be established.
108 * placeholders for future expansion.
110 void unImplemented ();
111 void unImplemented2 ();
112 void unImplemented3 ();
113 void unImplemented4 ();