Workbench User Guide : Generating Fields from Predefined Templates : How You Can Add a Generated Field to a Frame : The spin_control Field Template
 
Share this page          
The spin_control Field Template
The spin_control field template is used to create a control consisting of an entry field and up and down buttons that increment or decrement the value displayed in the field. A spin control can contain integer, float, money, date, or varchar data. In the case of a varchar field, the individual values come from a ChoiceList that can be built automatically or that you can provide.
When you create a spin control, you can set its minimum and maximum values, the increment value to add or subtract when the up or down button is clicked, and a flag indicating whether you want the field to wrap between its minimum and maximum values when either limit is reached. For date fields, the increment can be specified in date units (such as months). For other data types, the increment should be a numeric value.
When you are designing the field, you can further customize the entry field by modifying the display format of the entry field based on the data type.
Create a Spin Control Field
You can create a spin control field using the Frame Editor.
To create a spin control field
1. On the Develop tab, in the Components portlet, open the frame in which you want to create the field from the field template.
2. Click Insert, Field From Field Template.
The Select a Field Template dialog appears.
3. Select the core application and the spin_control template, and then click OK.
4. Position the field on the frame.
The Spin Control Assistant appears.
5. Complete the dialog using the following information:
Spin Control Type
Specifies the type of spin control:
Integer
Float
Date
Money
ChoiceList (varchar)
Depending on the type of spin control selected, different controls appear in the Spin Control Assistant. For more information, see How You Can Specify Spin Control Values.
Wrap Value
Specifies whether the value wraps:
Enabled
Specifies that when the specified maximum value is reached, it wraps to the minimum value and vice versa
Disabled
Specifies that the value stops incrementing or decrementing
6. Click Generate.
The field is created and displayed on the form.
How You Can Specify Spin Control Values
There are five different types of spin controls that you can choose:
Integer
Float
Money
Date
ChoiceList (varchar)
For the first four types, the following fields appear in the Assistant window:
Initial Value
Specifies the value that is initially displayed in the field
Minimum Value
Specifies the lowest value that is displayed in the field
Maximum Value
Specifies the highest value that is displayed in the field
Increment Value
Specifies the amount that the value is incremented or decremented when the user clicks the up or down arrow button
The ChoiceList type automatically makes use of the Standard List 4GL procedure. (For more information, see the StdList function in the Language Reference Guide.) If you select ChoiceList as the Spin Control Type, the following choices are available:
List Type
Specifies the type of list to be created:
Weekdays
Lists weekday names (1–7, Sunday to Saturday)
Months
Lists month names (1–12, January to December)
States
Uses a predefined list of U.S. states (1–50, Alabama to Wyoming)
Query
Lists unique values from a specified table and column (row 1 through n, the maximum number of rows). When this option is chosen, the following fields appear:
Table Name
Specifies the variable name for the table to be used
Column Name
Specifies the variable name for the column to be used
Custom Name
Lists your own list of values
Note:  When you use this option, take care that the list you provide is valid. Its values must be of the varchar data type and must be unique.
List Name
Specifies a variable name for the list
Initial Value
Specifies the index value of the initial selection in the list
How a Spin Control Field Works
When the frame containing the spin control is executed, the field appears, containing a specified initial (default) value. For example, the default values in the Spin Control Assistant dialog produces the following:
A user can type a new value into the entry field portion of the spin control, or use the increment or decrement buttons to change the value. If a valid value is typed, it is verified the next time the increment or decrement button is clicked, and “clipped” to the limits defined for the field if it is out of range. If the value entered is valid, the buttons increment or decrement it as usual.
Another example of a generated spin control field, using the Weekdays choice list (ChoiceList Spin Control Type option), follows:
The functionality of the spin control is based on the Spin_Object user class, which handles its processing. For more information about the Spin_Object user class, see the appendix "Generated User Classes" in the Language Reference Guide.