RuleForm

From Q
Jump to: navigation, search

This feature is new in Q 4.8.

RuleForm

Provides Rules with methods for defining and interrogating controls. These controls will be shown to the user when the user creates or edits a Rule. Appears to Rule code as the form variable.

checkBox(arguments)

Creates a new labelled checkBox control. Note that the label is shown on the left. If you would prefer that the label is shown to the right of the checkBox, use the old-style form.newCheckBox(). If setInputControls() is present, then then control will only appear if it is listed in the array given to setInputControls(), otherwise it will appear automatically.
argumentsA dictionary of arguments to pass to the function: "label": A label which appears adjacent to the control (a string). "name": The name of the control (a string). If not specified, one will be automatically created. "prompt": The text (an html string) for the tooltip. Default: none. "page": The name of the page in the Inspector to place the control on. The default is set by calling form.page, which in turn defaults to "Inputs". "group": The name of the group in the Inspector to place the control on. The default is set by calling form.group, which in turn defaults to "", which is an unnamed group at the top of the page.
Returns:A new ScriptLabelledCheckBox object.

colorPicker(arguments)

Creates a new labelled control which allows the user to select a color. If setInputControls() is present, then then control will only appear if it is listed in the array given to setInputControls(), otherwise it will appear automatically.
argumentsA dictionary of arguments to pass to the function: "label": A label which appears adjacent to the control (a string). "name": The name of the control (a string). If not specified, one will be automatically created. "prompt": The text (an html string) for tooltip. Default: none. "page": The name of the page in the Inspector to place the control on. The default is set by calling form.page, which in turn defaults to "Inputs". "group": The name of the group in the Inspector to place the control on. The default is set by calling form.group, which in turn defaults to "", which is an unnamed group at the top of the page.
Returns:A new ScriptLabelledColorPicker object.

comboBox(arguments)

Creates a new labelled control to allow the user to select an item. If setInputControls() is present, then then control will only appear if it is listed in the array given to setInputControls(), otherwise it will appear automatically.
argumentsA dictionary of arguments to pass to the function: "label": A label which appears adjacent to the control (a string). "name": The name of the control (a string). If not specified, one will be automatically created. "alternatives": An array of strings to show in the drop down. "types": A list of allowed values (an array of strings). These may be 'Variable', 'Question' or 'Table'. "required": A flag indicating whether an input is required in order to be valid. Default: true. "expression": Whether this output of this is to be treated as an expression, or requires quoting. Default: false. "prompt": The text (an html string) for the placeholder and the tooltip. Default: determined from "types". "error": The text (an html string) to be displayed if an unacceptable choice is made. Default: determined from "types". "invalid": The text (an html string) indicating that the input is invalid. Default: "". "page": The name of the page in the Inspector to place the control on. The default is set by calling form.page, which in turn defaults to "Inputs". "group": The name of the group in the Inspector to place the control on. The default is set by calling form.group, which in turn defaults to "", which is an unnamed group at the top of the page. Note that only one of "alternatives" and "types" should be specified.
Returns:A new ScriptLabelledComboBox object.

controlInvalid(control, message)

Immediately aborts execution of the script and marks the specified control as invalid.
controlThe control that the error relates to.
messageA message to show with that control.

dataEntry(arguments)

Creates a new labelled dataEntry control. If setInputControls() is present, then then control will only appear if it is listed in the array given to setInputControls(), otherwise it will appear automatically.
argumentsA dictionary of arguments to pass to the function: "label": A label which appears adjacent to the control (a string). If you omit this then the button will be automatically labelled. "edit_label": A label which replaces "label" when data has been added to the control. If you omit this then the button will be automatically labelled. "name": The name of the control (a string). If not specified, one will be automatically created. "prompt": The text (an html string) for the tooltip. Default: none. "page": The name of the page in the Inspector to place the control on. The default is set by calling form.page, which in turn defaults to "Inputs". "group": The name of the group in the Inspector to place the control on. The default is set by calling form.group, which in turn defaults to "", which is an unnamed group at the top of the page.
Returns:A new ScriptLabelledDataEntry object.

datePicker(arguments)

Creates a new labelled control which allows the user to select a date. If setInputControls() is present, then then control will only appear if it is listed in the array given to setInputControls(), otherwise it will appear automatically.
argumentsA dictionary of arguments to pass to the function: "label": A label which appears adjacent to the control (a string). "name": The name of the control (a string). If not specified, one will be automatically created. "prompt": The text (an html string) for tooltip. Default: none. "page": The name of the page in the Inspector to place the control on. The default is set by calling form.page, which in turn defaults to "Inputs". "group": The name of the group in the Inspector to place the control on. The default is set by calling form.group, which in turn defaults to "", which is an unnamed group at the top of the page.
Returns:A new ScriptLabelledDatePicker object.

dropBox(arguments)

Creates a new labelled control to allow the user to drop input data dragged from elsewhere in the project.

May only be used in R Controls.

If setInputControls() is present, then then control will only appear if it is listed in the array given to setInputControls(), otherwise it will appear automatically.

"types" has the form of:

[Variable|Question|Table|RItem](:!*comma-separated-subtypes)?(:!*comma-separated-[hidden|filter|weight])

where the first part dictates the basic type, the second part modifies for subtypes, and the third further modifies for question tags. The second and third parts are optional and may be repeated as many times as desired.

argumentsA dictionary of arguments to pass to the function: "label": A label which appears adjacent to the control (a string). "name": The name of the control (a string). If not specified, one will be automatically created. "types": A list of allowed values (an array of strings). These may be 'Variable', 'Question' or 'Table'. "multi": A flag to indicate whether the control can accept more than one input. Default: false. "required": A flag indicating whether an input is required in order to be valid. Default: true. "min_inputs": The minimum number of inputs required. Default: if "required" then 1 otherwise 0. "max_inputs": The maximum number of inputs allowed. Default: no maximum. "height": The vertical size of the dropBox (in lines). Default: min(max_inputs, 4). "duplicates": A flag indicating whether the control permits the same input to appear twice. Default: false. "expression": Whether this output of this is to be treated as an expression, or requires quoting. Default: true. "prompt": The text (an html string) for the placeholder and the tooltip. Default: determined from "types". "error": The text (an html string) to be displayed if an unacceptable input is being dragged into the dropBox. Default: determined from "types". "invalid": The text (an html string) indicating that the input is invalid. Default: "". "page": The name of the page in the Inspector to place the control on. The default is set by calling form.page, which in turn defaults to "Inputs". "group": The name of the group in the Inspector to place the control on. The default is set by calling form.group, which in turn defaults to "", which is an unnamed group at the top of the page.
Returns:A new ScriptLabelledDropBox object.

newCheckBox(control_name, text)

Creates a new control to show a checkbox. The control will only appear if given back to the form via setInputControls() or setOutputControls().
control_nameA unique name for the control. It must not contain spaces or punctuation, nor begin with a number.
textThe text to show with the checkbox.
Returns:A new ScriptCheckBox object.

newColorPicker(control_name)

Creates a new control to allow the user to select a color. The control will only appear if given back to the form via setInputControls() or setOutputControls().
control_nameA unique name for the control. It must not contain spaces or punctuation, nor begin with a number.
Returns:A new ScriptColorPicker object.

newComboBox(control_name, alternatives)

Creates a new control to allow the user to select an item. The control will only appear if given back to the form via setInputControls() or setOutputControls().
control_nameA unique name for the control. It must not contain spaces or punctuation, nor begin with a number.
alternativesAn array of strings to show in the drop down.
Returns:A new ScriptComboBox object.

newDatePicker(control_name)

Creates a new control to allow the user to specify a date
control_nameA unique name for the control. It must not contain spaces or punctuation, nor begin with a number.
Returns:A new ScriptDatePicker object.

newLabel(text)

Creates a new control that shows a few words of text. The text will only appear if given back to the form via setInputControls() or setOutputControls().
textThe string to show.
Returns:A new ScriptLabel object.

newNumberBox(control_name)

Creates a new control to allow the user to enter a number. The control will only appear if given back to the form via setInputControls() or setOutputControls().
control_nameA unique name for the control. It must not contain spaces or punctuation, nor begin with a number.
Returns:A new ScriptNumberBox object.

newNumericUpDown(control_name)

Creates a new control to allow the user to enter a number. The control will only appear if given back to the form via setInputControls() or setOutputControls().
control_nameA unique name for the control. It must not contain spaces or punctuation, nor begin with a number.
Returns:A new ScriptNumericUpDown object.

newStatisticPicker(control_name)

Creates a new control to allow the user to select a statistic. See the ScriptStatisticPicker object for details. The control will only appear if given back to the form via setInputControls() or setOutputControls().
control_nameA unique name for the control. It must not contain spaces or punctuation, nor begin with a number.
Returns:A new ScriptStatisticPicker object.

newTextBox(control_name)

Creates a new control to allow the user to enter text. The control will only appear if given back to the form via setInputControls() or setOutputControls().
control_nameA unique name for the control. It must not contain spaces or punctuation, nor begin with a number.
Returns:A new ScriptTextBox object.

numericUpDown(arguments)

Creates a new labelled control to allow the user to enter a number. If setInputControls() is present, then then control will only appear if it is listed in the array given to setInputControls(), otherwise it will appear automatically.
argumentsA dictionary of arguments to pass to the function: "label": A label which appears adjacent to the control (a string). "name": The name of the control (a string). If not specified, one will be automatically created. "increment": The amount by which the number is raised or lowered when the up and down arrow buttons are pressed. Default is 1. "minimum": The minimum value for this number. Default is 0. "maximum": The maximum value for this number. Default is 100. "prompt": The text (an html string) for the tooltip. Default: none.
Returns:A new ScriptLabelledNumericUpDown object.

ruleNotApplicable(because)

Immediately aborts execution of the Rule because it is not applicable to the data it is being run on. Other Rules applied to the item will continue to run.
becauseText that will be embedded in a message such as "This Rule is invalid because XXXX.", where your text replaces XXXX.
Example:
form.ruleNotApplicable("need at least two non-empty cells to calculate standard deviation")

setHeading(heading, options)

Provides the text to be shown before any input controls when the user creates or edits the Rule. It should help the user understand the purpose of the input controls.
headingA string.
optionsAn optional dictionary of arguments to pass to the function: "page": The name of the page in the Inspector to place the control on. The default is set by calling form.page, which in turn defaults to "Inputs". "group": The name of the group in the Inspector to place the control on. The default is set by calling form.group, which in turn defaults to "", which is an unnamed group at the top of the page.
Example:
form.setHeading("Highlights cells with low n:");

setInputControls(controls)

Sets the list of controls that will appear in the form's top section. These are the main inputs to control what the Rule will do. For backwards compatibility, this method is also works on R Controls too but usage is discouraged.
controlsAn array of controls created by the other functions in this object.

setItemName(name)

Sets the name of the table/plot to which the rule is applied.
nameThe new name for the table/plot.
Example:
form.setItemName('some new name');

setOutputColor(color)

Provides the color to be shown next to this Rule when it is listed. Call this if your control is highlighting using just a single color.
colorA color, probably returned form a ScriptColorPicker object.
Example:
form.setOutputColor(colorPicker.requireValue());

setOutputColors(colors)

Provides the two colors to be shown next to this Rule when it is listed. Call this if your control is highlighting using a blend between two or three colors.
colorsAn array containing two or three colors.
Example:
form.setOutputColors([colorFromPicker.requireValue(), colorToPicker.requireValue()]);

setOutputControls(controls)

Sets the list of controls that will appear in the form's bottom section, after the label "Preview:". These controls are used to control the highlighting (if any) that the Rule will apply.
controlsAn array of controls created by the other functions in this object.

setSummary(summary, options)

Provides the text to be shown next to this Rule when it is listed. It should concisely describe what the script does.
summaryA string.
optionsAn optional dictionary of arguments to pass to the function: "page": The name of the page in the Inspector to place the control on. The default is set by calling form.page, which in turn defaults to "Inputs". "group": The name of the group in the Inspector to place the control on. The default is set by calling form.group, which in turn defaults to "", which is an unnamed group at the top of the page.
Example:
form.setSummary("Highlights cells with n less than "+minimumN);

setTranslation(name_en, name_override)

Override the name of one of the statistics that appears on this table/plot. This is equivalent to changing the Output Text in Table/Plot Options.
name_enEnglish text that is normally used.
name_overrideThe text to use instead of the original. If null the default text is restored.
Example:
form.setTranslation('Column n', 'col n'));

textBox(arguments)

Creates a new control to allow the user to enter text. If setInputControls() is present, then then control will only appear if it is listed in the array given to setInputControls(), otherwise it will appear automatically.
argumentsA dictionary of arguments to pass to the function: "label": A label which appears adjacent to the control (a string). "name": The name of the control (a string). If not specified, one will be automatically created. "type": The name of the type used to validate the text (can only be "number" at the moment). Default: no validation. "required": A flag indicating whether an input is required in order to be valid. Default: true. "expression": Whether this output of this is to be treated as an expression, or requires quoting. Default: false. "prompt": The text (an html string) for the placeholder and the tooltip. Default: based on "type". "error": The text (an html string) to be displayed if an unacceptable input is given. Default: based on "type". "invalid": The text (an html string) indicating that the input is invalid. Default: "". "page": The name of the page in the Inspector to place the control on. The default is set by calling form.page, which in turn defaults to "Inputs". "group": The name of the group in the Inspector to place the control on. The default is set by calling form.group, which in turn defaults to "", which is an unnamed group at the top of the page.
Returns:A new ScriptTextBox object.

type

Returns the name we use to refer to this class in the documentation.

vertical

A flag indicating whether the layout should be done vertically or not.