|Home | Tutorial | Classes | Functions | QSA Workbench | Language | Qt API | QSA Articles | Qt Script for Applications |

[Prev: How to Design and Implement Application Objects] [Home]

## Creating Qt Scripts

In this chapter we'll demonstrate how to create scripts for a scriptable application using QSA Workbench, a scripting environment for managing, creating, and running scripts. QSA Workbench provides a code completion feature that makes writing scripts easier. We will explain how to create a dialog using Qt Script and then create and implement a convertToEuro() function. We will write the scripts using the `spreadsheet` application that we created in the previous chapter.

> Settings for Euro Converter Finished Dialog

### Creating a New Macro

A 'Macro' is simply a global Qt Script function.

Run the `spreadsheet` application if it isn't already running. Click the New button located on the Scripts toolbar to invoke the 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.

> New Macro Toolbar Button

Follow the steps below to create the new macro:

- 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.

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

- If you want to associate an icon with the macro, click the ellipsis button (...) to invoke the 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.

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

> Adding the New Function

QSA Workbench opens with the new empty function added to it. We will implement the scripting function in the following section.

### 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 the QSA Workbench editor, 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.

            var inputCol = 1;
            var startRow = 1;
            var endRow = 1;
            var outputCol = 1;
            if ( Application.sheet1.numSelections > 0 ) {
                var sel = Application.sheet1.selection( 0 );
                inputCol = sel.x + 1;
                outputCol = inputCol + 1;
                startRow = sel.y + 1;
                endRow = sel.bottom + 1;
            }

In Qt Script, we have some global objects. The most important one for our example is called `Application`. This object contains application objects. Application objects are the objects that the C++ application makes available to our script. In the `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.

            d = new Dialog;
            d.caption = "Settings for Euro Converter";
            d.okButtonText = "Calculate";
            d.cancelButtonText = "Cancel";

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 text of the OK Button to 'Calculate'. Change the text property of the Cancel button to 'Cancel'.

### 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 add them to the dialog or the group box.

#### Add A Group Box and Spin boxes

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

            var g = new GroupBox;
            g.title = "Conversion Range:";
            d.add( g );

This code creates the new group box. Set its 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:

            var spinColumn = new SpinBox;
            spinColumn.label = "Column:";
            spinColumn.minimum = 1;
            spinColumn.maximum = 100;
            spinColumn.value = inputCol;
            g.add( spinColumn );

            var spinStartRow = new SpinBox;
            spinStartRow.label = "Start at Row:";
            spinStartRow.minimum = 1;
            spinStartRow.maximum = 100;
            spinStartRow.value = startRow;
            g.add( spinStartRow );

            var spinEndRow = new SpinBox;
            spinEndRow.label = "End at Row:";
            spinEndRow.minimum = 1;
            spinEndRow.maximum = 100;
            spinEndRow.value = endRow;
            g.add( spinEndRow );

            var spinOutput = new SpinBox;
            spinOutput.label = "Output Column:";
            spinOutput.minimum = 1;
            spinOutput.maximum = 100;
            spinOutput.value = outputCol;
            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 label property to "Column:". Set the minimum property to 1 and the maximum property to 100. Set the 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 label property to "Start at Row:". Set the minimum property to 1 and the maximum property to 100. Set the 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 label property to "Start at Row:". Set the minimum property to 1 and the maximum property to 100. Set the 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 label property to "Start at Row:". Set the minimum property to 1 and the maximum property to 100. Set the number property to the calculated output column. Add the spin box to the group box.

#### 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.:

            d.newColumn();

#### 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:

            var g = new GroupBox;
            g.title = "Conversion Range:";
            d.add( g );

This code creates the new group box similar to the first group box we created earlier in the chapter. Change the 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:

            var radioUSD = new RadioButton;
            radioUSD.text = "USD";
            radioUSD.checked = true;
            g.add(radioUSD);
            var radioYEN = new RadioButton;
            radioYEN.text = "YEN";
            g.add(radioYEN);
            var radioNOK = new RadioButton;
            radioNOK.text = "NOK";
            g.add(radioNOK);

We create the first radio button and name it radioUSD. Set its text property to "USD". Set the 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 text property to "YEN". Add the radio button to the group box.

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

### Running the Dialog

To run the dialog, click the Call Function button in QSA Workbench. 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.

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

            var divisor;

            if( radioUSD.checked )
                divisor = 0.930492;
            else if( radioYEN.checked )
                divisor = 0.007677;
            else if ( radioNOK.checked )
                divisor = 0.133828;

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

            inputCol = spinColumn.value - 1;
            outputCol = spinOutput.value - 1;
            startRow = spinStartRow.value - 1;
            endRow = spinEndRow.value - 1;

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.

            if ( endRow < startRow ) {
                MessageBox.critical( "Cannot calculate!", "Error" );
                return;
            }

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

            for ( var i = startRow; i <= endRow; ++i ) {
                var input = Application.sheet1.text( i, inputCol );
                Application.sheet1.setText( i, outputCol,
                                            Math.round( input / divisor * 100 ) / 100 );
            }

### Running the EuroConvertor Macro

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

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

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

- Click the Euro Conversion toolbar button. The Settings for Euro Converter dialog pops up.

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

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

- Click Calculate.

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

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