Subversion Repositories Scribus

Rev

Rev 24679 | 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>
18507 gpittman 6
<style>
7
@import "manual.css";
8
</style>
10646 cbradney 9
<body>
597 cbradney 10
<h2>Handling Text Frames</h2>
559 cbradney 11
 
12
<dl>
1041 cbradney 13
 
11224 subik 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
 
1041 cbradney 19
<dt><a name="-deleteText"><strong>deleteText</strong></a>(...)</dt>
7440 subik 20
<dd><code>deleteText(["name"])</code>
1041 cbradney 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>
1607 subik 22
 
1041 cbradney 23
<dt><a name="-getAllText"><strong>getAllText</strong></a>(...)</dt>
7440 subik 24
<dd><code>getAllText(["name"]) -&gt; string</code>
1041 cbradney 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>
1607 subik 26
 
1041 cbradney 27
<dt><a name="-getColumnGap"><strong>getColumnGap</strong></a>(...)</dt>
7440 subik 28
<dd><code>getColumnGap(["name"]) -&gt; float</code>
1041 cbradney 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>
1607 subik 30
 
1041 cbradney 31
<dt><a name="-getColumns"><strong>getColumns</strong></a>(...)</dt>
7440 subik 32
<dd><code>getColumns(["name"]) -&gt; integer</code>
1607 subik 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>
36
<dd><code>getFirstLineOffset(["name"]) -&gt; integer</code>
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
 
1041 cbradney 43
<dt><a name="-getFont"><strong>getFont</strong></a>(...)</dt>
7440 subik 44
<dd><code>getFont(["name"]) -&gt; string</code>
1607 subik 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
 
1041 cbradney 47
<dt><a name="-getFontSize"><strong>getFontSize</strong></a>(...)</dt>
7440 subik 48
<dd><code>getFontSize(["name"]) -&gt; float</code>
1041 cbradney 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>
1607 subik 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
 
1041 cbradney 61
<dt><a name="-getLineSpacing"><strong>getLineSpacing</strong></a>(...)</dt>
7440 subik 62
<dd><code>getLineSpacing(["name"]) -&gt; float</code>
1041 cbradney 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>
1607 subik 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
 
1041 cbradney 73
<dt><a name="-getText"><strong>getText</strong></a>(...)</dt>
7440 subik 74
<dd><code>getText(["name"]) -&gt; string</code>
23647 jghali 75
<p>Deprecated. Use getFrameText() instead.</p></dd>
1041 cbradney 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>
1041 cbradney 81
 
13059 subik 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
 
1041 cbradney 88
<dt><a name="-getTextLength"><strong>getTextLength</strong></a>(...)</dt>
7440 subik 89
<dd><code>getTextLength(["name"]) -&gt; integer</code>
1041 cbradney 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
 
7440 subik 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>
7440 subik 96
 
1041 cbradney 97
<dt><a name="-getTextShade"><strong>getTextShade</strong></a>(...)</dt>
22731 jghali 98
<dd><code>getTextShade(["name"]) -&gt; integer</code>
22785 jghali 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>
1607 subik 101
 
22731 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
 
11224 subik 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>
110
 
17795 jghali 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>
17795 jghali 114
<p>May raise WrongFrameTypeError if the target frame is not a text frame</p></dd>
115
 
1041 cbradney 116
<dt><a name="-insertText"><strong>insertText</strong></a>(...)</dt>
7440 subik 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>
1041 cbradney 120
<p>May throw IndexError for an insertion out of bounds.</p></dd>
1607 subik 121
 
7440 subik 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>
25098 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
 
1041 cbradney 147
<dt><a name="-selectText"><strong>selectText</strong></a>(...)</dt>
7440 subik 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>
22293 gpittman 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>
22442 gpittman 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>
22293 gpittman 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>
1607 subik 157
 
1041 cbradney 158
<dt><a name="-setColumns"><strong>setColumns</strong></a>(...)</dt>
7440 subik 159
<dd><code>setColumns(nr, ["name"])</code>
1041 cbradney 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>
1607 subik 162
 
1041 cbradney 163
<dt><a name="-setColumnGap"><strong>setColumnGap</strong></a>(...)</dt>
7440 subik 164
<dd><code>setColumnGap(size, ["name"])</code>
1041 cbradney 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>
1607 subik 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
 
1041 cbradney 175
<dt><a name="-setFont"><strong>setFont</strong></a>(...)</dt>
7440 subik 176
<dd><code>setFont("font", ["name"])</code>
1041 cbradney 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>
7440 subik 181
<dd><code>setFontSize(size, ["name"])</code>
1041 cbradney 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>
1607 subik 184
 
1041 cbradney 185
<dt><a name="-setLineSpacing"><strong>setLineSpacing</strong></a>(...)</dt>
7440 subik 186
<dd><code>setLineSpacing(size, ["name"])</code>
1041 cbradney 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>
1607 subik 189
 
14427 jghali 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>
194
 
7440 subik 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>
7440 subik 198
<p>May raise WrongFrameTypeError if the target frame is not a text frame</p></dd>
199
 
1041 cbradney 200
<dt><a name="-setText"><strong>setText</strong></a>(...)</dt>
7440 subik 201
<dd><code>setText("text", ["name"])</code>
1041 cbradney 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>
7440 subik 205
<dd><code>setTextAlignment(align, ["name"])</code>
1607 subik 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>
1041 cbradney 207
<p>May throw ValueError for an invalid alignment constant.</p></dd>
208
 
13059 subik 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
 
13199 jghali 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
 
224
<dt><a name="-setTextColor"><strong>setTextColor</strong></a>(...)</dt>
225
<dd><code>setTextColor("color", ["name"])</code>
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
 
1041 cbradney 228
<dt><a name="-setTextShade"><strong>setTextShade</strong></a>(...)</dt>
7440 subik 229
<dd><code>setTextShade(shade, ["name"])</code>
1041 cbradney 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>
7440 subik 233
<dd><code>setTextStroke("color", ["name"])</code>
1041 cbradney 234
<p>Set "color" of the text stroke. If "name" is not given the currently selected item is used.</p></dd>
235
 
22731 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
 
1420 subik 243
<dt><a name="-textOverflows"><strong>textOverflows</strong></a>(...)</dt>
7440 subik 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>
1420 subik 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
 
597 cbradney 253
</dl>
10646 cbradney 254
</body>
255
</html>