r22441 by gpittman - Edit docs for some additional examples, plus consistency of appearance
scribus-commit
scribus-commit at lists.scribus.net
Thu Mar 22 01:12:51 UTC 2018
Author: gpittman
Date: Thu Mar 22 01:12:51 2018
New Revision: 22441
URL: http://scribus.net/websvn/listing.php?repname=Scribus&sc=1&rev=22441
Log:
Edit docs for some additional examples, plus consistency of appearance
Modified:
trunk/Scribus/doc/en/scripterapi-dialogs.html
trunk/Scribus/doc/en/scripterapi-doc.html
trunk/Scribus/doc/en/scripterapi-page.html
trunk/Scribus/doc/en/scripterapi-select.html
trunk/Scribus/doc/en/scripterapi-textframes.html
Modified: trunk/Scribus/doc/en/scripterapi-dialogs.html
URL: http://scribus.net/websvn/diff.php?repname=Scribus&rev=22441&path=/trunk/Scribus/doc/en/scripterapi-dialogs.html
==============================================================================
--- trunk/Scribus/doc/en/scripterapi-dialogs.html (original)
+++ trunk/Scribus/doc/en/scripterapi-dialogs.html Thu Mar 22 01:12:51 2018
@@ -16,8 +16,9 @@
<p>Shows a File Open dialog box with the caption "caption". Files are filtered with the filter string "filter". A default filename or file path can also supplied, leave this string empty when you don't want to use it. A value of True for haspreview enables a small preview widget in the FileSelect box. When the issave parameter is set to True the dialog acts like a "Save As" dialog otherwise it acts like a "File Open Dialog". When the isdir parameter is True the dialog shows and returns only directories. The default for all of the opional parameters is False.<p>
<p>The filter, if specified, takes the form 'comment (*.type *.type2 ...)'. For example 'Images (*.png *.xpm *.jpg)'.</p>
<p>Refer to the Qt-Documentation for QFileDialog for details on filters.</p>
-<p>Example: <a href="#-fileDialog">fileDialog</a>('Open input', 'CSV files (*.csv)')<br>
-Example: <a href="#-fileDialog">fileDialog</a>('Save report', defaultname='report.txt', issave=True)</p></dd>
+<p>Examples:</p>
+<p><b>fileDialog('Open input', 'CSV files (*.csv)')</p>
+<p>fileDialog('Save report', defaultname='report.txt', issave=True)</b></p></dd>
<dt><a name="-fileQuit"><strong>fileQuit</strong></a>(...)</dt>
<dd><code>fileQuit()</code>
@@ -43,14 +44,8 @@
<li>BUTTONOPT_ESCAPE Pressing escape presses this button.</li>
</ul>
<p>Usage examples:</p>
-<pre>
-result = <a href="#-messageBox">messageBox</a>('Script failed',
- 'This script only works when you have a text frame selected.',
- ICON_ERROR)
-result = <a href="#-messageBox">messageBox</a>('Monkeys!', 'Something went ook! <i>Was it a monkey?</i>',
- ICON_WARNING, BUTTON_YES|BUTTONOPT_DEFAULT,
- BUTTON_NO, BUTTON_IGNORE|BUTTONOPT_ESCAPE)
-</pre>
+<p><b>result = messageBox</a>('Script failed', 'This script only works when you have a text frame selected.', ICON_ERROR)</p>
+<p>result = messageBox('Monkeys!', 'Something went ook! <i>Was it a monkey?</i>', ICON_WARNING, BUTTON_YES|BUTTONOPT_DEFAULT, BUTTON_NO, BUTTON_IGNORE|BUTTONOPT_ESCAPE)</b></p>
<p>Defined button and icon constants: BUTTON_NONE, BUTTON_ABORT, BUTTON_CANCEL, BUTTON_IGNORE, BUTTON_NO, BUTTON_NOALL, BUTTON_OK, BUTTON_RETRY, BUTTON_YES, BUTTON_YESALL, ICON_NONE, ICON_INFORMATION, ICON_WARNING, ICON_CRITICAL.</p></dd>
<dt><a name="-newDocDialog"><strong>newDocDialog</strong></a>(...)</dt>
Modified: trunk/Scribus/doc/en/scripterapi-doc.html
URL: http://scribus.net/websvn/diff.php?repname=Scribus&rev=22441&path=/trunk/Scribus/doc/en/scripterapi-doc.html
==============================================================================
--- trunk/Scribus/doc/en/scripterapi-doc.html (original)
+++ trunk/Scribus/doc/en/scripterapi-doc.html Thu Mar 22 01:12:51 2018
@@ -30,11 +30,17 @@
<dt><a name="-getUnit"><strong>getUnit</strong></a>(...)</dt>
<dd><code>getUnit() -> integer (Scribus unit constant)</code>
-<p>Returns the measurement units of the document. The returned value will be one of the UNIT_* constants: UNIT_INCHES, UNIT_MILLIMETERS, UNIT_PICAS, UNIT_POINTS.</p></dd>
+<p>Returns the measurement units of the document. The returned value will be one of the UNIT_* constants: UNIT_INCHES, UNIT_MILLIMETERS, UNIT_PICAS, UNIT_POINTS.</p>
+<p>Typically you may use this command so that you can change the measurement units to something else, for which you are creating or modifying objects based some particular units, like points, after which you want to return to whatever the original units were.</p><p><b>original = getUnit()</b></p>
+<p><i>do some operations...then later</i></p>
+<p><b>setUnit(original)</b></p>
+</dd>
<dt><a name="-haveDoc"><strong>haveDoc</strong></a>(...)</dt>
<dd><code>haveDoc() -> bool</code>
-<p>Returns true if there is a document open.</p></dd>
+<p>Returns true if there is a document open. Since this returns a boolean, typically this will be used in a conditional clause:</p>
+<p><b>if haveDoc():</b></p>
+<p>so that you can deal with the situation where no document exists with an <b>else:</b> clause.</p></dd>
<!--<dt><a name="-importSVG"><strong>importSVG</strong>(...)</a></dt>
<dd><code>importSVG("string")</code>
@@ -50,7 +56,7 @@
<dt><a name="-newDoc"><strong>newDoc</strong></a>(...)</dt>
<dd><code>newDoc(size, margins, orientation, firstPageNumber, unit, facingPages, firstSideLeft) -> bool</code>
-<p>WARNING: Obsolete procedure! Use <a href="#-newDocument">newDocument</a> instead.</p>
+<p>WARNING: Obsolete procedure! Use <a href="#-newDocument">newDocument</a> instead. Also note that this commands requires 7 parameters, whereas the preferred <b>newDocument()</b> command requires 8.</p>
<p>Creates a new document and returns true if successful. The parameters have the
following meaning:</p>
<ul>
@@ -68,6 +74,7 @@
<dt><a name="-newDocument"><strong>newDocument</strong>(...)</a></dt>
<dd><code>newDocument(size, margins, orientation, firstPageNumber,
unit, pagesType, firstPageOrder, numPages) -> bool</code>
+<p>Note that this commands requires 8 parameters, whereas the obsolete <b>newDoc()</b> command required 7. The additional parameter indicates how many pages to create.</p>
<p>Creates a new document and returns true if successful. The parameters have the
following meaning:
<ul>
@@ -93,8 +100,8 @@
for the document. PAPER_* constants are a series of tuples specific to the document size, with the values corresponding to points. Therefore, if you are creating a document and using UNIT_MILLIMETERS for example, DO NOT USE the PAPER_* constants.</p>
<p>For A and B paper formats there are now new constants to use with UNIT_MILLIMETERS, named for example, PAPER_A4_MM, or PAPER_B6_MM.</p>
<p>Examples:</p>
-<p>newDocument(PAPER_A4, (10, 10, 20, 20), LANDSCAPE, 7, UNIT_POINTS, PAGE_4, 3, 1)</p>
-<p>newDocument(PAPER_A4_MM, (10, 10, 20, 20), LANDSCAPE, 7, UNIT_MILLIMETERS, PAGE_4, 3, 1)</p>
+<p><b>newDocument(PAPER_A4, (10, 10, 20, 20), LANDSCAPE, 7, UNIT_POINTS, PAGE_4, 3, 1)</b></p>
+<p><b>newDocument(PAPER_A4_MM, (10, 10, 20, 20), LANDSCAPE, 7, UNIT_MILLIMETERS, PAGE_4, 3, 1)</b></p>
<p>May raise ScribusError if is firstPageOrder bigger than allowed by pagesType.</p>
</dd>
@@ -158,7 +165,10 @@
<dt><a name="-setUnit"><strong>setUnit</strong></a>(...)</dt>
<dd><code>setUnit(type)</code>
<p>Changes the measurement unit of the document. Possible values for "unit" are defined as constants UNIT_<type>.</p>
-<p>May raise ValueError if an invalid unit is passed.</p></dd>
+<p>May raise ValueError if an invalid unit is passed.</p>
+<p>As noted above, typically you may use this command so that you can change the measurement units to something else, for which you are creating or modifying objects based some particular units, like points, after which you want to return to whatever the original units were.</p><p><b>original = getUnit()</b></p>
+<p><i>do some operations...then later</i></p>
+<p><b>setUnit(original)</b></p></dd>
<dt><a name="-setBaseLine"><strong>setBaseLine</strong></a>(...)</dt>
<dd><code>setBaseLine(grid, offset)</code>
Modified: trunk/Scribus/doc/en/scripterapi-page.html
URL: http://scribus.net/websvn/diff.php?repname=Scribus&rev=22441&path=/trunk/Scribus/doc/en/scripterapi-page.html
==============================================================================
--- trunk/Scribus/doc/en/scripterapi-page.html (original)
+++ trunk/Scribus/doc/en/scripterapi-page.html Thu Mar 22 01:12:51 2018
@@ -85,12 +85,12 @@
<dt><a name="-gotoPage"><strong>gotoPage</strong></a>(...)</dt>
<dd><code>gotoPage(nr)</code>
-<p>Moves to the page "nr" (that is, makes the current page "nr"). Note that gotoPage doesn't (curently) change the page the user's view is displaying, it just sets the page that script commands will operates on.</p>
+<p>Moves to the page "nr" (that is, makes the current page "nr"). Note that gotoPage doesn't (currently) change the page the user's view is displaying, it just sets the page that script commands will operates on.</p>
<p>May raise IndexError if the page number is out of range.</p></dd>
<dt><a name="-importPage"><strong>importPage</strong>(...)</a></dt>
<dd><code></code>
-<p>importPage("fromDoc", (pageList), [create, imortwhere, importwherePage]) Imports a set of pages (given as a tuple) from an existing document (the file name must be given). This functions maps the "Page->Import" dropdown menu function. fromDoc: string; the filename of the document to import pages from pageList: tuple with page numbers of pages to import create: number; 0 to replace existing pages, 1 (default) to insert new pages importWhere: number; the page number (of the current document) at which import the pages importWherePage: number; used if create==1; 0 to create pages before selected page; 1 to create pages after selected page; 2 (default) to create pages at the end of the document</p></dd>
+<p>importPage("fromDoc", (pageList), [create, importwhere, importwherePage]) Imports a set of pages (given as a tuple) from an existing document (the file name must be given). This functions maps the "Page->Import" dropdown menu function. fromDoc: string; the filename of the document to import pages from pageList: tuple with page numbers of pages to import create: number; 0 to replace existing pages, 1 (default) to insert new pages importWhere: number; the page number (of the current document) at which import the pages importWherePage: number; used if create==1; 0 to create pages before selected page; 1 to create pages after selected page; 2 (default) to create pages at the end of the document</p></dd>
<dt><a name="-newPage"><strong>newPage</strong></a>(...)</dt>
<dd><code>newPage(where [,"masterpage"])</code>
@@ -116,8 +116,9 @@
<dt><a name="-setHGuides"><strong>setHGuides</strong></a>(...)</dt>
<dd><code>setHGuides(list)</code>
<p>Sets horizontal guides. Input parameter must be a list of guide positions measured in the current document units - see UNIT_<type> constants.</p>
-<p>Example: <a href="#-setHGuides">setHGuides</a>(<a href="#-getHGuides">getHGuides</a>() + [200.0, 210.0] # add new guides without any lost<br>
-<a href="#-setHGuides">setHGuides</a>([90,250]) # replace current guides entirely</p></dd>
+<p>Example:</p>
+<p><b>setHGuides(getHGuides() + [200.0, 210.0])</b> # this will add new guides while saving existing guides</p>
+<p><b>setHGuides([90,250])</b> # this will replace current guides entirely</p></dd>
<dt><a name="-setRedraw"><strong>setRedraw</strong></a>(...)</dt>
<dd><code>setRedraw(bool)</code>
@@ -125,7 +126,7 @@
<dt><a name="-setVGuides"><strong>setVGuides</strong></a>(...)</dt>
<dd><code>setVGuides()</code>
-<p>See <a href="#-setHGuides">setHGuides</a>.</p></dd>
+<p>The usage is analagous to that of <a href="#-setHGuides">setHGuides</a> for either adding to existing guides or replacing them.</p></dd>
</dl>
</body>
Modified: trunk/Scribus/doc/en/scripterapi-select.html
URL: http://scribus.net/websvn/diff.php?repname=Scribus&rev=22441&path=/trunk/Scribus/doc/en/scripterapi-select.html
==============================================================================
--- trunk/Scribus/doc/en/scripterapi-select.html (original)
+++ trunk/Scribus/doc/en/scripterapi-select.html Thu Mar 22 01:12:51 2018
@@ -33,7 +33,7 @@
<dt><a name="-selectObject"><strong>selectObject</strong></a>(...)</dt>
<dd><code>selectObject("name")</code>
-<p>Selects the object with the given "name".</p></dd>
+<p>Selects the object with the given "name". If what you wish to do is to paste a copy of the object to another page, you must first <b>copyObject()</b>, then <b>pasteObject()</b>. See <b>Manipulating Objects</b></p></dd>
</dl>
</body>
Modified: trunk/Scribus/doc/en/scripterapi-textframes.html
URL: http://scribus.net/websvn/diff.php?repname=Scribus&rev=22441&path=/trunk/Scribus/doc/en/scripterapi-textframes.html
==============================================================================
--- trunk/Scribus/doc/en/scripterapi-textframes.html (original)
+++ trunk/Scribus/doc/en/scripterapi-textframes.html Thu Mar 22 01:12:51 2018
@@ -95,10 +95,10 @@
<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>
<p>May throw IndexError if the selection is outside the bounds of the text.</p>
<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>
-<p><dd>def SelectAllText(textframe):<br/>
- texlen = scribus.getTextLength(textframe)<br/>
- scribus.selectText(0,texlen,textframe)<br/>
- return</dd></p></dd>
+<p><b>def SelectAllText(textframe):</p>
+ <p> texlen = scribus.getTextLength(textframe)</p>
+ <p> scribus.selectText(0,texlen,textframe)</p>
+ <p> return</b></p></dd>
<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>
More information about the scribus-commit
mailing list