\chapter Creating Scripts Using Qt Script for Applications

In this chapter we'll demonstrate how to create scripts for a
scriptable application. We will explain how to create a dialog using
\QS and then create and implement a convertToEuro() function. We will
write the scripts using the \c spreadsheet application that we created
in an earlier chapter.

\img dialog.png
\caption Settings for Euro Converter Finished Dialog

\section1 Creating a New Macro

A 'Macro' is simply a global \QS function.

Run the \c spreadsheet application if it isn't already running.
Click the \Toolbutton New button located on the Scripts toolbar to
invoke the \Widget{New Macro} dialog. Once we create a new macro, a
toolbar button will appear on the Scripts toolbar as a shortcut to
execute the macro.

\img newscript.png
\caption New Macro Toolbar Button

Follow the steps below to create the new macro:

\list

\i
The combobox is labelled 'Call Function'. Enter the name of the new
global function. Functions that already exist can be viewed by
clicking the arrow on the combobox, or by typing the name of the
function in the combobox.

\i
In addition to the function name, the macro can have a 'display name'
that appears, for example, in the application's \Menu Scripts menu.
Enter 'Euro Conversion' in the 'Name' line edit.

\i
If you want to associate an icon with the macro, click the ellipsis
button (\Button{...}) to invoke the \Widget{Open File} dialog and
select an icon to represent the macro. The icon will appear on the
application's toolbar as a shortcut to the script you create.

\endlist

Click \OK when you have entered the information in the \Widget {New
Script} dialog. The \Widget {Add Function} message box will pop up,
saying "The function doesn't exist. Do you want to add it?". Click
\Button Yes.

\caption Adding the New Function

\img addfunction.png

The \QSAD scripting environment opens with the new empty function added to
it. We will implement the scripting function in the following section.

\section1 Implementing the Macro and Creating a Dialog

In this section, we will implement the functionality of the
convert-to-euro macro. We want to present the user with a dialog in which they
can: 1) enter a range of rows and columns which are read from the
spreadsheet, 2) specify where in the spreadsheet the results should be
written, and 3) select a currency type to convert into Euros.

In \QSAD, we write the code to calculate the input values which are the input
column, start row, end row, and ouput column. We initialize these
variables to 1, but if the user selects a range in the spreadsheet, we
then use the selection for the initial values.

\quotefile spreadsheet/euro.qs
\skipto var input
\printuntil }

In \QS, we have some global objects. The most important one for our
example is called \c{Application}. This object contains other objects, but the
most important are the application objects. These are the objects
that the C++ application makes available to our script. In the \c
spreadsheet example, the sheets are available this way, e.g.,
Application.sheet1. 

To create a new dialog, write the following code. An explanation of the
code will follow.

\quotefile spreadsheet/euro.qs
\skipto d = new Dialog
\printuntil cancelButtonText =

Every dialog includes an Ok and Cancel button by default. After
creating the new dialog, simply change the caption property to
"Settings for Euro Convertor. Change the \Property text of the OK
Button to 'Calculate'. Change the \Property text property of the
Cancel button to 'Cancel'.

\section1 Adding Widgets to the Dialog

The Settings for Euro dialog consists of three spinboxes for selecting
the columns and rows on the spreadsheet, a spinbox to output the
result of the conversion, a group box to lay out the spinboxes, three
radiobuttons in a group box to select the currency to convert from,
and text labels for each of the widgets. If you run the dialog
application and resize it, all the widgets scale properly. The layout
of the widgets is determined by the order in which you write the code
for each widget.

\section2 Add A Group Box and Spinboxes

We'll start with the first group box and its widgets. Write the
following code in the editor to create the group box:

\quotefile spreadsheet/euro.qs
\skipto var g = new GroupBox
\printuntil d.add( g )

This code creates the new group box. Set its \Property title to
"Conversion Range:". Then add the group box to the dialog. Note
that every time a widget is created, it must be added its parent.  

Write the following code to add multiple spin boxes and text labels to
the group box:

\quotefile spreadsheet/euro.qs
\skipto var spinColumn 
\printuntil g.add( spinOutput )

With this code, we create the first spin box in the group box and and
name it spinColumn. This spin box corresponds to the column in the
spreadsheet from which the numbers will be read. Set the \Property
label property to "Column:". Set the \Property minimum property to 1
and the \Property maximum property to 100. Set the \Property number
property to the calculated input column. Add the spin box to the group
box.

Create the second spin box and name it spinStartRow. This spin box
corresponds to first row in the spreadsheet from which the numbers
will be read. Set the \Property label property to "Start at Row:". Set
the \Property minimum property to 1 and the \Property maximum property
to 100. Set the \Property number property to the calculated start row.
Add the spin box to the group box.

Create the third spin box and and name it spinEndRow. This spin box
corresponds to the last row in the spreadsheet from which the numbers
will be read. Set the \Property label property to "Start at Row:". Set
the \Property minimum property to 1 and the \Property maximum property
to 100. Set the \Property number property to the calculated end row.
Add the spin box to the group box.

Create the fourth spin box and and name it spinOutput. This spin box
corresponds to the column in the spreadsheet to which the converted
values will be returned. Set the \Property label property to "Start at
Row:". Set the \Property minimum property to 1 and the \Property
maximum property to 100. Set the \Property number property to the
calculated output column. Add the spin box to the group box.

\section2 Widget Lay Out

We'll add a column to the dialog to set layout so that the new group
box will be added beside the current group box.:

\quotefile spreadsheet/euro.qs
\skipto d.newColumn
\printline d.newColumn

\section2 Add a Group Box and Radio Buttons

Now we'll add the second group box and its widgets. Write the following
code to create the second group box:

\quotefile spreadsheet/euro.qs
\skipto g = new GroupBox
\printuntil d.add

This code creates the new group box similar to the first group box we
created earlier in the chapter. Change the \Property title property to
"Convert From:". Add the group box to the dialog. 

Write the following code to add multiple radio buttons to the group
box:

\quotefile spreadsheet/euro.qs
\skipto var radioUSD = new RadioButton
\printuntil g.add( radioNOK )

We create the first radio button and name it radioUSD. Set its
\Property text property to "USD". Set the \Property checked property
to true to make this radio button checked. Add the radio button to
the group box.

Create the second radio button and name it radioYEN. Set its
\Property text property to "YEN". Add the radio button to
the group box.

Create the third radio button and name it radioNOK. Set its
\Property text property to "NOK". Add the radio button to
the group box.

\section1 Running the Dialog

To run the dialog, click the \Button {Call Function} button in \QSAD.
The Call Function dialog pops up with a drop down list of functions
you created. Select convertToEuro and click \OK. The Output Window
displays errors found in the code. 

\omit
To run the dialog, type the following code:

\quotefile spreadsheet/euro.qs
\skipto if ( !d.exec
\printuntil return

The function now runs the dialog modally. The user clicks OK and the
function returns True, otherwise False. If the function returns False,
we return and do nothing. Otherwise we go on with the calculation.
\endomit

The first block of code reads what currency the user
chose and then initializes the divisor accordingly.

\quotefile spreadsheet/euro.qs
\skipto var divisor
\printuntil divisor = 0.1

The second block of code reads the range that the user has entered in the
dialog.

\quotefile spreadsheet/euro.qs
\skipto inputCol = sp
\printuntil endRow = sp

The third block of code checks that the entered range is valid. If it
is not valid, a warning is issued and the operation is canceled.

\quotefile spreadsheet/euro.qs
\skipto if ( endRow
\printuntil }

The fourth block of code reads the value from the spreadsheet,
calculates the results and then writes the results to the spreadsheet.

\quotefile spreadsheet/euro.qs
\skipto for ( var
\printuntil }

\section1 Running the EuroConvertor Macro

We are now ready to run the macro and invoke the dialog we just
created.

\list

\i In the spreadsheet, type a few numbers in column A, rows 1-3.

\i Select the cells you entered the numbers into so that they are highlighted.

\i Click the \Toolbutton {Euro Conversion} toolbar button. The
\Widget {Settings for Euro Converter} dialog pops up.

\i The 'Column', 'Start at Row', 'End at Row' and 'Output Column'
spinboxes are defaulted to the selection you made on the spreadsheet.

\i Select a currency to convert the numbers you entered on the
spreadsheet to euro.

\i Click \Button Calculate.

\i The results of the conversion are output starting at the 'Output
Column' indicated in the dialog.

\endlist

We've now coded a dialog and written the code to provide its
functionality, all purely using \QS. This should provide a taste of
the power and flexibility that \QSA can provide for your \QT C++
applications.


