input (HSL reserved word)

Summary

input is a reserved word. It is used in HSL scripts to define a variable as an argument that is required to run the script.

Details

input can be used to define control constructs, data types, and Boolean states in Shogun Post scripts. Do not use input as a variable name in your script commands.

Inputs are commonly used to create parameters for a script, which are visible in the Pipelines panel. Input statements set the default value of a variable, and some conditions that must be adhered to, such as range. The variable named in the input statement must be declared in the script. The input statement also allows you to control the way in which the parameter is visible and specified in the Pipelines panel.

Command syntax

input variableName defaultValue [-advanced] [-allowNonDiscrete] [-color] [-description string][-discrete value1 value2 ..] [-file Filter string] [-folder] [-macro listItem1 script1 listItem2 script2] [-module] [-namedDiscrete listItem1 value1 listItem2 value2 ..] [-range minNumber maxNumber]

Arguments

Name	Type	Required	Comments
`variableName`	string	Yes	Variable name declared in the script, must begin with $.
`defaultValue`	Must match type of variableName	Yes	Default value that the variable will take, if not given as an argument when calling the script.

Flags

Name	Flag arguments	Argument type	Exclusive to	Comments
`advanced`	0		–	Makes the parameter for the script advanced, rather than always visible in the Pipelines panel.
`allowNonDiscrete`	0			Should only be used when the discrete or namedDiscrete flag is present. When using the discrete flag, this allows the input parameter in the Pipelines panel to be edited as well being selected from the discrete picklist
`color*`	0		file, folder, module, discrete, namedDiscrete	Adds a color picker to the pipeline parameter. The associated variable must be type vector.
`description`	11	string	–	Adds a description that is visible in the Pipelines panel.
`discrete*`	Many	string	color, file, folder, module, namedDiscrete	Sets a picklist for the value which is visible in the Pipelines panel.
`file*`	1	string	color, folder, module, discrete, namedDiscrete	Generates a file icon in the parameter in the Pipeline panel enabling browsing to a file. The fileFilter sets the filter in the file browser. The associated variable must be type string.
`folder*`	1	string	color, file, module, discrete, namedDiscrete	As with file (above), except string returned is a path to a directory rather than a file.
`macro`	Many pairs	string	–	Enables the input to be returned from a script. Pairs of arguments are specified as strings. The first string is a picklist item visible in the Pipelines panel; the following string is a script name that will return the input value.
`module*`	0		color, file, folder, discrete, namedDiscrete	Enables you to pick a module from the scene to use in a string variable.
`namedDiscrete*`	Many pairs	string, variable type	color, file, folder, module, discrete	Enables you to create a picklist of type string, which has corresponding values, the same type as the variable type.
`range`	2	int or float		Enables you to set a range for integer or float variables. May only be used when the variable type is numeric.

* This flag changes the way the variable's input is entered in the GUI and therefore may not be combined with any of the other flags marked with an asterisk * in the above table. You can use these flags only when the variable type is compatible, for example, you cannot use -folder with an int variable. However, you can use color, discrete, or namedDiscrete for a color variable.

Return value

void

Example

//  -macro
//  Lets you specify pairs of arguments as strings after the -macro.
//  First string is the value in the picklist in the operation.
//  parameters. //  Second string is the script to run which will
//  return a value into the input variable.
//  IMPORTANT all return variables from scripts must be the
//  same variable type, in this case strings.
//  Otherwise it might crash Shogun Post.
string $GetDayOrMonthAsString;
input $GetDayOrMonthAsString "" -macro "Day" "GetDayOfWeek" "Month" "GetMonth";
print $GetDayOrMonthAsString;
//  -module
//  This allows you to pick a module from the scene to use in a
//  string variable.  If there is a blank scene there will be
//  nothing to pick associated variable must be type string
string $PickModuleName;
input $PickModuleName "" -module;
print $PickModuleName;
//  -discrete -allowNonDiscrete
//  Example 1: lets you create a picklist using the -discrete switch
//  NOTE: The default value for the input has to be 
//  included in the list of discrete inputs
string $PickTextToPrint;
input $PickTextToPrint "Text1" -discrete "Text1" "Text2";
print $PickTextToPrint;
//  Example 2: allows you to edit the text as well as use the 
//  picklist using the -allowNonDiscrete switch
//  NOTE: It's helpful, but not essential, to add "" to the picklist,
//  so that it is obvious you can leave blank or enter text
string $PickOrTypeTextToPrint;
input $PickOrTypeTextToPrint "Text3" -discrete "" "Text3" "Text4" -allowNonDiscrete;
print $PickOrTypeTextToPrint;
//  -namedDiscrete
//  Specify pairs of strings, first string: Picklist value, 
//  second string: Value to set variable to. Allows you to create 
//  a picklist, that will convert to another value of the same 
//  variable type. Picking "One" will set the variable to "1", 
//  which could be easily converted to an integer.
//  IMPORTANT: The default value must be a valid entry from the
//   variable value, and not the picklist value.
string $GetNumberFromWord;
input $GetNumberFromWord "1" -namedDiscrete "One" "1" "Two" "2" "Three" "3";
print $GetNumberFromWord;
//  -advanced
//  This will make the parameter for the script an advanced 
//  one rather than always visible in the pipelines panel.
//  -color
//  This will add a color picker to the pipeline parameter
//  associated variable must be type vector
//  -description
//  This will add a description which will be visible 
//  in the pipelines panel.
//  -file
//  This generates a file icon in the parameter in the pipeline
//  panel allowing browsing to a path associated variable must be 
//  type string
string $Filename;
  input $Filename "" -file "ShogunPost File (.hdf)|.hdf";  
print $Filename;
//  -folder
//  As with file, except string returned is a path to a 
//  directory rather than a file.
//  -range
//  Allows a range to be set for integer or float variables
float $EnterValInRange;
input $EnterValInRange 10.000 -range -50.000 50.000 -description "Enter value between -50.000 and 50.000";
print $EnterValInRange;