RControlForm
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.
| arguments | A 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.
| arguments | A 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.
| arguments | A 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". "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. |
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.
| arguments | A 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. "large_data_error": The error message text to be shown to the user if they attempt to include too many rows or columns in this data entry field, which defaults to "You may enter a table that is at most {0} x {1}. If you need to enter more data then upload it as a CSV file." if not set. |
| 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.
| arguments | A 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.
| arguments | A 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. |
group(arguments)
Sets the default group for controls from this point onwards. This default can be overridden when creating a control
| arguments | A dictionary of arguments to pass to the function: "label": The name of the group in the Inspector to place subsequent controls on. The default is "", which is an un-named group "expanded": A flag indicating whether the group should be expanded, a missing value results in the default heuristic |
| Example: | form.group({label: "Advanced", expanded: false});
|
listBox(arguments)
Creates a new labelled control to allow the user to select one or more items from a list.
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.
| arguments | A 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 list box. "names": An array of strings corresponding to the alternatives which should be used as the actual output to R. "multiSelection": A flag to indicate whether the control should allow multiple selections. Default: false. "nItemsVisible": The maximum height of the control (in lines). Default: 5. "initialValues": A list of values corresponding to names if present or alternatives that is used to preset the selection. Default: none. "required": A flag indicating whether an input is required in order to be valid. Default: true. "prompt": The text (an html string) for the tooltip. Default: none. "error": The text (an html string) to be displayed if the control is required and not entered. Default: [Label] is required. "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 if both "alternatives" and "names" are specified they should be the same length. |
| Returns: | A new ScriptLabelledListBox 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.
| arguments | A 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. |
page(label)
Sets the default page for controls from this point onwards. This default can be overridden when creating a control
| label | The name of the page in the Inspector to place subsequent controls on. The default is "Inputs" |
| Example: | |
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.
| heading | A string. |
| options | An 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.
| controls | An array of controls created by the other functions in this object. |
setObjectInspectorTitle(title, title_plural)
Sets the title used by the Object Inspector to describe this item. eg: Visualization, Calculation etc. If not set, the Output Type of the item is used to decide how to describe it
| title | The name used to describe the object in the title bar of the Object Inspector. |
| title_plural | The name used to describe more than one of the item. If omitted, the singular name will have an 's' added to the end |
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.
| summary | A string. |
| options | An 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);
|
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.
| arguments | A 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.