r23623 by jghali - #16090: improve documentation for scripter's insertText() and getTextLines()
scribus-commit
scribus-commit at lists.scribus.net
Sun Apr 19 23:32:48 UTC 2020
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\
"));
More information about the scribus-commit
mailing list