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