pyatspi/selector.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, Enum
  17 from factory import accessible_factory
  18
  19 __all__ = [
  20            "Selector",
  21            "Command",
  22            "CommandListener",
  23           ]
  24
  25 #------------------------------------------------------------------------------
  26
  27 class Command(list):
  28         def __new__(cls, name, id):
  29                 list.__new__(cls, (name, id))
  30         def __init__(self, name, id):
  31                 list.__init__(self, (name, id))
  32
  33         def _get_name(self):
  34                 return self[0]
  35         def _set_name(self, val):
  36                 self[0] = val
  37         name = property(fget=_get_name, fset=_set_name)
  38         def _get_id(self):
  39                 return self[1]
  40         def _set_id(self, val):
  41                 self[1] = val
  42         id = property(fget=_get_id, fset=_set_id)
  43
  44 #------------------------------------------------------------------------------
  45
  46 class CommandListener(BaseProxy):
  47         """
  48         An interface which should be implemented by assistive technologies
  49         or other clients of the Selector interface, over which notifications
  50         to the list of available commands is made. The notifyCommands()
  51         method of the client is then called by the Selector instance.
  52         """
  53         def notifyCommands(self, *args, **kwargs):
  54                 """
  55                 Notify the CommandListener instance of changes to the currently
  56                 available commands, by sending the current CommandList.
  57                 @param : commands
  58                 The newly-available list of Command objects which may be invoked
  59                 by the listener.
  60                 """
  61                 func = self.get_dbus_method("notifyCommands")
  62                 return func(*args, **kwargs)
  63
  64 #------------------------------------------------------------------------------
  65
  66 class Selector(BaseProxy):
  67         """
  68         This interface is intended for use by assistive technologies
  69         and related user-agents. Via this interface, an assistive technology
  70         or user agent may expose a series of choices or selections in
  71         textual form, which can be activated on demand by a client of
  72         the Selector interface.
  73         Examples of the use of this interface include voice-command and
  74         remote-control applications, in which the user interaction is
  75         wholly or partly delegated by the implementor to an external
  76         agent.
  77         """
  78
  79         def activateCommand(self, *args, **kwargs):
  80                 """
  81                 Request that the Selector invoke the specified Command.
  82                 @param : cmd
  83                 the Command to activate/invoke.
  84                 @return a CommandResult indicating whether the request was honored,
  85                 and the reason for failure if the Command could not be activated
  86                 or invoked.
  87                 """
  88                 func = self.get_dbus_method("activateCommand")
  89                 return func(*args, **kwargs)
  90
  91         def deregisterChangeListener(self, *args, **kwargs):
  92                 """
  93                 Tell the Selector instance to cease notifying the specified CommandListener
  94                 of changes to the command list.
  95                 @param : listener
  96                 the CommandListener to remove from the notification list.
  97                 """
  98                 func = self.get_dbus_method("deregisterChangeListener")
  99                 return func(*args, **kwargs)
 100
 101         def getCommands(self, *args, **kwargs):
 102                 """
 103                 Query the Selector for the current CommandList.
 104                 @return the currently available CommandList
 105                 """
 106                 func = self.get_dbus_method("getCommands")
 107                 return func(*args, **kwargs)
 108
 109         def refreshCommands(self, *args, **kwargs):
 110                 """
 111                 Ask the Selector to re-calculate its CommandList.
 112                 @return TRUE if the CommandList changed.
 113                 """
 114                 func = self.get_dbus_method("refreshCommands")
 115                 return func(*args, **kwargs)
 116
 117         def registerChangeListener(self, *args, **kwargs):
 118                 """
 119                 Register a :CommandListener instance for notification of changes
 120                 to the command set.
 121                 @param : listener
 122                 the CommandListener to be notified of changes.
 123                 """
 124                 func = self.get_dbus_method("registerChangeListener")
 125                 return func(*args, **kwargs)
 126
 127         def replaceCommands(self, *args, **kwargs):
 128                 """
 129                 @return TRUE if the replacement request was successful, FALSE
 130                 if the request could not be honored.
 131                 """
 132                 func = self.get_dbus_method("replaceCommands")
 133                 return func(*args, **kwargs)
 134
 135         def get_supportsReplace(self):
 136                 return self._pgetter(self._dbus_interface, "supportsReplace")
 137         def set_supportsReplace(self, value):
 138                 self._psetter(self._dbus_interface, "supportsReplace", value)
 139         _supportsReplaceDoc = \
 140                 """
 141                 This attribute is TRUE if this Selector allows its CommandList
 142                 to be specified by the client
 143                 """
 144         supportsReplace = property(fget=get_supportsReplace, fset=set_supportsReplace, doc=_supportsReplaceDoc)
 145
 146         class CommandResult(Enum):
 147                 """
 148                 A code returned by a call to activateCommand, indicating the
 149                 result of the activation request.
 150                 """
 151                 _enum_lookup = {
 152                         0:'COMMAND_RESULT_INVALID',
 153                         1:'COMMAND_RESULT_SUCCESS',
 154                         2:'COMMAND_RESULT_FAILED',
 155                         3:'COMMAND_RESULT_OBSOLETE',
 156                         4:'COMMAND_RESULT_LAST_DEFINED',
 157                 }
 158
 159         COMMAND_RESULT_FAILED = CommandResult(2)
 160         COMMAND_RESULT_INVALID = CommandResult(0)
 161         COMMAND_RESULT_LAST_DEFINED = CommandResult(4)
 162         COMMAND_RESULT_OBSOLETE = CommandResult(3)
 163         COMMAND_RESULT_SUCCESS = CommandResult(1)
 164
 165 # Register the accessible class with the factory.
 166 accessible_factory.register_accessible_class(interfaces.ATSPI_SELECTOR, Selector)
 167
 168 #END----------------------------------------------------------------------------