r22280 by gpittman -

Tue Dec 26 16:42:16 UTC 2017

Author: gpittman
Date: Tue Dec 26 16:42:16 2017
New Revision: 22280

URL: http://scribus.net/websvn/listing.php?repname=Scribus&sc=1&rev=22280
Log:
fixing/enhancing the documentation about dialog buttons and returned values

Modified:
    branches/Version14x/Scribus/scribus/doc/en/menu.xml
    branches/Version14x/Scribus/scribus/doc/en/scripterapi-constants.html
    branches/Version14x/Scribus/scribus/doc/en/scripterapi-dialogs.html

Modified: branches/Version14x/Scribus/scribus/doc/en/menu.xml
URL: http://scribus.net/websvn/diff.php?repname=Scribus&rev=22280&path=/branches/Version14x/Scribus/scribus/doc/en/menu.xml
==============================================================================

--- branches/Version14x/Scribus/scribus/doc/en/menu.xml	(original)
+++ branches/Version14x/Scribus/scribus/doc/en/menu.xml	Tue Dec 26 16:42:16 2017
@@ -140,7 +140,7 @@
 			<submenuitem text="PDF Export" file="scripterapi-PDFfile.html"/>
 			<submenuitem text="Printing" file="scripterapi-Printer.html"/>
 			<submenuitem text="Image Export" file="scripterapi-ImageExport.html"/>
-			<submenuitem text="Pre-defined Constants" file="scripterapi-constants.html"/>
+			<submenuitem text="Predefined Constants" file="scripterapi-constants.html"/>
 			<submenuitem text="Scripter Extensions" file="scripter-extensions.html"/>
 			<submenuitem text="Scripter Extensions API" file="scripterapi-extensions.html"/>
 		</submenuitem>

Modified: branches/Version14x/Scribus/scribus/doc/en/scripterapi-constants.html
URL: http://scribus.net/websvn/diff.php?repname=Scribus&rev=22280&path=/branches/Version14x/Scribus/scribus/doc/en/scripterapi-constants.html
==============================================================================
--- branches/Version14x/Scribus/scribus/doc/en/scripterapi-constants.html	(original)
+++ branches/Version14x/Scribus/scribus/doc/en/scripterapi-constants.html	Tue Dec 26 16:42:16 2017
@@ -17,7 +17,7 @@
     messageBox("Scribus - Python script",
         "This script requires Scribus 1.2.2 or newer. "+\
         "You're running %s." % scribus.scribus_version,
-        ICON_CRITICAL)
+        scribus.ICON_CRITICAL)
     sys.exit()
 </pre>
 
@@ -181,14 +181,26 @@
 
 <h4>Dialog Buttons</h4>
 <dl>
-    <dt>BUTTON_ABORT</dt>
-    <dt>BUTTON_CANCEL</dt>
-    <dt>BUTTON_IGNORE</dt>
-    <dt>BUTTON_NO</dt>
-    <dt>BUTTON_NONE</dt>
-    <dt>BUTTON_OK</dt>
-    <dt>BUTTON_RETRY</dt>
-    <dt>BUTTON_YES</dt>
+<p>This table shows the return values when you are using buttons, for example, with the <strong>messageBox()</strong> command. The value will be the same regardless of which button (button1, button2, or button3) these constants have been assigned.</p>
+<p>
+<table>
+<tr><td><strong>Button Type</strong></td><td><strong>Return Value</strong></td></tr>
+<tr>    <td>BUTTON_ABORT</td><td>262144</td></tr>
+<tr>    <td>BUTTON_CANCEL</td><td>4194304</td></tr>
+    <tr><td>BUTTON_IGNORE</td><td>1048576</td></tr>
+    <tr><td>BUTTON_NO</td><td>65536</td></tr>
+    <tr><td>BUTTON_NONE</td><td>N/A</td></tr>
+    <tr><td>BUTTON_OK</td><td>1024</td></tr>
+    <tr><td>BUTTON_RETRY</td><td>524288</td></tr>
+    <tr><td>BUTTON_YES</td><td>16384</td></tr>
+</table></p>
+
+<p>There is also a hierarchy of buttons in terms of where they appear in the dialogs, although note its complexity:</p>
+<dl>
+    <dt>BUTTON_YES will always be to the left of all other buttons.</dt>
+    <dt>BUTTON_NO will always be to the left of all other buttons, except BUTTON_YES.</dt>
+    <dt>BUTTON_RETRY, BUTTON_OK, and BUTTON_IGNORE are in a middle group which appear relative to each other according to assignment, so whichever is button1, will be to the left of button2, and so on. Any of these will always be to the left of BUTTON_CANCEL or BUTTON_ABORT.</dt>
+    <dt>BUTTON_CANCEL and BUTTON_ABORT are in a rightward group that will always be to the right of all other buttons, but with respect to each other according to assignment.</dt>
 </dl>
 
 <h4>Dialog Icons</h4>

Modified: branches/Version14x/Scribus/scribus/doc/en/scripterapi-dialogs.html
URL: http://scribus.net/websvn/diff.php?repname=Scribus&rev=22280&path=/branches/Version14x/Scribus/scribus/doc/en/scripterapi-dialogs.html
==============================================================================
--- branches/Version14x/Scribus/scribus/doc/en/scripterapi-dialogs.html	(original)
+++ branches/Version14x/Scribus/scribus/doc/en/scripterapi-dialogs.html	Tue Dec 26 16:42:16 2017
@@ -33,7 +33,7 @@
 icon=ICON_NONE, button1=BUTTON_OK|BUTTONOPT_DEFAULT,
 button2=BUTTON_NONE, button3=BUTTON_NONE) -> integer</code>
 <p>Displays a message box with the title "caption", the message "message", and an icon "icon" and up to 3 buttons. By default no icon is used and a single button, OK, is displayed. Only the caption and message arguments are required, though setting an icon and appropriate button(s) is strongly recommended. The message text may contain simple HTML-like markup.</p>
-<p>Returns the number of the button the user pressed. Button numbers start at 1.</p>
+<p>Returns the integer value of the button the user pressed. These values are constant regardless of button position. For example BUTTON_YES will always return 16384. See <a href="scripterapi-constants.html">Predefined Constants</a> for further information.</p>
 <p>For the icon and the button parameters there are predefined constants available with the same names as in the Qt Documentation. These are the BUTTON_* and ICON_* constants defined in the module. There are also two extra constants that can be binary-ORed with button constants:</p>
 <ul>
 <li>BUTTONOPT_DEFAULT Pressing enter presses this button.</li>


