1
2
3 """
4 The Blender.Text submodule.
5
6 Text Objects
7 ============
8
9 This module provides access to B{Text} objects in Blender.
10
11 Example::
12 import Blender
13 from Blender import Text
14 #
15 txt = Text.New("MyText") # create a new Text object
16 print Text.Get() # current list of Texts in Blender
17 txt.write("Appending some ") # appending text
18 txt.write("text to my\\n") # '\\n' inserts new-line markers
19 txt.write("text buffer.")
20 print txt.asLines() # retrieving the buffer as a list of lines
21 Text.unlink(txt) # removing a Text object
22 """
23
24 -def New (name = None, follow_cursor = 0):
25 """
26 Create a new Text object.
27 @type name: string
28 @param name: The Text name.
29 @type follow_cursor: int
30 @param follow_cursor: The text follow flag: if 1, the text display always
31 follows the cursor.
32 @rtype: Blender Text
33 @return: The created Text Data object.
34 """
35
36 -def Get (name = None):
37 """
38 Get the Text object(s) from Blender.
39 @type name: string
40 @param name: The name of the Text object.
41 @rtype: Blender Text or a list of Blender Texts
42 @return: It depends on the 'name' parameter:
43 - (name): The Text object with the given name;
44 - (): A list with all Text objects in the current scene.
45 """
46
48 """
49 Load a file into a Blender Text object.
50 @type filename: string
51 @param filename: The name of the file to load.
52 @rtype: Blender Text
53 @return: A Text object with the contents of the loaded file.
54 """
55
57 """
58 Unlink (remove) the given Text object from Blender.
59 @type textobj: Blender Text
60 @param textobj: The Text object to be deleted.
61 """
62
64 """
65 The Text object
66 ===============
67 This object gives access to Texts in Blender.
68 @ivar filename: The filename of the file loaded into this Text.
69 @ivar mode: The follow_mode flag: if 1 it is 'on'; if 0, 'off'.
70 @ivar nlines: The number of lines in this Text.
71 """
72
74 """
75 Get the name of this Text object.
76 @rtype: string
77 """
78
80 """
81 Set the name of this Text object.
82 @type name: string
83 @param name: The new name.
84 """
85
87 """
88 Get the filename of the file loaded into this Text object.
89 @rtype: string
90 """
91
93 """
94 Get the number of lines in this Text buffer.
95 @rtype: int
96 """
97
99 """
100 Clear this Text object: its buffer becomes empty.
101 """
102
104 """
105 Reset the read IO pointer to the start of the buffer.
106 """
107
109 """
110 Reads a line of text from the buffer from the current IO pointer
111 position to the end of the line. If the text has changed since the last
112 read, reset() *must* be called.
113 @rtype: string
114 """
115
116 - def set(attribute, value):
117 """
118 Set this Text's attributes.
119 @type attribute: string
120 @param attribute: The attribute to change:
121 currently, 'follow_cursor' is the only one available. It can be
122 turned 'on' with value = 1 and 'off' with value = 0.
123 @type value: int
124 @param value: The new attribute value.
125 """
126
128 """
129 Append a string to this Text buffer.
130 @type data: string
131 @param data: The string to append to the text buffer.
132 """
133
135 """
136 Inserts a string into this Text buffer at the cursor.
137 @type data: string
138 @param data: The string to insert into the text buffer.
139 """
140
141 - def asLines(start=0, end=-1):
142 """
143 Retrieve the contents of this Text buffer as a list of strings between
144 the start and end lines specified. If end < 0 all lines from start will
145 be included.
146 @type start: int
147 @param start: Optional index of first line of the span to return
148 @type end int
149 @param end: Optional index of the line to which the span is taken or
150 -1 to include all lines from start
151 @rtype: list of strings
152 @return: A list of strings, one for each line in the buffer between
153 start and end.
154 """
155
157 """
158 Retrieve the position of the cursor in this Text buffer.
159 @rtype: (int, int)
160 @return: A pair (row, col) indexing the line and character of the
161 cursor.
162 """
163
164 - def setCursorPos(row, col):
165 """
166 Set the position of the cursor in this Text buffer. Any selection will
167 be cleared. Use setSelectPos to extend a selection from the point
168 specified here.
169 @type row: int
170 @param row: The index of the line in which to position the cursor.
171 @type col: int
172 @param col: The index of the character within the line to position the
173 cursor.
174 """
175
177 """
178 Retrieve the position of the selection cursor in this Text buffer.
179 @rtype: (int, int)
180 @return: A pair (row, col) indexing the line and character of the
181 selection cursor.
182 """
183
184 - def setSelectPos(row, col):
185 """
186 Set the position of the selection cursor in this Text buffer. This
187 method should be called after setCursorPos to extend the selection to
188 the specified point.
189 @type row: int
190 @param row: The index of the line in which to position the cursor.
191 @type col: int
192 @param col: The index of the character within the line to position the
193 cursor.
194 """
195
196 - def suggest(list, prefix=''):
197 """
198 Suggest a list of names. If list is a list of tuples (name, type) the
199 list will be formatted to syntax-highlight each entry type. Types must
200 be strings in the list ['m', 'f', 'v', 'k', '?']. It is recommended that
201 the list be sorted, case-insensitively by name.
202
203 @type list: list of tuples or strings
204 @param list: List of pair-tuples of the form (name, type) where name is
205 the suggested name and type is one of 'm' (module or class), 'f'
206 (function or method), 'v' (variable), 'k' (keyword), '?' (other).
207 Lists of plain strings are also accepted where the type is always
208 '?'.
209 @type prefix: string
210 @param prefix: The optional prefix used to limit what is suggested from
211 the list. This is usually whatever precedes the cursor so that
212 backspace will update it.
213 """
214
215 - def showDocs(docs):
216 """
217 Displays a word-wrapped message box containing the specified
218 documentation when this Text object is visible.
219 @type docs: string
220 @param docs: The documentation string to display.
221 """
222
223 import id_generics
224 Text.__doc__ += id_generics.attributes
225