pyatspi/hyperlink.py

   1 #Copyright (C) 2008 Codethink Ltd
   2
   3 #This library is free software; you can redistribute it and/or
   4 #modify it under the terms of the GNU Lesser General Public
   5 #License version 2 as published by the Free Software Foundation.
   6
   7 #This program is distributed in the hope that it will be useful,
   8 #but WITHOUT ANY WARRANTY; without even the implied warranty of
   9 #MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  10 #GNU General Public License for more details.
  11 #You should have received a copy of the GNU Lesser General Public License
  12 #along with this program; if not, write to the Free Software
  13 #Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  14
  15 import interfaces
  16 from base import BaseProxy
  17 from factory import accessible_factory
  18
  19 __all__ = [
  20            "Hyperlink",
  21           ]
  22
  23 #------------------------------------------------------------------------------
  24
  25 class Hyperlink(BaseProxy):
  26         """
  27         Instances of Hyperlink are returned by Hypertext objects, and
  28         are the means by which end users and clients interact with linked,
  29         and in some cases embedded, content. Hyperlinks may have multiple
  30         "anchors", where an anchor corresponds to a reference to a particular
  31         resource with a corresponding resource identified (URI). Hyperlinks
  32         may be queried for their URIs, or queried for the objects corresponding
  33         to their anchors. The objects thus obtained are instances of
  34         Accessible, and may be queried, and manipulated via the Action
  35         interface.
  36         """
  37
  38         def getObject(self, *args, **kwargs):
  39                 """
  40                 Gets the i'th object, (where i is an integer between 0 and Hyperlink::numAnchors
  41                 - 1, inclusive) associated with a Hyperlink. The objects returned
  42                 are usually actionable (i.e. they should implement Accessibility::Action),
  43                 and the available actions often include "open", "bookmark", "save
  44                 link as", etc. They may also implement Accessibility::StreamableContent,
  45                 although clients can normally use getURI to obtain a resource
  46                 locator via which the object's data may be accessed.
  47                 @return an Accessible object instance representing the Hyperlink's
  48                 ith anchor, or through which the content associated with the
  49                 ith anchor can be accessed.
  50                 """
  51                 func = self.get_dbus_method("getObject")
  52                 return func(*args, **kwargs)
  53
  54         def getURI(self, *args, **kwargs):
  55                 """
  56                 Obtain a resource locator ('URI') which can be used to access
  57                 the content to which this link "points" or is connected.
  58                 @return a string corresponding to the URI of the Hyperlink's
  59                 'ith' anchor, if one exists, or a NIL string otherwise.
  60                 """
  61                 func = self.get_dbus_method("getURI")
  62                 return func(*args, **kwargs)
  63
  64         def isValid(self, *args, **kwargs):
  65                 """
  66                 Check the hyperlink to see if a connection to its backing content
  67                 can be established, or if its URI is valid.
  68                 @return True if the object's content is available, or False if
  69                 the hyperlink's URI is invalid, or a connection to the resource
  70                 can not be established.
  71                 """
  72                 func = self.get_dbus_method("isValid")
  73                 return func(*args, **kwargs)
  74
  75         def get_endIndex(self):
  76                 return self._pgetter(self._dbus_interface, "endIndex")
  77         def set_endIndex(self, value):
  78                 self._psetter(self._dbus_interface, "endIndex", value)
  79         _endIndexDoc = \
  80                 """
  81                 the ending offset within the containing Hypertext content with
  82                 which this Hyperlink is associated; that is, the offset of the
  83                 first element past the range within the Hypertext associated
  84                 with this Hyperlink.
  85                 """
  86         endIndex = property(fget=get_endIndex, fset=set_endIndex, doc=_endIndexDoc)
  87
  88         def get_nAnchors(self):
  89                 return self._pgetter(self._dbus_interface, "nAnchors")
  90         def set_nAnchors(self, value):
  91                 self._psetter(self._dbus_interface, "nAnchors", value)
  92         _nAnchorsDoc = \
  93                 """
  94                 the number of separate anchors associated with this Hyperlink
  95                 """
  96         nAnchors = property(fget=get_nAnchors, fset=set_nAnchors, doc=_nAnchorsDoc)
  97
  98         def get_startIndex(self):
  99                 return self._pgetter(self._dbus_interface, "startIndex")
 100         def set_startIndex(self, value):
 101                 self._psetter(self._dbus_interface, "startIndex", value)
 102         _startIndexDoc = \
 103                 """
 104                 the starting offset within the containing Hypertext content with
 105                 which this Hyperlink is associated
 106                 """
 107         startIndex = property(fget=get_startIndex, fset=set_startIndex, doc=_startIndexDoc)
 108
 109 # Register the accessible class with the factory.
 110 accessible_factory.register_accessible_class(interfaces.ATSPI_HYPERLINK, Hyperlink)
 111
 112 #END----------------------------------------------------------------------------