pyatspi/selection.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 accessible import Accessible
  17 from factory import accessible_factory
  18
  19 import dbus
  20
  21 __all__ = [
  22            "Selection",
  23           ]
  24
  25 #------------------------------------------------------------------------------
  26
  27 class Selection(Accessible):
  28         """
  29         An interface which indicates that an object exposes a 'selection'
  30         model, allowing the selection of one or more of its children.
  31         Read-only Selection instances are possible, in which case the
  32         interface is used to programmatically determine the selected-ness
  33         of its children. A selected child has State::STATE_SELECTED,
  34         and a child which may hypothetically be selected (though possibly
  35         not programmatically selectable) has State::STATE_SELECTABLE.
  36         """
  37
  38         def clearSelection(self):
  39                 """
  40                 Attempt to clear all selections (i.e. deselect all children)
  41                 of a Selection. Not all Selection implementations allow the removal
  42                 of all selections.
  43                 @return True if the selections were successfully cleared, False
  44                 otherwise.
  45                 """
  46                 func = self.get_dbus_method("clearSelection", dbus_interface=ATSPI_SELECTION)
  47                 return func()
  48
  49         def deselectChild(self, *args, **kwargs):
  50                 """
  51                 Remove a child from the selected children list of a Selection,
  52                 if the child is currently selected.
  53                 @param : childIndex
  54                 a long integer (the zero offset index into the Accessible object's
  55                 list of children) indicating which child of the Selection is
  56                 to be selected.
  57                 @return True if the child was successfully selected, False otherwise.
  58                 """
  59                 func = self.get_dbus_method("deselectChild", dbus_interface=ATSPI_SELECTION)
  60                 return func(*args, **kwargs)
  61
  62         def deselectSelectedChild(self, index):
  63                 """
  64                 Remove a child to the selected children list of a Selection.
  65                 @param : selectedChildIndex
  66                 a long integer indicating which of the selected children of the
  67                 Selection is to be deselected. The index is a zero-offset index
  68                 into the 'selected child list', not a zero-offset index into
  69                 the list of all children of the Selection.
  70                 @return True if the child was successfully deselected, False
  71                 otherwise.
  72                 """
  73                 func = self.get_dbus_method("deselectSelectedChild", dbus_interface=ATSPI_SELECTION)
  74                 return func(index)
  75
  76         def getSelectedChild(self, index):
  77                 """
  78                 Get the i-th selected Accessible child of a Selection.
  79                 @param : selectedChildIndex
  80                 a long integer indicating which of the selected children of an
  81                 object is being requested.
  82                 @return a pointer to a selected Accessible child object, specified
  83                 by selectedChildIndex.
  84                 """
  85                 func = self.get_dbus_method("getSelectedChild", dbus_interface=ATSPI_SELECTION)
  86                 return self._cache.create_accessible(self._app_name,
  87                                                      func(index),
  88                                                      interfaces.ATSPI_ACCESSIBLE)
  89
  90         def isChildSelected(self, index):
  91                 """
  92                 Determine whether a particular child of an Selection implementor
  93                 is currently selected. Note that childIndex is the zero-offset
  94                 index into the standard Accessible container's list of children.
  95                 @param : childIndex
  96                 an index into the Selection's list of children.
  97                 @return True if the specified child is currently selected, False
  98                 otherwise.
  99                 """
 100                 func = self.get_dbus_method("isChildSelected", dbus_interface=ATSPI_SELECTION)
 101                 return func(index)
 102
 103         def selectAll(self):
 104                 """
 105                 Attempt to select all of the children of a Selection implementor.
 106                 Not all Selection implementors support this operation (for instance,
 107                 implementations which support only "single selection" do not
 108                 support this operation).
 109                 @return True if successful, False otherwise.
 110                 """
 111                 func = self.get_dbus_method("selectAll", dbus_interface=ATSPI_SELECTION)
 112                 return func()
 113
 114         def selectChild(self, index):
 115                 """
 116                 Add a child to the selected children list of a Selection.
 117                 @param : childIndex
 118                 a long integer indicating which child of the Selection is to
 119                 be selected.
 120                 @return True if the child was successfully selected, False otherwise.
 121                 """
 122                 func = self.get_dbus_method("selectChild", dbus_interface=ATSPI_SELECTION)
 123                 return func(index)
 124
 125         def get_nSelectedChildren(self):
 126                 return dbus.Int32(self._pgetter(self._dbus_interface, "nSelectedChildren"))
 127         _nSelectedChildrenDoc = \
 128                 """
 129                 The number of children of a Selection implementor which are currently
 130                 selected.
 131                 """
 132         nSelectedChildren = property(fget=get_nSelectedChildren, doc=_nSelectedChildrenDoc)
 133
 134 # Register the accessible class with the factory.
 135 accessible_factory.register_accessible_class(ATSPI_SELECTION, Selection)
 136
 137 #END----------------------------------------------------------------------------