Author: jghali
Date: Sun Apr 19 23:32:48 2020
New Revision: 23623
URL: http://scribus.net/websvn/listing.php?repname=Scribus&sc=1&rev=23623
Log:
#16090: improve documentation for scripter's insertText() and getTextLines()
Modified:
trunk/Scribus/doc/de/scripterapi-textframes.html
trunk/Scribus/doc/en/scripterapi-textframes.html
trunk/Scribus/doc/fr/scripterapi-textframes.html
trunk/Scribus/doc/it/scripterapi-textframes.html
trunk/Scribus/doc/ru/scripterapi-textframes.html
trunk/Scribus/scribus/plugins/scriptplugin/cmdtext.h
Modified: trunk/Scribus/doc/de/scripterapi-textframes.html
URL:
http://scribus.net/websvn/diff.php?repname=Scribus&rev=23623&path=/trunk/Scribus/doc/de/scripterapi-textframes.html
==============================================================================
--- trunk/Scribus/doc/de/scripterapi-textframes.html (original)
+++ trunk/Scribus/doc/de/scripterapi-textframes.html Sun Apr 19 23:32:48 2020
@@ -67,7 +67,8 @@
<dt><a name="-getTextLines"><strong>getTextLines</strong>(...)</a></dt>
<dd><code>getTextLines(["name"]) -> integer</code>
-<p>Returns the number of lines of the text in the text frame "name". If "name"
is not given the currently selected item is used.</p></dd>
+<p>Returns the number of lines of text in text frame "name". If "name" is not
given the currently selected item is used.</p>
+<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>
<dt><a name="-getTextShade"><strong>getTextShade</strong></a>(...)</dt>
<dd><code>getTextShade(["name"]) -> integer</code>
@@ -85,12 +86,13 @@
<dt><a name="-insertHtmlText"><strong>insertHtmlText</strong></a>(...)</dt>
<dd><code>insertHtmlText("text", ["name"])</code>
-<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>
+<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>
<p>May raise WrongFrameTypeError if the target frame is not a text
frame</p></dd>
<dt><a name="-insertText"><strong>insertText</strong></a>(...)</dt>
<dd><code>insertText("text", pos, ["name"])</code>
-<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>
+<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>
+<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="#-getText">getText()</a> or <a
href="#-getTextLines">getTextLines()</a>.</p>
<p>May throw IndexError for an insertion out of bounds.</p></dd>
<dt><a name="-isPDFBookmark"><strong>isPDFBookmark</strong>(...)</a></dt>
Modified: trunk/Scribus/doc/en/scripterapi-textframes.html
URL:
http://scribus.net/websvn/diff.php?repname=Scribus&rev=23623&path=/trunk/Scribus/doc/en/scripterapi-textframes.html
==============================================================================
--- trunk/Scribus/doc/en/scripterapi-textframes.html (original)
+++ trunk/Scribus/doc/en/scripterapi-textframes.html Sun Apr 19 23:32:48 2020
@@ -67,7 +67,8 @@
<dt><a name="-getTextLines"><strong>getTextLines</strong>(...)</a></dt>
<dd><code>getTextLines(["name"]) -> integer</code>
-<p>Returns the number of lines of the text in the text frame "name". If "name"
is not given the currently selected item is used.</p></dd>
+<p>Returns the number of lines of text in text frame "name". If "name" is not
given the currently selected item is used.</p>
+<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>
<dt><a name="-getTextShade"><strong>getTextShade</strong></a>(...)</dt>
<dd><code>getTextShade(["name"]) -> integer</code>
@@ -85,12 +86,13 @@
<dt><a name="-insertHtmlText"><strong>insertHtmlText</strong></a>(...)</dt>
<dd><code>insertHtmlText("text", ["name"])</code>
-<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>
+<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>
<p>May raise WrongFrameTypeError if the target frame is not a text
frame</p></dd>
<dt><a name="-insertText"><strong>insertText</strong></a>(...)</dt>
<dd><code>insertText("text", pos, ["name"])</code>
-<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>
+<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>
+<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="#-getText">getText()</a> or <a
href="#-getTextLines">getTextLines()</a>.</p>
<p>May throw IndexError for an insertion out of bounds.</p></dd>
<dt><a name="-isPDFBookmark"><strong>isPDFBookmark</strong>(...)</a></dt>
Modified: trunk/Scribus/doc/fr/scripterapi-textframes.html
URL:
http://scribus.net/websvn/diff.php?repname=Scribus&rev=23623&path=/trunk/Scribus/doc/fr/scripterapi-textframes.html
==============================================================================
--- trunk/Scribus/doc/fr/scripterapi-textframes.html (original)
+++ trunk/Scribus/doc/fr/scripterapi-textframes.html Sun Apr 19 23:32:48 2020
@@ -54,6 +54,11 @@
<dd><code>getTextLength(["nom"]) -> nombre entier</code>
<p>Retourne la longueur du texte dans le cadre de texte "nom". Si "nom" n'est
pas fourni, l'élément sélectionné est utilisé. </p></dd>
+<dt><a name="-getTextLines"><strong>getTextLines</strong>(...)</a></dt>
+<dd><code>getTextLines(["nom"]) -> integer</code>
+<p>Retourne le nombre de lignes de texte présenté dans le cadre de texte
"nom". Si "nom" n'est pas fourni, l'élément sélectionné est utilisé.</p>
+<p>Comme cette fonction nécessite que la mise en page du texte soit à jour,
il est possible que vous ayez besoin d'appeler <a
href="#-layoutText">layoutText()</a> ou <a
href="#-layoutTextChain">layoutTextChain()</a> au préalable afin d'obtenir le
résultat attendu.</p></dd>
+
<dt><a name="-getTextShade"><strong>getTextShade</strong></a>(...)</dt>
<dd><code>getTextShade(["nom"]) -> nombre entier</code>
<p>Retourne la valeur de la teinte de couleur définie pour le texte de
l'objet "nom". Si ce cadre contient du texte sélectionné, la valeur assignée
au premier caractère de la sélection est retournée. Si "nom" n'est pas
fourni, l'élément sélectionné est utilisé. </p>
@@ -69,6 +74,7 @@
texte doit être encodé en UTF (voir <a href="#-setText">setText</a>()
comme référence). Le premier caractère a un index de 0.
Insérer du texte à la position -1 l'ajoute à la fin du cadre.
Si "nom" n'est pas fourni, l'élément sélectionné est utilisé. </p>
+<p>Pour des raisons de performance, cette fonction ne réalise aucune mise Ã
jour de la mise en page du texte. En conséquence il est possible que vous
deviez appeler <a href="#-layoutText">layoutText()</a> or <a
href="#-layoutTextChain">layoutTextChain()</a> après avoir appelé cette
fonction et lorsque vous le jugez nécessaire préalablement à l'appel de
fonctions telles que <a href="#-getText">getText()</a> ou <a
href="#-getTextLines">getTextLines()</a>.</p>
<p>Peut générer IndexError dans le cas d'une insertion hors limites.</p></dd>
<dt><a name="-layoutText"><strong>layoutText</strong></a>(...)</dt>
Modified: trunk/Scribus/doc/it/scripterapi-textframes.html
URL:
http://scribus.net/websvn/diff.php?repname=Scribus&rev=23623&path=/trunk/Scribus/doc/it/scripterapi-textframes.html
==============================================================================
--- trunk/Scribus/doc/it/scripterapi-textframes.html (original)
+++ trunk/Scribus/doc/it/scripterapi-textframes.html Sun Apr 19 23:32:48 2020
@@ -67,7 +67,8 @@
<dt><a name="-getTextLines"><strong>getTextLines</strong>(...)</a></dt>
<dd><code>getTextLines(["name"]) -> integer</code>
-<p>Returns the number of lines of the text in the text frame "name". If "name"
is not given the currently selected item is used.</p></dd>
+<p>Returns the number of lines of text in text frame "name". If "name" is not
given the currently selected item is used.</p>
+<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>
<dt><a name="-getTextShade"><strong>getTextShade</strong></a>(...)</dt>
<dd><code>getTextShade(["name"]) -> integer</code>
@@ -85,12 +86,13 @@
<dt><a name="-insertHtmlText"><strong>insertHtmlText</strong></a>(...)</dt>
<dd><code>insertHtmlText("text", ["name"])</code>
-<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>
+<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>
<p>May raise WrongFrameTypeError if the target frame is not a text
frame</p></dd>
<dt><a name="-insertText"><strong>insertText</strong></a>(...)</dt>
<dd><code>insertText("text", pos, ["name"])</code>
-<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>
+<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>
+<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="#-getText">getText()</a> or <a
href="#-getTextLines">getTextLines()</a>.</p>
<p>May throw IndexError for an insertion out of bounds.</p></dd>
<dt><a name="-isPDFBookmark"><strong>isPDFBookmark</strong>(...)</a></dt>
Modified: trunk/Scribus/doc/ru/scripterapi-textframes.html
URL:
http://scribus.net/websvn/diff.php?repname=Scribus&rev=23623&path=/trunk/Scribus/doc/ru/scripterapi-textframes.html
==============================================================================
--- trunk/Scribus/doc/ru/scripterapi-textframes.html (original)
+++ trunk/Scribus/doc/ru/scripterapi-textframes.html Sun Apr 19 23:32:48 2020
@@ -67,7 +67,8 @@
<dt><a name="-getTextLines"><strong>getTextLines</strong>(...)</a></dt>
<dd><code>getTextLines(["name"]) -> integer</code>
-<p>Returns the number of lines of the text in the text frame "name". If "name"
is not given the currently selected item is used.</p></dd>
+<p>Returns the number of lines of text in text frame "name". If "name" is not
given the currently selected item is used.</p>
+<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>
<dt><a name="-getTextShade"><strong>getTextShade</strong></a>(...)</dt>
<dd><code>getTextShade(["name"]) -> integer</code>
@@ -85,12 +86,13 @@
<dt><a name="-insertHtmlText"><strong>insertHtmlText</strong></a>(...)</dt>
<dd><code>insertHtmlText("text", ["name"])</code>
-<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>
+<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>
<p>May raise WrongFrameTypeError if the target frame is not a text
frame</p></dd>
<dt><a name="-insertText"><strong>insertText</strong></a>(...)</dt>
<dd><code>insertText("text", pos, ["name"])</code>
-<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>
+<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>
+<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="#-getText">getText()</a> or <a
href="#-getTextLines">getTextLines()</a>.</p>
<p>May throw IndexError for an insertion out of bounds.</p></dd>
<dt><a name="-isPDFBookmark"><strong>isPDFBookmark</strong>(...)</a></dt>
Modified: trunk/Scribus/scribus/plugins/scriptplugin/cmdtext.h
URL:
http://scribus.net/websvn/diff.php?repname=Scribus&rev=23623&path=/trunk/Scribus/scribus/plugins/scriptplugin/cmdtext.h
==============================================================================
--- trunk/Scribus/scribus/plugins/scriptplugin/cmdtext.h (original)
+++ trunk/Scribus/scribus/plugins/scriptplugin/cmdtext.h Sun Apr 19
23:32:48 2020
@@ -88,6 +88,10 @@
\n\
Returns the number of lines of the text in the text frame \"name\".\n\
If \"name\" is not given the currently selected item is used.\n\
+\n\
+As this function depends on text layout being up-to-date, you may need to call
\n\
+layoutText() or layoutTextChain() before calling this function in order to get
\n\
+expected result.\n\
"));
/*! Get text lines */
PyObject *scribus_gettextlines(PyObject * /*self*/, PyObject* args);
@@ -99,8 +103,10 @@
Returns the text visible in text frame \"name\". If this text frame has some
text\n\
selected, the selected text is returned. If \"name\" is not given the
currently\n\
selected item is used.\n\
+\n\
This function returns only the text visible in specified frame. If you need to
\n\
retrieve the text contained in a text chain, use getAllText() instead.\n\
+\n\
As this function depends on text layout being up-to-date, you may need to call
\n\
layoutText() or layoutTextChain() before calling this function in order to get
\n\
expected result.\n\
@@ -190,7 +196,12 @@
Inserts the text \"text\" at the position \"pos\" into the text frame
\"name\".\n\
Text must be UTF encoded (see setText() as reference) The first character has
an\n\
index of 0. Inserting text at position -1 appends it to the frame. If \"name\"
is\n\
-not given the currently selected Item is used.\n\
+not given the currently selected item is used.\n\
+\n\
+For performance reason, this function does not update text layout in any way.
\n\
+As a consequence, you may need to call layoutText() or layoutTextChain() at
appropriate \n\
+times after calling this function and before calling functions such as
getText() \n\
+or getTextLines().\n\
\n\
May throw IndexError for an insertion out of bounds.\n\
"));
_______________________________________________
scribus-commit mailing list
[email protected]
http://lists.scribus.net/mailman/listinfo/scribus-commit
