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 add_accessible_class
  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         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
 161     COMMAND_RESULT_INVALID = CommandResult(0)
 162
 163     COMMAND_RESULT_LAST_DEFINED = CommandResult(4)
 164
 165     COMMAND_RESULT_OBSOLETE = CommandResult(3)
 166
 167     COMMAND_RESULT_SUCCESS = CommandResult(1)
 168
 169 # ATTENTION - Register the Application class with the accessible factory.
 170 add_accessible_class(interfaces.ATSPI_SELECTOR, Selector)
 171
 172 #END----------------------------------------------------------------------------