Developing Longview Forms

Longview Forms technology was created to enable Developers to design consistent forms across the Longview product without a reliance on HTML. You can create dynamic forms that allow users to provide information for your Longview App. You can use the information users enter into your form in variables used in a procedure. You can call a form from a procedure using the SHOW FORM command. For more information on calling your form, see “Show Form”. For information on creating a dynamic form, see Designing dynamic forms.

A Longview Form document (.lvfrm) defines the layout, format, and controls to display for a form and contains form functions. As a general rule, the order of functions specified in your form document is the order in which fields appear on the form.

For information on guidelines and best practices for designing Longview Forms, see Understanding guidelines and considerations and Reviewing best practices.

Note: You can specify optional parameters in any order for forms functions.

Creating a Longview Form consists of the following steps:

You can use the following functions in a Longview Form document:

The following graphic shows a form created using a Longview Form document.

To view the code used to create this form, see Sample Longview Form and supporting procedures.

Understanding guidelines and considerations

Review the following guidelines and considerations before creating Longview Forms:

• Parameters
• Global Variables
• Layout
• UseListDelimiter command

Parameters

Longview Forms functions contain keyword-value pairs for optional parameters, such as “Title:title”. This syntax enables the system to identify the keyword and pass on the value without requiring keyword-value pairs to be in a particular order. For all optional parameters for Longview Forms functions, you can specify the optional parameters in any order.

Though not recommended, in some cases you may want to include a blank label for a control. For other Longview Application Framework commands and functions, you must use two double quotation marks ("") for blanks; however, to include a blank label for Longview Form functions, use a space enclosed in double quotation marks (" ").

Global Variables

For Longview Forms, you can use the following global variables for which you can set values:

• LVG_FormValid — this variable returns custom validation logic.
• LVG_FormMessage — this variable returns a customizable message to a user after a form validates.

For more information, see Working with global variables.

Layout

Longview Forms contain two columns: the left-side label column and the right-side control column. The width of the left-side label column is dictated by the longest label included in any of the functions specified in your Longview Form document. The right-side control column uses the remaining available width of the form, as specified by the Window function, if included. If you do not specify the Width parameter of the Window function, or you do not include the Window function in your Longview Form document, the width of the form is 550 pixels.

Though not recommended, in some cases you may use a variable for the label parameter, which may cause the right-side control column of your form to be unreadable by users. Always test the way your form displays, including testing possible variable values that could be passed in by your users. For more information, see Reviewing best practices.

UseListDelimiter command

The ComboBox and RadioGroup forms functions allow STRINGLIST variables that use a delimiter to separate values. Depending on your system and the delimiter used, you may need to use the UseListDelimiter command to convert at sign ( @ ) delimiters to pipes ( | ) or vice versa.

Reviewing best practices

Longview strongly recommends testing your Longview Form before you publish your Longview App to users. Testing is considered complete after you have tested the following, if applicable to your form:

• The form loads with all controls displayed as desired and no error messages.
• The form loads without any initial warnings displayed to the user.
• The form loads with target values resolved and displayed as expected.
• The form loads with the expected available values for prompt controls such as the Symbol Selector and Symbol Spec Selector.
• Any specified variables populate as expected after controls are completed by the user.
• Any specified variables that are referenced in subsequent procedures are set before being referenced.
• Any specified buttons become available as expected based on the Validate keyword, if included.
• Any specified OnChange procedures that modify controls do so as expected.

Designing dynamic forms

As a Developer, you can create simple forms that use information entered by users to update your Longview Apps; however, you can also create complex and dynamic forms. The level of complexity of your form is up to you. A dynamic form is one that updates as the user completes the fields. For example, you could write your own validation procedure to display a message to the user if they do not include an at sign ( @ ) when prompted to type their email address, or you could write an OnChange procedure to modify the selections in a combo box based on the selection from another control.

To view sample code, see Sample Longview Form and supporting procedures.

Using the OnChange keyword

Many Longview Forms functions allow you to use the optional OnChange keyword. You can use the OnChange keyword to specify a procedure to run after the system detects a change - this lets you add your own validation and/or create a form that updates dynamically as the user fills out the form. OnChange procedures trigger immediately after the user modifies the control such as typing in a text box or selecting a radio button.

Note: OnChange procedures cannot update the available symbols in the Symbol Selector control for the SymbolSelector and SymbolSpecSelector functions.

Using the OnClick keyword

The Button function provides you with the optional OnClick keyword. You can use the OnClick keyword to specify a procedure to run after the user clicks the button. You could, for example, write an OnClick procedure to kick off a calculation or you could write an OnClick procedure to add a new symbol to the system using the values for the variables that the user entered in your form. For more information, see Button.

Note: Target variables are populated with the values entered or selected by the user when they complete the form. If you include a "Cancel" button and want target variables reset to default values, it is up to you to write an appropriate OnClick procedure that reverts the target variables.

Defining properties

You can use the functions in this section to define the properties of your form:

• Button
• Window

Button

Use this function to define the buttons included on your form. Buttons appear on the button bar at the bottom of the form. To add more than one button, you must include more than one Button function. The order in which you specify Button functions in your form document is the order in which buttons appear from left to right on your form. Optionally, you can specify a procedure to run after the user clicks the button.

Note: If you do not include the Button function in your form document, the form includes a Close button, by default, that is always available.

Syntax:

where:

• Value is the value returned to the LVS_BUTTONCLICKED system variable when the user clicks the button. For more information, see “Using the LVS_BUTTONCLICKED system variable”.
• TextValue is optional and is the text to display on the button. If you do not specify TextValue, the content specified for Value displays as the button text.
• Validate is optional and can be one of the following:
• Procedure is optional and is the name of the OnClick procedure to run after the user clicks the button. To close the form, include the SHOW RETURN command in your OnClick procedure. If you do not specify an OnClick procedure, the system automatically executes the SHOW RETURN command when the user clicks the button, and closes the form. Include the extension and the file path if the file is not located in the default path. The default path is the path specified in the <rootpath> tag of the .lvapp file. If no root path is specified, the system assumes the root path is the applications folder in the working directory.

For more information, see “Using the OnClick keyword”.

Syntax Example 1

Syntax Example 2

Window

Use this function to specify the title, width, and height of the form window. All parameters of the Window function are optional; however, if you include the Window function in your form document, you must specify at least one parameter.

Syntax:

Note: You must specify at least one of Title, Width, or Height if you include the Window function in your form document.

where:

• Title is optional and is the string used as the title for the form window. Enclose this parameter in double quotation marks (""), including the Title keyword. If you do not specify Title, the form opens with the Longview App description as the title of the form window.
• Width is optional and specifies the width, in pixels or as a percentage, of the form window. Indicate a percentage with a percent (%) sign. If you do not use a percent sign, the parameter is assumed to be in pixels. If you do not specify Width, the default width of the form is 450 pixels.
• Height is optional and specifies the height, in pixels or as a percentage, of the form window. Indicate a percentage with a percent (%) sign. If you do not use a percent sign, the parameter is assumed to be in pixels. Review the following table for the expected behavior of form height:

  If…	The system…
  you specify Height as a value too small for the user to interact with the form...	overrides your specification for Height and imposes a minimum height of 100 pixels so that the button bar displays.
  you specify Height as a value too large for the maximum height available on the user’s screen...	overrides your specification for Height and displays the form with the maximum height available on the user’s screen and includes a vertical scroll bar on the right-hand side of the form.

Syntax Example 1

Syntax Example 2

Syntax Example 3

Defining formats

You can use the functions in this section to define formats for your form:

• DateFormat

DateFormat

Use this function to specify the format in which to return the value of a date that a user enters into a control specified by the DatePicker function. You may want to, for example, kick off a rollover process based on the month the user selects. To do so, you must know which number in the selected date refers to the day, month, and year. If you do not include the DateFormat function in your form document, date values are returned in the ISO format YYYY-MM-DD. For more information, see DatePicker.

Note: Dates display to the user in the format specified by their operating system’s regional settings.

Syntax:

where:

• Format specifies the format in which the value of a date input is returned, enclosed in double quotation marks (“”), and can be one of the following:

Note: The default format if you do not include the DateFormat function in your form document is the ISO format YYYY-MM-DD.

Syntax Example 1

Displaying information

You can use the functions in this section to display information on your form:

• Heading

Heading

Use this function to include text that spans the label column and the control column of the form. You can use the Heading function to include a heading with larger text or, for example, to provide instructions to users in the default text size and style. You can also use the Heading function to break your form into sections. For more information on form layout, see Layout.

Note: The CheckBox field also appears in the above graphic as an example of a heading spanning the full width of a form.

Syntax:

where:

• Text is the text to display, enclosed in double quotation marks (""). To include a blank row in your form, use the Separator function. For more information, see Separator.
• Style is optional and is the appearance of the text. This parameter can be one of the following values:

  Value	Description
  Title	Displays the specified text in Tahoma 16px Bold #FF336699.
  Subtitle	Displays the specified text in Tahoma 11px Bold Black.
  Normal	Displays the specified text in Tahoma 11px Black. This is the default if you do not specify Style.

Syntax Example 1

Syntax Example 2

Syntax Example 3

Adding static controls

You can use the functions in this section to add static controls to your form:

• Number
• Separator
• Text

Number

Use this function to display a labelled number to users. You can use the Number function to display a static number or to display a number based on another input on your form. For example, you could display a new employee’s number of vacation days remaining in a calendar year based on the employee’s start date. For more information, see Designing dynamic forms.

You can specify whether a number displays left- or right-aligned on the form, and you can also specify whether to display numbers using the user’s regional settings for thousand separators.

Syntax:

where:

• Label is the label for the field, enclosed in double quotation marks ("").
• Value is a number or the name of the NUM variable created in the supporting procedure for this Number function.
• Align is optional and specifies where to display the number on the form. Use LEFT to display the number on the left-hand side of the control column. Use RIGHT to display the number on the right-hand side of the control column. If you do not specify Align, numbers display on the right-hand side of the control column by default.
• ThousandsSeparator is optional and specifies whether to display numbers using the user’s region-specific character to separate thousands. Use ON to display numbers with a thousand separator. Use OFF to display numbers without a thousand separator. If you do not specify ThousandsSeparator, numbers display without a thousand separator character.

Syntax Example 1

Syntax Example 2

Syntax Example 3

Separator

Use this function to include a separator in your form. You can use the Separator function to break up areas on your form with blank space or a line, or you can optionally include a text label to divide your form into separate sections.

Syntax:

where:

• Style is one of the following:

  Value	Description
  BLANK	Use this value to insert a blank horizontal separator that spans the width of the form.
  LINE	Use this value to insert a solid horizontal line that spans the width of the form.

• TextValue is optional and is the left-aligned text to display as the label for the separator. Enclose this value in double quotation marks (""), including the Text keyword.

Syntax Example 1

Syntax Example 2

Text

Use this function to display labelled text to users. You can use the Text function to display static text or to display text based on another input on your form. For example, you could display a new employee’s manager based on their role. For more information, see “Designing dynamic forms”.

Syntax:

where:

• Label is the label for the field, enclosed in double quotation marks ("").
• Value is a string or the name of the STRING variable created in the supporting procedure for this Text function.

Syntax Example 1

Syntax Example 2

Adding interactive controls

You can use the functions in this section to add input controls to your form:

• DatePicker
• FormulaBuilder
• NumberBox
• TextBox

DatePicker

Use this function to add a date picker to your form. Users can type or select a date that is input into a specified target variable. Dates display to the user in the format specified by their operating system’s regional settings and users are expected to type dates in their regional preference format. Optionally, you can specify a procedure to run after the date is input. You can also optionally restrict the range of dates the user is allowed to input.

Note: Date values are returned in the format specified by the DateFormat function. If you have not included the DateFormat function in your form document, date values are returned in the default ISO format YYYY-MM-DD. For more information, see DateFormat.

Syntax:

where:

• Label is the label for the field, enclosed in double quotation marks ("").
• Target is the name of the STRING variable created in the supporting procedure for this DatePicker function.
• Procedure is optional and is the name of the OnChange procedure to run after the user changes the field. Always include the extension, and include the file path if the file is not located in the default path. The default path is the path specified in the <rootpath> tag of the .lvapp file. If no root path is specified, the system assumes the root path is the applications folder in the working directory.

  For more information, see Using the OnChange keyword.

• Date is optional and is the date range for the date picker, defined using the Min and Max keywords. Use the format specified by the DateFormat function, otherwise use the default format which is the ISO format YYYY-MM-DD. You do not have to specify both Min and Max; you may include only the Min keyword value pair to restrict the minimum allowed date or you may include only the Max keyword value pair to restrict the maximum allowed date.
• Required is optional and can be one of the following:

  Value	Description
  TRUE	Use this value to include a red asterisk beside the field label indicating to the user this field is required. This value ensures any buttons specified in the form document that include the optional Validate:TRUE parameter are unavailable until fields marked as required are completed by the user. For more information, see Button.
  FALSE	Use this value to leave the field label without an asterisk. This is  the default if you do not specify Required.

Syntax Example 1

FormulaBuilder

Use this function to add a formula builder to your form. Users can type a formula or select symbols and operators for a formula using interactive controls. The formula specified can be input into a target variable. Numbers are displayed and should be input based on the  user's operating system regional format. Optionally, you can specify a procedure to run after the formula is input. You can also optionally restrict the symbols that the user is allowed to input.

Syntax:

where:

• Label is the label for the field, enclosed in double quotation marks ("").
• Target is the name of the STRING variable created in the supporting procedure for this FormulaBuilder function.
• DimensionName is the dimension containing the symbols to include in the Formula Builder.
• SymbolSpecifications is optional and is the level of symbols to display in the Formula Builder hierarchy, in relation to the specified symbol, for example, SymbolName### or SymbolName#99.
• Procedure is optional and is the name of the OnChange procedure to run after the user changes the field. Always include the extension, and include the file path if the file is not located in the default path. The default path is the path specified in the <rootpath> tag of the .lvapp file. If no root path is specified, the system assumes the root path is the applications folder in the working directory.
• Required is optional and can be one of the following:

  Value	Description
  TRUE	Use this value to include a red asterisk beside the field label indicating to the user this field is required. This value ensures any buttons specified in the form document that include the optional Validate:TRUE parameter are unavailable until fields marked as required are completed by the user.
  FALSE	Use this value to leave the field label without an asterisk. This is the default if you do not specify Required.

Note: If the dimension selected is the time period dimension, floating time periods will be included in the symbol specifications.

Syntax example:

NumberBox

Use this function to add an input box for numbers to your form. Users can type a number that is input into a specified target variable. Users can also enter the plus sign ( + ), minus sign ( - ), dot ( . ), and comma ( , ), and can use parentheses to indicate negative numbers, such as (2). Numbers user enter use the format specified by their operating system’s regional settings, including their region-specific character for thousand separator, if you include the optional thousands separator keyword. Optionally, you can specify a procedure to run after the number is input. You can also optionally restrict the range of numbers the user can input or restrict the number of allowed decimals and specify whether numbers display left- or rightaligned.

Syntax:

where:

• Label is the label for the field, enclosed in double quotation marks ("").
• Target is the name of the NUM variable created in the supporting procedure for this NumberBox function.
• Procedure is optional and is the name of the OnChange procedure to run after the user changes the field. Always include the extension, and include the file path if the file is not located in the default path. The default path is the path specified in the <rootpath> tag of the .lvapp file. If no root path is specified, the system assumes the root path is the applications folder in the working directory. For more information, see Using the OnChange keyword.
• Procedure is optional and is the name of the OnChange procedure to run after the user changes the field. Always include the extension, and include the file path if the file is not located in the default path. The default path is the path specified in the <rootpath> tag of the .lvapp file. If no root path is specified, the system assumes the root path is the applications folder in the working directory. For more information, see Using the OnChange keyword.
• Number is optional and is the number range for the number box, defined using the Min and Max keywords. You do not have to specify both Min and Max; you may include only the Min keyword value pair to restrict the minimum allowed number or you can include only the Max keyword value pair to restrict the maximum allowed number.
• Decimals is optional and specifies the number, from 0-9, of digits allowed after the decimal character. Use 0 to restrict the user from typing any numbers after the decimal character. The default value is 9 if you do not specify Decimals.
• Align is optional and specifies where to display the number within the number box. Use LEFT to display the number on the left-hand side of the number box. Use RIGHT to display the number on the right-hand side of the number box. If you do not specify Align, numbers display on the right-hand side of the number box by default.
• ThousandsSeparator is optional and specifies whether to display numbers using the user’s region-specific character to separate thousands. Use ON to display numbers with a thousand separator. Use OFF to display numbers without a thousand separator. If you do not specify ThousandsSeparator, numbers display without a thousand separator character.
• Required is optional and can be one of the following:

  Value	Description
  TRUE	Use this value to include a red asterisk beside the field label indicating to the user this field is required. This value ensures any buttons specified in the form document that include the optional Validate:TRUE parameter are unavailable until fields marked as required are completed by the user. For more information, see Button
  FALSE	Use this value to leave the field label without an asterisk. This is the default if you do not specify Required.

Syntax Example 1

Syntax Example 2

Syntax Example 3

TextBox

Use this function to display labelled text to users. You can use the Text function to display static text or to display text based on another input on your form. For example, you could display a new employee’s manager based on their role. For more information, see Designing dynamic forms.

Syntax:

where:

• Label is the label for the field, enclosed in double quotation marks ("").
• Value is a string or the name of the STRING variable created in the supporting procedure for this Text function.

Syntax Example 1

Syntax Example 2

Adding selection controls

You can use the functions in this section to add selection controls to your form:

• CheckBox
• ComboBox
• RadioGroup

CheckBox

Use this function to add a check box to your form. To add more than one check box, you must include more than one CheckBox function. Optionally, you can specify a procedure to run after the check box is selected.

Syntax:

where:

• Label is the label for the field, enclosed in double quotation marks ("").
• Target is the name of the STRING or NUM variable created in the supporting procedure for this CheckBox function. STRING variables return values of either TRUE or FALSE; NUM variables return values of either 1 or 0.
• Procedure is optional and is the name of the OnChange procedure to run after the user changes the field. Always include the extension, and include the file path if the file is not located in the default path. The default path is the path specified in the <rootpath> tag of the .lvapp file. If no root path is specified, the system assumes the root path is the applications folder in the working directory. For more information, see Using the OnChange keyword.

Syntax Example 1

Syntax Example 2

ComboBox

Use this function to add a non-editable combo box (also referred to as drop-down list) to your form. The order in which you specify the combo box values in this function is the order in which the options appear in the list. Optionally, you can specify a procedure to run after the user selects an option. Combo boxes are always treated as required fields, and a red asterisk displays beside combo box labels indicating to the user that the field is required.

Note: You may need to use the UseListDelimiter command to convert the delimiter used between values. For more information, see UseListDelimiter.

Syntax:

where:

• Label is the label for the field, enclosed in double quotation marks ("").
• Target is the name of the STRING variable created in the supporting procedure for this ComboBox function. If Target contains a valid value, it is selected when the forms displays. If Target contains an invalid value or no value, the form displays with nothing selected.
• Values is a pipe ( | ) delimited string, or the name of the STRINGLIST, NUMLIST, or RANGE variable created in the supporting procedure for this ComboBox function to display as the drop-down options. Enclose values in double quotation marks ("").

  Note: Blank values are not valid.

• TextValues is optional, is the text to display for each drop-down option, and is a pipe ( | ) delimited string, or the name of a STRINGLIST, NUMLIST, or RANGE variable in the supporting procedure. If you do not specify TextValue, the content specified for Values displays as the text for the options in the list.
• Procedure is optional and is the name of the OnChange procedure to run after the user changes the field. Always include the extension, and include the file path if the file is not located in the default path. The default path is the path specified in the <rootpath> tag of the .lvapp file. If no root path is specified, the system assumes the root path is the applications folder in the working directory. For more information, see Using the OnChange keyword.

Syntax Example 1

Syntax Example 2

RadioGroup

Use this function to add a group of radio buttons to your form. The order in which you specify the radio values in this function is the order in which the buttons appear from top to bottom on your form. When the form displays for the first time, no radio button is selected by default, unless you set the target variable. Radio groups are always treated as required fields, and a red asterisk displays beside radio group labels indicating to the user that the field is required.

Note: You may need to use the UseListDelimiter command to convert the delimiter used between values. For more information, see UseListDelimiter.

Syntax:

where:

• Label is the label for the field, enclosed in double quotation marks ("").
• Target is the name of the STRING variable created in the supporting procedure for this RadioGroup function.
• Values is a pipe ( | ) delimited string, or the name of the STRINGLIST, NUMLIST, or RANGE variable created in the supporting procedure for this RadioGroup function to display as the button options. Enclose values in double quotation marks ("").
• TextValues is optional, is the text to display for each button, and is a pipe ( | ) delimited string, or the name of the STRINGLIST, NUMLIST, or RANGE variable created in the supporting procedure for this RadioGroup function. If you do not specify TextValue, the content specified for values displays as the radio button text.
• Procedure is optional and is the name of the OnChange procedure to run after the user changes the field. Always include the extension, and include the file path if the file is not located in the default path. The default path is the path specified in the <rootpath> tag of the .lvapp file. If no root path is specified, the system assumes the root path is the applications folder in the working directory. For more information, see Using the OnChange keyword.

Syntax Example 1

Syntax Example 2

Adding prompt controls

You can use the functions in this section to add prompt controls to your form:

• FileChooser
• ScheduleSymbolSelector
• SymbolSelector
• SymbolSpecSelector

FileChooser

Use this function to prompt users to select a file for your form. Optionally, you can specify a procedure to run after the file is selected. You can also optionally specify the types of files allowed and the button options for the prompt that opens.

Syntax:

where:

• Label is the label for the field, enclosed in double quotation marks ("").
• Target is the name of the STRING variable created in the supporting procedure for this FileChooser function.
• FileRestrictions is optional and is a list of the suggested file type and extension pairs for the user to select, enclosed in double quotation marks(""). Separate each file type and extension with a pipe ( | ).

  Note: If you want to allow all file types, omit the FileRestrictions parameter, or use "FileRestrictions:All Files|*.*".

• BrowseType is optional and can be Open or Save. Open or Save As appears as the title for the browse dialog that opens when users click the folder icon in the file chooser, and Open or Save appears as the button text option in the browse dialog.
• Path is optional and is the default path selected for the browse dialog, enclosed in double quotation marks.
• Procedure is optional and is the name of the OnChange procedure to run after the user changes the field. Always include the extension, and include the file path if the file is not located in the default path. The default path is the path specified in the <rootpath> tag of the .lvapp file. If no root path is specified, the system assumes the root path is the applications folder in the working directory. For more information, see Using the OnChange keyword.
• Required is optional and can be one of the following:

  Option	Description
  TRUE	Use this value to include a red asterisk beside the field label indicating to the user this field is required. This value ensures any buttons specified in the form document that include the optional Validate:TRUE parameter are unavailable until fields marked as required are completed by the user. For more information, see Button.
  FALSE	Use this value to leave the field label without an asterisk. This is the default if you do not specify Required.

Syntax Example 1

ScheduleSymbolSelector

Use this function to add a Schedule Symbol Selector to your form. Users can select one or more symbols from the Schedule Symbol Selector for a specified schedule dimension. Optionally, you can specify a procedure to run after the symbol is selected.

Note: OnChange procedures triggered from other functions cannot update the Schedule Symbol Selector control.

Syntax:

where:

• Label is the label for the field, enclosed in double quotation marks ("").
• Target is the name of the STRING, STRING[ ], or RANGE variable created in the supporting procedure for this ScheduleSymbolSelector function.
• ScheduleName is the name of the schedule the ScheduleSymbolSelector will use.
• DimensionName is the schedule dimension containing the symbols to include in the Schedule Symbol Selector.
• AllowMultiple is optional and specifies whether users can select multiple symbols and can have a value of TRUE or FALSE. The default if you do not specify AllowMultiple is FALSE.
• Procedure is optional and is the name of the OnChange procedure to run after the user changes the field. Always include the extension, and include the file path if the file is not located in the default path. The default path is the path specified in the <rootpath> tag of the .lvapp file. If no root path is specified, the system assumes the root path is the applications folder in the working directory. For more information, see “Using the OnChange keyword”.
• Required is optional and can be one of the following:

  Value	Description
  TRUE	Use this value to include a red asterisk beside the field indicating to the user this field is required. This value ensures any buttons specified in the form document that include the optional Validate:TRUE parameter are unavailable until fields marked as required are completed by the user. For more information, see Button.
  FALSE	Use this value to leave the field label without an asterisk. This is the default if you do not specify Required

Syntax example:

SymbolSelector

Use this function to add a Symbol Selector to your form. Users can select one or more symbols from the Symbol Selector for a specified dimension. Optionally, you can specify a procedure to run after the symbol is selected. You can also optionally specify a symbol specification, up to two attribute filters, and the allowable symbol types.

Note: OnChange procedures triggered from other functions cannot update the Symbol Selector control.

Syntax:

where:

• Label is the label for the field, enclosed in double quotation marks ("").
• Target is the name of the STRING, STRING[ ], or RANGE variable created in the supporting procedure for this SymbolSelector function.
• DimensionName is the dimension containing the symbols to include in the Symbol Selector.
• SymbolSpecifications is optional and is the level of symbols to display in the Symbol Selector hierarchy, in relation to the specified symbol, for example, SymbolName### or SymbolName#99.
• AllowLeaf is optional and specifies whether users can select leaf symbols and can have a value of TRUE or FALSE. The default if you do not specify AllowLeaf is FALSE.
• AllowParent is optional and specifies whether users can select parent symbols and can have a value of TRUE or FALSE. The default if you do not specify AllowParent is FALSE.
• AllowReadOnly is optional and specifies whether users can select read-only symbols and can have a value of TRUE or FALSE. The default if you do not specify AllowReadOnly is FALSE.
• AllowMultiple is optional and specifies whether users can select multiple symbols and can have a value of TRUE or FALSE. The default if you do not specify AllowMultiple is FALSE.
• AttributeFilters is optional can be up to two attribute filters linked by AND or OR, enclosed in double quotations marks, using the syntax:

  FilterType{AttrName{Operation{Expression

  where:

  Value	Description
  FilterType	specifies the method to use to search the hierarchy for symbols matching the filter criteria and can be one of ALL, PARENT, LEAF, or ROOT. If you specify two attribute filters, FilterType must be the same for both filters.
  AttrName	is the name of an attribute.
  Operation	can be EQ for exactly equal to or NE for not equal to.
  Expression	is a character string. If the expression contains spaces, enclose the expression in double quotation marks preceded by a backslash (\"expression with spaces\"). If the expression is a list, separate multiple items with a pipe ( | ). For non-list attributes, the filter behaves as follows: Attribute EQ Expression — Matches only if the attribute is an exact match of the expression. Attribute NE Expression — Matches if the attribute is not an exact match of the expression. For list attributes, the filter behaves as follows: Attribute EQ Expression — Matches if the attribute is an exact match of the expression, or is a list of values, any one of which exactly matches the expression. Attribute NE Expression — Matches if the attribute is empty or a list of values, none of which exactly matches the expression.

  If you specify two attribute filters, enclose each filter in parentheses, for example "(attributefilter1) AND (attributefilter2)".

• Procedure is optional and is the name of the OnChange procedure to run after the user changes the field. Always include the extension, and include the file path if the file is not located in the default path. The default path is the path specified in the <rootpath> tag of the .lvapp file. If no root path is specified, the system assumes the root path is the applications folder in the working directory. For more information, see Using the OnChange keyword.
• Required is optional and can be one of the following:

  Value	Description
  TRUE	Use this value to include a red asterisk beside the field label indicating to the user this field is required. This value ensures any buttons specified in the form document that include the optional Validate:TRUE parameter are unavailable until fields marked as required are completed by the user. For more information, see Button.
  FALSE	Use this value to leave the field label without an asterisk. This is the default if you do not specify Required.

Syntax Example 1

Syntax Example 2

SymbolSpecSelector

Use this function to add a Symbol Spec Selector to your form. The Symbol Spec Selector prompts users to select a symbol from the Symbol Selector, to select one of All, Leaf, Parent, or Root and Parent for the selected symbol, and to specify the number of levels down (froms 0 to 99) for the specified symbol. Optionally, you can specify a procedure to run after the symbol is selected. You can also optionally specify a symbol specification, up to two attribute filters, and the allowable symbol types.

Note: OnChange procedures triggered from other functions cannot update the Symbol Selector control.

Syntax:

where:

• Label is the label for the field, enclosed in double quotation marks ("").
• Target is the name of the STRING variable created in the supporting procedure for this SymbolSpecSelector function. The Symbol Spec Selector populates with the selections from the specified target variable. If you leave target blank by using double quotation marks (""), the Symbol Spec Selector populates with no symbol selected, ALL as the symbol definition, and 99 as the default number of levels. If you specify an invalid symbol, the Symbol Spec Selector loads with no symbol and a warning message displays.
• DimensionName is the dimension containing the symbols to include in the Symbol Selector.
• SymbolSpecifications is optional and is the level of symbols to display in the Symbol Selector hierarchy, in relation to the specified symbol, for example, SymbolName### or SymbolName#99.
• AllowLeaf is optional and specifies whether users can select leaf symbols from the Symbol Selector control and can have a value of TRUE or FALSE. The default if you do not specify AllowLeaf is FALSE.

  Note: AllowLeaf is tied to the symbols available to the user in the Symbol Selector control and not the symbol definition control. Users can always select one of All, Leaf, Parent, or Root and Parent from the symbol definition control.

• AllowReadOnly is optional and specifies whether users can select read-only symbols from the Symbol Selector control and can have a value of TRUE or FALSE. The default if you do not specify AllowReadOnly is FALSE.
• AttributeFilters is optional can be up to two attribute filters linked by AND or OR, enclosed in double quotations marks, using the syntax:

  FilterType{AttrName{Operation{Expression

  where:

  Value	Description
  FilterType	specifies the method to use to search the hierarchy for symbols matching the filter criteria and can be one of ALL, PARENT, LEAF, or ROOT. If you specify two attribute filters, FilterType must be the same for both filters.
  AttrName	is the name of an attribute.
  Operation	can be EQ for exactly equal to or NE for not equal to.
  Expression	is a character string. If the expression contains spaces, enclose the expression in double quotation marks preceded by a backslash (\"expression with spaces\"). If the expression is a list, separate multiple items with a pipe ( | ). For non-list attributes, the filter behaves as follows: Attribute EQ Expression — Matches only if the attribute is an exact match of the expression. Attribute NE Expression — Matches if the attribute is not an exact match of the expression. For list attributes, the filter behaves as follows: Attribute EQ Expression — Matches if the attribute is an exact match of the expression, or is a list of values, any one of which exactly matches the expression. Attribute NE Expression — Matches if the attribute is empty or a list of values, none of which exactly matches the expression.

  If you specify two attribute filters, enclose each filter in parentheses, for example "(attributefilter1) AND (attributefilter2)".

• Procedure is optional and is the name of the OnChange procedure to run after the user changes the field. Always include the extension, and include the file path if the file is not located in the default path. The default path is the path specified in the <rootpath> tag of the .lvapp file. If no root path is specified, the system assumes the root path is the applications folder in the working directory. For more information, see Using the OnChange keyword.
• Required is optional and can be one of the following:

  Value	Description
  TRUE	sUse this value to include a red asterisk beside the field label indicating to the user this field is required. This value ensures any buttons specified in the form document that include the optional Validate:TRUE parameter are unavailable until fields marked as required are completed by the user. For more information, see Button.
  FALSE	Use this value to leave the field label without an asterisk. This is the default if you do not specify Required.

Syntax Example 1

Syntax Example 2