Subversion Repositories Scribus

Rev

Rev 24826 | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
10646 cbradney 1
<html>
2
<head>
3
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
4
        <title>Handling Text Frames</title>
5
</head>
20587 gpittman 6
<style>
7
@import "manual.css";
8
</style>
10646 cbradney 9
<body>
5297 mrdocs 10
<h2>Handling Text Frames</h2>
11
 
12
<dl>
13
 
20587 gpittman 14
<dt><a name="-dehyphenateText"><strong>dehyphenateText</strong></a>(...)</dt>
15
<dd><code>dehyphenateText(["name"]) -&gt; bool</code>
16
<p>Does dehyphenation on text frame "name". If "name" is not given the currently selected item is used.</p>
17
<p>May raise WrongFrameTypeError if the target frame is not a text frame</p></dd>
18
 
5297 mrdocs 19
<dt><a name="-deleteText"><strong>deleteText</strong></a>(...)</dt>
20587 gpittman 20
<dd><code>deleteText(["name"])</code>
5297 mrdocs 21
<p>Deletes any text in the text frame "name". If there is some text selected, only the selected text will be deleted. If "name" is not given the currently selected item is used.</p></dd>
20587 gpittman 22
 
5297 mrdocs 23
<dt><a name="-getAllText"><strong>getAllText</strong></a>(...)</dt>
20587 gpittman 24
<dd><code>getAllText(["name"]) -&gt; string</code>
5297 mrdocs 25
<p>Returns the text of the text frame "name" and of all text frames which are linked with this frame. If this textframe has some text selected, the selected text is returned. If "name" is not given the currently selected item is used.</p></dd></dt>
20587 gpittman 26
 
5297 mrdocs 27
<dt><a name="-getColumnGap"><strong>getColumnGap</strong></a>(...)</dt>
20587 gpittman 28
<dd><code>getColumnGap(["name"]) -&gt; float</code>
5297 mrdocs 29
<p>Returns the column gap size of the text frame "name" expressed in points. If "name" is not given the currently selected item is used.</p></dd>
20587 gpittman 30
 
5297 mrdocs 31
<dt><a name="-getColumns"><strong>getColumns</strong></a>(...)</dt>
20587 gpittman 32
<dd><code>getColumns(["name"]) -&gt; integer</code>
33
<p>Gets the number of columns of the text frame "name". If "name" is not given the currently selected item is used.</p></dd>
34
 
24070 jghali 35
<dt><a name="-getFirstLineOffset"><strong>getFirstLineOffset</strong></a>(...)</dt>
25097 jghali 36
<dd><code>getFirstLineOffset(["name"]) -&gt; integer</code>
24070 jghali 37
<p>Gets the offset of the first line of text inside text frame "name". If "name" is not given the currently selected item is used.</p></dd>
38
 
24021 jghali 39
<dt><a name="-getFirstLinkedFrame"><strong>getFirstLinkedFrame</strong></a>(...)</dt>
40
<dd><code>getFirstLinkedFrame(["name"]) -&gt; string</code>
41
<p>Return the first text frame in the chain. If "name" is not given the currently selected item is used.</p></dd>
42
 
5297 mrdocs 43
<dt><a name="-getFont"><strong>getFont</strong></a>(...)</dt>
20587 gpittman 44
<dd><code>getFont(["name"]) -&gt; string</code>
45
<p>Returns the font name for the text frame "name". If this text frame has some text selected the value assigned to the first character of the selection is returned. If "name" is not given the currently selected item is used.</p></dd>
46
 
5297 mrdocs 47
<dt><a name="-getFontSize"><strong>getFontSize</strong></a>(...)</dt>
20587 gpittman 48
<dd><code>getFontSize(["name"]) -&gt; float</code>
5297 mrdocs 49
<p>Returns the font size in points for the text frame "name". If this text frame has some text selected the value assigned to the first character of the selection is returned. If "name" is not given the currently selected item is used.</p></dd>
20587 gpittman 50
 
23647 jghali 51
<dt><a name="-getFrameText"><strong>getFrameText</strong></a>(...)</dt>
52
<dd><code>getFrameText(["name"]) -&gt; string</code>
53
<p>Returns the text visible in text frame "name". If this text frame has some text selected, the selected text is returned. If "name" is not given the currently selected item is used.</p>
54
<p>This function returns only the text visible in specified frame. If you need to retrieve the text contained in a text chain, use <a href="#-getAllText">getAllText()</a> instead.</p>
55
<p>As this function depends on text layout being up-to-date, you may need to call <a href="#-layoutText">layoutText()</a> or <a href="#-layoutTextChain">layoutTextChain()</a> before calling this function in order to get expected result.</p></dd>
56
 
24021 jghali 57
<dt><a name="-getLastLinkedFrame"><strong>getLastLinkedFrame</strong></a>(...)</dt>
58
<dd><code>getLastLinkedFrame(["name"]) -&gt; string</code>
59
<p>Return the last text frame in the chain. If "name" is not given the currently selected item is used.</p></dd>
60
 
5297 mrdocs 61
<dt><a name="-getLineSpacing"><strong>getLineSpacing</strong></a>(...)</dt>
20587 gpittman 62
<dd><code>getLineSpacing(["name"]) -&gt; float</code>
5297 mrdocs 63
<p>Returns the line spacing ("leading") of the text frame "name" expressed in points. If "name" is not given the currently selected item is used.</p></dd>
20587 gpittman 64
 
24021 jghali 65
<dt><a name="-getNextLinkedFrame"><strong>getNextLinkedFrame</strong></a>(...)</dt>
66
<dd><code>getNextLinkedFrame(["name"]) -&gt; string</code>
67
<p>Return the next text frame in the chain or None if specified frame is the last frame in the chain. If "name" is not given the currently selected item is used.</p></dd>
68
 
69
<dt><a name="-getPrevLinkedFrame"><strong>getPrevLinkedFrame</strong></a>(...)</dt>
70
<dd><code>getPrevLinkedFrame(["name"]) -&gt; string</code>
71
<p>Return the previous text frame in the chain or None if specified frame is the first frame in the chain. If "name" is not given the currently selected item is used.</p></dd>
72
 
5297 mrdocs 73
<dt><a name="-getText"><strong>getText</strong></a>(...)</dt>
20587 gpittman 74
<dd><code>getText(["name"]) -&gt; string</code>
23647 jghali 75
<p>Deprecated. Use getFrameText() instead.</p></dd>
5297 mrdocs 76
 
77
<dt><a name="-getTextColor"><strong>getTextColor</strong></a>(...)</dt>
22785 jghali 78
<dd><code>getTextColor(["name"]) -&gt; string</code>
79
<p>Returns the name of the text color used for text frame "name". If this text frame has some text selected the value assigned to the first character of the selection is returned. If "name" is not given the currently selected item is used.</p>
80
<p>May raise WrongFrameTypeError if the target frame is not a text frame</p></dd>
5297 mrdocs 81
 
20587 gpittman 82
<dt><a name="-getTextDistances"><strong>getTextDistances</strong></a>(...)</dt>
83
<dd><code>getTextDistances(["name"]) -&gt; tuple</code>
84
<p>Returns the text distances of the text frame "name" expressed in points. The
85
distances are returned as a tuple like (left, right, top, bottom). If "name"
86
is not given the currently selected item is used.</p></dd>
87
 
5297 mrdocs 88
<dt><a name="-getTextLength"><strong>getTextLength</strong></a>(...)</dt>
20587 gpittman 89
<dd><code>getTextLength(["name"]) -&gt; integer</code>
5297 mrdocs 90
<p>Returns the length of the text in the text frame "name". If "name" is not given the currently selected item is used.</p></dd>
91
 
20587 gpittman 92
<dt><a name="-getTextLines"><strong>getTextLines</strong>(...)</a></dt>
93
<dd><code>getTextLines(["name"]) -&gt; integer</code>
23623 jghali 94
<p>Returns the number of lines of text in text frame "name". If "name" is not given the currently selected item is used.</p>
95
<p>As this function depends on text layout being up-to-date, you may need to call <a href="#-layoutText">layoutText()</a> or <a href="#-layoutTextChain">layoutTextChain()</a> before calling this function in order to get expected result.</p></dd>
20587 gpittman 96
 
5297 mrdocs 97
<dt><a name="-getTextShade"><strong>getTextShade</strong></a>(...)</dt>
22785 jghali 98
<dd><code>getTextShade(["name"]) -&gt; integer</code>
99
<p>Returns the shade of text color used for text frame "name". If this text frame has some text selected the value assigned to the first character of the selection is returned. If "name" is not given the currently selected item is used.</p>
100
<p>May raise WrongFrameTypeError if the target frame is not a text frame</p></dd>
5297 mrdocs 101
 
22785 jghali 102
<dt><a name="-getTextVerticalAlignment"><strong>getTextVerticalAlignment</strong></a>(...)</dt>
103
<dd><code>getTextVerticalAlignment(["name"]) -&gt; integer</code>
104
<p>Gets the vertical alignment of text inside text frame "name". If "name" is not given the currently selected item is used.</p></dd>
105
 
20587 gpittman 106
<dt><a name="-hyphenateText"><strong>hyphenateText</strong></a>(...)</dt>
107
<dd><code>hyphenateText(["name"]) -&gt; bool</code>
108
<p>Does hyphenation on text frame "name". If "name" is not given the currently selected item is used.</p>
109
<p>May raise WrongFrameTypeError if the target frame is not a text frame</p></dd>
5297 mrdocs 110
 
20587 gpittman 111
<dt><a name="-insertHtmlText"><strong>insertHtmlText</strong></a>(...)</dt>
112
<dd><code>insertHtmlText("text", ["name"])</code>
23623 jghali 113
<p>Inserts the text from "file" into the text frame "name". Text must be UTF encoded (see <a href="#-setText">setText</a>() as reference). If "name" is not given the currently selected item is used.</p>
20587 gpittman 114
<p>May raise WrongFrameTypeError if the target frame is not a text frame</p></dd>
115
 
5297 mrdocs 116
<dt><a name="-insertText"><strong>insertText</strong></a>(...)</dt>
20587 gpittman 117
<dd><code>insertText("text", pos, ["name"])</code>
23623 jghali 118
<p>Inserts the text "text" at the position "pos" into the text frame "name". Text must be UTF encoded (see <a href="#-setText">setText</a>() as reference) The first character has an index of 0. Inserting text at position -1 appends it to the frame. If "name" is not given the currently selected item is used.</p>
23647 jghali 119
<p>For performance reason, this function does not update text layout in any way. As a consequence, you may need to call <a href="#-layoutText">layoutText()</a>  or <a href="#-layoutTextChain">layoutTextChain()</a> at appropriate times after calling this function and before calling functions such as <a href="#-getFrameText">getFrameText()</a> or <a href="#-getTextLines">getTextLines()</a>.</p>
5297 mrdocs 120
<p>May throw IndexError for an insertion out of bounds.</p></dd>
20587 gpittman 121
 
122
<dt><a name="-isPDFBookmark"><strong>isPDFBookmark</strong>(...)</a></dt>
123
<dd><code>isPDFBookmark(["name"]) -&gt; bool</code>
124
<p>Returns true if the text frame "name" is a PDF bookmark. If "name" is not given the currently selected item is used.</p>
125
<p>May raise WrongFrameTypeError if the target frame is not a text frame</p></dd>
126
 
23332 jghali 127
<dt><a name="-layoutText"><strong>layoutText</strong></a>(...)</dt>
128
<dd><code>layoutText(["name"])</code>
129
<p>Relayout text in the text frame "name". If "name" is not given the currently selected item is used.</p></dd>
130
 
23339 jghali 131
<dt><a name="-layoutTextChain"><strong>layoutTextChain</strong></a>(...)</dt>
132
<dd><code>layoutTextChain(["name"])</code>
133
<p>Relayout the whole text chain whom the text frame "name" belongs. If "name" is not given the currently selected item is used.</p></dd>
134
 
23371 jghali 135
<dt><a name="-linkTextFrames"><strong>linkTextFrames</strong></a>(...)</dt>
136
<dd><code>linkTextFrames("fromname", "toname")</code>
25097 jghali 137
<p>Link two text frames. The frame named "fromname" is linked to the frame named "toname". The source frame must not already link to another frame. The target frame must not be linked from another frame.</p>
23371 jghali 138
<p>May throw <a href="#ScribusException">ScribusException</a> if linking rules are violated.</p></dd>
139
 
23921 jghali 140
<dt><a name="-selectFrameText"><strong>selectFrameText</strong></a>(...)</dt>
141
<dd><code>selectFrameText(start, count, ["name"])</code>
142
<p>Selects "count" characters of text in the text frame "name" starting from the character "start". Character counting starts at 0. If "count" is zero, any text selection will be cleared. If "count" is -1, the selection will extend to the end of the frame. If "name" is not given the currently selected item is used.</p>
143
<p>This function only acts on the text visible in the specified frame. If you need to work on the text contained in a text chain, use selectText() instead.</p>
144
<p>As this function depends on text layout being up-to-date, you may need to call <a href="#-layoutText">layoutText()</a> or <a href="#-layoutTextChain">layoutTextChain()</a> before calling this function in order to get expected result.</p>
145
<p>May throw IndexError if the selection is outside the bounds of the text.</p></dd>
146
 
5297 mrdocs 147
<dt><a name="-selectText"><strong>selectText</strong></a>(...)</dt>
20587 gpittman 148
<dd><code>selectText(start, count, ["name"])</code>
23921 jghali 149
<p>Selects "count" characters of text in the text frame "name" starting from the character "start". Character counting starts at 0. If "count" is zero, any text selection will be cleared. If "name" is not given the currently selected item is used.</p>
22785 jghali 150
<p>May throw IndexError if the selection is outside the bounds of the text.</p>
151
<p>There is no specific command to select all of the text in a frame. To accomplish this, you might create a function in your script which you would call with the name of the frame as follows:</p>
152
<p><b>def SelectAllText(textframe):</b></p>
153
    <p><b>&nbsp;&nbsp;&nbsp;&nbsp;texlen = scribus.getTextLength(textframe)</b></p>
154
    <p><b>&nbsp;&nbsp;&nbsp;&nbsp;scribus.selectText(0,texlen,textframe)</b></p>
155
    <p><b>&nbsp;&nbsp;&nbsp;&nbsp;return</b></p></dd>
156
<dd><p>One of the reasons this is important is that, should you want to select a frame and then apply a Paragraph Style to the frame, you will find that a frame with multiple paragraphs will not have the style set for all of the text, only the last paragraph. Therefore, the solution is to select all the text of the frame, and then apply the style.</p></dd>
20587 gpittman 157
 
5297 mrdocs 158
<dt><a name="-setColumns"><strong>setColumns</strong></a>(...)</dt>
20587 gpittman 159
<dd><code>setColumns(nr, ["name"])</code>
5297 mrdocs 160
<p>Sets the number of columns of the text frame "name" to the integer "nr". If "name" is not given the currently selected item is used.</p>
161
<p>May throw ValueError if number of columns is not at least one.</p></dd>
20587 gpittman 162
 
5297 mrdocs 163
<dt><a name="-setColumnGap"><strong>setColumnGap</strong></a>(...)</dt>
20587 gpittman 164
<dd><code>setColumnGap(size, ["name"])</code>
5297 mrdocs 165
<p>Sets the column gap of the text frame "name" to the value "size". If "name" is not given the currently selected item is used.</p>
20587 gpittman 166
<p>May throw ValueError if the column gap is out of bounds (must be positive).</p></dd>
167
 
24070 jghali 168
<dt><a name="-setFirstLineOffset"><strong>setFirstLineOffset</strong></a>(...)</dt>
169
<dd>
170
<code>setFirstLineOffset(offset, ["name"])</code>
171
<p>Sets the offset of the first line of text inside text frame "name" to the specified offset policy. If "name" is not given the currently selected item is used. "offset" should be one of the FLOP_* constants defined in this module - see dir(scribus).</p>
172
<p>May throw ValueError for an invalid offset constant.</p>
173
</dd>
174
 
5297 mrdocs 175
<dt><a name="-setFont"><strong>setFont</strong></a>(...)</dt>
20587 gpittman 176
<dd><code>setFont("font", ["name"])</code>
5297 mrdocs 177
<p>Sets the font of the text frame "name" to "font". If there is some text selected only the selected text is changed.  If "name" is not given the currently selected item is used.</p>
178
<p>May throw ValueError if the font cannot be found.</p></dd>
179
 
180
<dt><a name="-setFontSize"><strong>setFontSize</strong></a>(...)</dt>
20587 gpittman 181
<dd><code>setFontSize(size, ["name"])</code>
5297 mrdocs 182
<p>Sets the font size of the text frame "name" to "size". "size" is treated as a value in points. If there is some text selected only the selected text is changed. "size" must be in the range 1 to 512. If "name" is not given the currently selected item is used.</p>
183
<p>May throw ValueError for a font size that's out of bounds.</p></dd>
20587 gpittman 184
 
5297 mrdocs 185
<dt><a name="-setLineSpacing"><strong>setLineSpacing</strong></a>(...)</dt>
20587 gpittman 186
<dd><code>setLineSpacing(size, ["name"])</code>
5297 mrdocs 187
<p>Sets the line spacing ("leading") of the text frame "name" to "size". "size" is a value in points. If "name" is not given the currently selected item is used.</p>
188
<p>May throw ValueError if the line spacing is out of bounds.</p></dd>
189
 
20587 gpittman 190
<dt><a name="-setLineSpacingMode"><strong>setLineSpacingMode</strong></a>(...)</dt>
191
<dd><code>setLineSpacingMode(mode, ["name"])</code>
192
<p>Sets the line spacing mode of the text frame "name" to "mode". If "name" is not given the currently selected item is used. Mode values are the same as in createParagraphStyle.</p>
193
<p>May throw ValueError if the line spacing mode is out of bounds.</p></dd>
5297 mrdocs 194
 
20587 gpittman 195
<dt><a name="-setPDFBookmark"><strong>setPDFBookmark</strong>(...)</a></dt>
196
<dd><code>setPDFBookmark("toggle", ["name"])</code>
24679 jghali 197
<p>Sets whether (toggle = 1) the text frame "name" is a bookmark or not. If "name" is not given the currently selected item is used.</p>
20587 gpittman 198
<p>May raise WrongFrameTypeError if the target frame is not a text frame</p></dd>
199
 
5297 mrdocs 200
<dt><a name="-setText"><strong>setText</strong></a>(...)</dt>
20587 gpittman 201
<dd><code>setText("text", ["name"])</code>
5297 mrdocs 202
<p>Sets the text of the text frame "name" to the text of the string "text". Text must be UTF8 encoded - use e.g. unicode(text, 'iso-8859-2'). See the FAQ for more details. If "name" is not given the currently selected item is used.</p></dd>
203
 
204
<dt><a name="-setTextAlignment"><strong>setTextAlignment</strong></a>(...)</dt>
20587 gpittman 205
<dd><code>setTextAlignment(align, ["name"])</code>
206
<p>Sets the text alignment of the text frame "name" to the specified alignment. If "name" is not given the currently selected item is used. "align" should be one of the ALIGN_ constants defined in this module - see dir(scribus).</p>
5297 mrdocs 207
<p>May throw ValueError for an invalid alignment constant.</p></dd>
208
 
20587 gpittman 209
<dt><a name="-setTextDistances"><strong>setTextDistances</strong></a>(...)</dt>
210
<dd><code>setTextDistances(left, right, top, bottom, ["name"])</code>
211
<p>Sets the text distances of the text frame "name" to the values "left"
212
"right", "top" and "bottom". If "name" is not given the currently
213
selected item is used.</p>
214
<p>May throw ValueError if any of the distances are out of bounds (must be positive).</p></dd>
215
 
216
<dt><a name="-setTextScalingH"><strong>setTextScalingH</strong></a>(...)</dt>
217
<dd><code>setTextScalingH(scale, ["name"]))</code>
218
<p>Sets the horizontal character scaling of the object "name" to "scale" in percent. If "name" is not given the currently selected item is used.</p></dd>
219
 
220
<dt><a name="-setTextScalingV"><strong>setTextScalingV</strong></a>(...)</dt>
221
<dd><code>setTextScalingV(scale, ["name"]))</code>
222
<p>Sets the vertical character scaling of the object "name" to "scale" in percent. If "name" is not given the currently selected item is used.</p></dd>
223
 
5297 mrdocs 224
<dt><a name="-setTextColor"><strong>setTextColor</strong></a>(...)</dt>
20587 gpittman 225
<dd><code>setTextColor("color", ["name"])</code>
5297 mrdocs 226
<p>Sets the text color of the text frame "name" to the color "color". If there is some text selected only the selected text is changed. If "name" is not given the currently selected item is used.</p></dd>
227
 
228
<dt><a name="-setTextShade"><strong>setTextShade</strong></a>(...)</dt>
20587 gpittman 229
<dd><code>setTextShade(shade, ["name"])</code>
5297 mrdocs 230
<p>Sets the shading of the text color of the object "name" to "shade". If there is some text selected only the selected text is changed. "shade" must be an integer value in the range from 0 (lightest) to 100 (full color intensity). If "name" is not given the currently selected item is used.</p></dd>
231
 
232
<dt><a name="-setTextStroke"><strong>setTextStroke</strong></a>(...)</dt>
20587 gpittman 233
<dd><code>setTextStroke("color", ["name"])</code>
5297 mrdocs 234
<p>Set "color" of the text stroke. If "name" is not given the currently selected item is used.</p></dd>
235
 
22785 jghali 236
<dt><a name="-setTextVerticalAlignment"><strong>setTextVerticalAlignment</strong></a>(...)</dt>
237
<dd>
238
<code>setTextVerticalAlignment(align, ["name"])</code>
239
<p>Sets the vertical alignment of text inside text frame "name" to the specified alignment. If "name" is not given the currently selected item is used. "align" should be one of the ALIGNV_ constants defined in this module - see dir(scribus).</p>
240
<p>May throw ValueError for an invalid alignment constant.</p>
241
</dd>
242
 
20587 gpittman 243
<dt><a name="-textOverflows"><strong>textOverflows</strong></a>(...)</dt>
244
<dd><code>textOverflows(["name", nolinks]) -&gt; integer</code>
22944 jghali 245
<p>Returns 1 if there are overflowing characters in text frame "name", 0 if not. If nolinks is set to non zero value, it takes only one frame - it doesn't use text frame linking. Without this parameter it searches all linking chain.</p>
20587 gpittman 246
<p>May raise WrongFrameTypeError if the target frame is not an text frame</p></dd>
247
 
23371 jghali 248
<dt><a name="-unlinkTextFrames"><strong>unlinkTextFrames</strong></a>(...)</dt>
249
<dd><code>unlinkTextFrames("name")</code>
250
<p>Remove the specified (named) object from the text frame flow/linkage. If the frame was in the middle of a chain, the previous and next frames will be connected, eg 'a-&gt;b-&gt;c' becomes 'a-&gt;c' when you <a href="#-unlinkTextFrames">unlinkTextFrames</a>(b)'</p>
251
<p>May throw <a href="#ScribusException">ScribusException</a> if linking rules are violated.</p></dd>
252
 
5297 mrdocs 253
</dl>
10646 cbradney 254
</body>
255
</html>