7b56b4aa3a3dc1451147cbf9fba0ec623ad5db31
[platform/core/uifw/at-spi2-atk.git] / 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----------------------------------------------------------------------------