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