Script Developers: Qt constants and scripting in xTuple ERP 3.3.0

This is the first in an occasional series of blog posts written from a developer's perspective. Most of the entries will be written for other developers - whether you work on scripts or the core, work for an xTuple ERP customer or want to extend PostBooks or are an xTuple VAR or are simply interested in how the product works internally. Some may have a wider appeal.

If you have been writing scripts for the xTuple ERP application or have been thinking about it, you'll be glad to know that this is getting a little easier with every release.  Comments about these changes rarely appear in the release notes because there are no Mantis issue for them. As we develop scripts internally, we extend the scripting API to make this easier.

We recently added access by name to many of the Qt enumerated values. Almost all of the enum constants defined in the Qt global namespace have been defined in release 3.3.0 as properties of a global Qt object.*  As an example of where this is useful, here is an excerpt from DisplayItemLocations.script (in xtuple/trunk/share/sample_scripts):

/* ...  addColumn() takes the following arguments:
   1) column title text
   2) column width in pixels
   3) default column alignment - see the Qt docs for Qt::Alignment
   4) default visibility - is this column visible when the window is first shown
   5) column name from the query to put in this column of the display
*/
...
list.addColumn("Lot/Serial Number", 115, 1, true, "lsnumber")
list.addColumn("Loc. Qty",           65, 2, true, "itemloc_qty")
...

What do the 1 and 2 mean in the addColumn() calls? According to the comment, they are column alignment settings and you have to read the Qt documentation to figure out what they stand for. In 3.3.0 and beyond, you can rewrite these lines symbolically:

list.addColumn("Lot/Serial Number", 115, Qt.AlignLeft,  true, "lsnumber")
list.addColumn("Loc. Qty",           65, Qt.AlignRight, true, "itemloc_qty")

Written this way, the intent is more clear and the comment can probably be removed.

We also made the enumerated values for QMessageBox buttons and roles available to scripts. Here's an example from one of the xtbatch scripts:

...
if (toolbox.messageBox("question", mywindow,
                       qsTr("Would you like to Save?"),
                       qsTr("The Form has not yet been saved to the "
                          + "database. Before adding details you must save "
                          + "the Form so it exists on the database."),
                        QMessageBox.Save, QMessageBox.Cancel) != QMessageBox.Save)
   return;
...

Note the QMessageBox.Save and QMessageBox.Cancel values near the end. These make a lot more sense than 0x00000800 and 0x00400000.

You will still need to consult the Qt documentation when you write something new but reading and writing scripts have become much easier.

There are other additions to the script API as well. Compare the contents of xtuple/tags/R3_2_2/scriptapi with xtuple/tags/R3_3_0BETA3 and you'll see that about ten more Qt classes are now directly available to your scripts. Eventually the documentation will catch up.

 * The exceptions are the values for the HitTestAccuracy and WhiteSpaceMode enumerations. The names exposed in the Qt object were collected from the Qt 4.5.1 documentation.