# Category:QScript Reference

This page describes provides an overview of the technical detail of QScript.

Refer to:

## Classes

Creating scripts requires an understanding of how different bits of information are structured within Q. If you have limited programming experience you should first look at Category:JavaScript Reference#JavaScript Reference.

Things in JavaScript are referred to as objects. Within Q, there are various types of objects, such as Plots, Tables and Filters. Some of the different types of QScript objects, and their interrelationships, are shown in the diagram below.

Objects are manipulated by methods. For example, the createBanner method can be used on a DataFile object to create a new Question object. For example, the following code creates a new object called demo_banner:

var demo_banner = data_file.createBanner("Demographic banner",
[[data_file.getQuestionByName("Age")],
[data_file.getQuestionByName("Gender")],
[data_file.getQuestionByName("Work status")]]);

## Global Variables/Functions

These can be used in any script, in addition to the usual functions provided by JavaScript.

## project

Returns the Project object.

Shows a box containing your message.
 message Whatever you pass in here will be converted to a string. help_page Optional text containing a URL or a Q Wiki topic. A help button will be added to the dialog box. When clicked, the page corresponding to the text is opened in the default browser. Example: alert('The QScript is stopped! Click OK to continue.'); 

Presents message with Yes and No buttons.
 message Text to appear in the dialog box. help_page Optional text containing a URL or a Q Wiki topic. A help button will be added to the dialog box. When clicked, the page corresponding to the text is opened in the default browser. Returns: True if Yes pushed, false otherwise. Example: if (askYesNo('Do you like green?')) log('User likes green.'); 

## assert(condition, message)

Checks that 'condition' is true. If not your script will be aborted.
 condition An expression that evaluates to true or false. message A message to display. Example: assert(project.dataFiles[0].getVariableByName('Q3') != null); 

## confirm(message, help_page)

Presents message with OK and Cancel buttons.
 message Text to appear in the dialog box. help_page Optional text containing a URL or a Q Wiki topic. A help button will be added to the dialog box. When clicked, the page corresponding to the text is opened in the default browser. Returns: True if OK pushed, false otherwise. Example: if (confirm('Do you want to show an alert?')) alert('Alert!'); 

## includeFile(filename)

Runs a QScript file. Any global variables or functions defined by the other script will then be available to the calling script. Duplicate calls to includeFile() with the same 'filename' are ignored.
 filename A path to a QScript source file. If the path is relative then it is relative to the directory containing the original script. Example: includeFile('Utilities.QScript'); 

## includeWeb(title)

Runs a QScript file from wiki.q-researchsoftware.com. Any global variables or functions defined by the other script will then be available to the calling script. Duplicate calls to includeWeb() with the same 'title' are ignored. This may not be used in the Inputs JavaScript for a Calculation.
 title The title of the wiki page containing the script. The page must be in the QScript Examples Library category. Example: includeWeb('Utilities for Selecting Variables'); 

## log(message)

Adds a line to the output log for this script.
 message Whatever you pass in here will be converted to a string. Example: log('My QScript was here.'); 

## prompt(message, default_value, help_page)

Allows the user to enter text into a single text box. If the user clicks Cancel then the script will stop running.
 message Text to appear in the dialog box. default_value Pre-entered default text for the user. help_page Optional text containing a URL or a Q Wiki topic. A help button will be added to the dialog box. When clicked, the page corresponding to the text is opened in the default browser. Returns: The text that was in the edit box when the user clicked OK. Example: var name = prompt('Enter you name:'); 

## scriptType()

Returns "QScript", "Rule" or "RGui" depending on how the JavaScript code is being run. See also runMode.

## selectMany(message, options, help_page, initial_selected_indices)

Presents a list of alternatives, any number of which may be selected. Returns an array of indices. If the user clicks Cancel then the script will stop running.
 message Text to appear in the dialog box. options An array of strings, any number of which (or none) may be selected. help_page Optional text containing a URL or a Q Wiki topic. A help button will be added to the dialog box. When clicked, the page corresponding to the text is opened in the default browser. initial_selected_indices An optional array of indices into the options that indicates which will be selected by default. Returns: An array of the indices chosen. Example: var indices = selectMany('What have you had today?', ['Breakfast', 'Lunch', 'Dinner']); log('User has eaten '+indices.length+' meals.'); 

## selectOne(message, alternatives, help_page, initial_selected_index)

Presents a drop-down list of alternatives. If the user clicks Cancel then the script will stop running.
 message Text to appear in the dialog box. alternatives An array of strings, each of which is one alternative. help_page Optional text containing a URL or a Q Wiki topic. A help button will be added to the dialog box. When clicked, the page corresponding to the text is opened in the default browser. initial_selected_index Optional index into alternatives that indicates which will be selected by default. Returns: The zero-based index of the selected alternative. Example: var animal_index = selectOne('What is your favourite?', ['Dog', 'Cat', 'Bird']);