Merge branch 'mdoff' of ssh://git.codethink.co.uk/git/atspi-dbus
[platform/core/uifw/at-spi2-atk.git] / pyatspi / editabletext.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 from text import *
19
20 __all__ = [
21            "EditableText",
22           ]
23
24 #------------------------------------------------------------------------------
25
26 class EditableText(Text):
27     """
28     Derived from interface Text, EditableText provides methods for
29     modifying textual content of components which support editing.
30     EditableText also interacts with the system clipboard via copyText,
31     cutText, and pasteText.
32     """
33     
34     def copyText(self, *args, **kwargs):
35         """
36         Copy a range of text into the system clipboard. 
37         @param : startPos
38         the character offset of the first character in the range of text
39         being copied. 
40         @param : endPos
41         the offset of the first character past the end of the range of
42         text being copied.
43         """
44         func = self.get_dbus_method("copyText")
45         return func(*args, **kwargs)
46     
47     def cutText(self, *args, **kwargs):
48         """
49         Excise a range of text from a Text object, copying it into the
50         system clipboard. 
51         @param : startPos
52         the character offset of the first character in the range of text
53         being cut. 
54         @param : endPos
55         the offset of the first character past the end of the range of
56         text being cut. 
57         @return True if the text was successfully cut, False otherwise.
58         """
59         func = self.get_dbus_method("cutText")
60         return func(*args, **kwargs)
61     
62     def deleteText(self, *args, **kwargs):
63         """
64         Excise a range of text from a Text object without copying it
65         into the system clipboard. 
66         @param : startPos
67         the character offset of the first character in the range of text
68         being deleted. 
69         @param : endPos
70         the offset of the first character past the end of the range of
71         text being deleted. 
72         @return True if the text was successfully deleted, False otherwise.
73         """
74         func = self.get_dbus_method("deleteText")
75         return func(*args, **kwargs)
76     
77     def insertText(self, *args, **kwargs):
78         """
79         Insert new text contents into an existing text object at a given
80         location, while retaining the old contents. 
81         @param : position
82         the character offset into the Text implementor's content at which
83         the new content will be inserted. 
84         @param : text
85         a UTF-8 string of which length characters will be inserted into
86         the text object's text buffer. 
87         @param : length
88         the number of characters of text to insert. If the character
89         count of text is less than or equal to length, the entire contents
90         of text will be inserted.
91         @return True if the text content was successfully inserted, False
92         otherwise.
93         """
94         func = self.get_dbus_method("insertText")
95         return func(*args, **kwargs)
96     
97     def pasteText(self, *args, **kwargs):
98         """
99         Copy the text contents of the system clipboard, if any, into
100         a Text object, inserting it at a particular character offset.
101         @param : position
102         the character offset before which the text will be inserted.
103         @return True if the text was successfully pasted into the Text
104         object, False otherwise.
105         """
106         func = self.get_dbus_method("pasteText")
107         return func(*args, **kwargs)
108     
109     def setAttributes(self, *args, **kwargs):
110         """
111         Apply a particular set of attributes to a range of text.
112         @return True if the text attributes were successfully modified,
113         False otherwise.
114         """
115         func = self.get_dbus_method("setAttributes")
116         return func(*args, **kwargs)
117     
118     def setTextContents(self, *args, **kwargs):
119         """
120         Replace the text contents with a new string, discarding the old
121         contents.
122         @param : newContents
123         a UTF-8 string with which the text object's contents will be
124         replaced. 
125         @return True if the text content was successfully changed, False
126         otherwise.
127         """
128         func = self.get_dbus_method("setTextContents")
129         return func(*args, **kwargs)
130     
131 # ATTENTION - Register the Application class with the accessible factory.
132 add_accessible_class(interfaces.ATSPI_EDITABLE_TEXT, EditableText)
133
134 #END----------------------------------------------------------------------------