Creating a Spin Button

To create a spin button you must first define a standard data field, either using the Designer or in code. Any of the following standard data fields can be converted to a spin button: string, character, date, time, integer, short integer, long integer, decimal, single-precision floating point, or double-precision floating point. When you place the field on the data form, remember to leave six extra spaces to the right of the field for the spin button control characters. See Chapter 7, "Standard Data Field Types," to learn how to create a standard data field.

The spin button choices are specified using a memory file. You do not need to know the details about using the Vermont Views memory file facility to implement a spin button. If you want more information about what memory files are and how they can be manipulated, see Chapter 45, "Creating and Viewing Memory Files."

Designer: You can convert a data field to a spin button field in the Designer. If you use the Designer to generate your main program, it will create the skeleton text for the memory file and the code to read the memory file; you will need to edit the text file, clist.txt, to add your selections. See the Designer User's Guide for more information.

If you do not use the Designer to generate your main program, you will need to create or edit the memory file that holds the selections; follow the steps outlined below.

You can also convert a data field to a spin button in your code at any point after you have read the form from the Designer library.

Code: Use the following steps to create a spin button in code. These steps assume that you have already created the standard data field and have #included the header file required to implement the specified data field type.

Step 1: Write the text for the list of spin button choices.

The text for the list of choices is written in an ASCII text file that you construct with any text editor.

nEach item in the list must appear on a single file line.
nThe length of the entry must fit into the data field.

By default, the first choice in the list is the first choice that is displayed in the field during form processing.

Step 2: Mark the spin button list text with a keyword.

Many spin button lists can be placed in a single ASCII text file. Each section of the file is marked with a keyword. When assigning a spin button list to a field, you pass the keyword that corresponds to the spin button choices that you want to appear in that field. Only choices from the section of the file marked by the keyword are displayed in the spin button field. The keyword itself is not displayed.

A keyword must start in the first column (column 0), have the system keyword character as the first character (an asterisk by default), and be the only text on the line. The keyword can be more that one word in length.

Only those lines containing keywords can have the keyword character in the first column.

Below, is an example of how a spin button list should appear in an ASCII text file, named spin_data.txt, where "*COLORS" is the keyword.

*COLORS

Red

Green

Blue

Yellow

Caution: The asterisk keyword character (*) that marks the keyword must appear in the first column of the line.

Step 3: Include the spin button header file vv_spin.h.

Include the spin button header file vv_spin.h in all modules that use spin buttons and in your main() module before vv_main.h.

Step 4: Read the ASCII text file into a memory file.

After you have constructed the file of spin button lists, you must read it in from disk to a memory file. The steps involved are:

1	Define a memory file with mf_def().
2	Read the ASCII file into the memory file with mf_rd().

Defining the Memory File

The function mf_def() has the following function call:

MFILEPTR mf_def(maxrows, maxcols)

where maxrows is the maximum number of rows the memory file could contain and maxcols is the maximum number of columns. Generally, you should specify the maximum number of columns to be the length of the longest line in your ASCII text file. You can specify maxrows to be the number of lines in the ASCII text file; however, you may want to specify a larger number in case you want to insert more items later.

Reading in the ASCII Text File

The function mf_rd() reads the ASCII text file and places the text into the memory file you defined. The call for mf_rd() is as follows:

int mf_rd(filespec, mfp)

where filespec is the path (optional) and the filename of the ASCII file containing the spin button list and mfp is a pointer to the memory file that you just defined.

Step 5: Assign a spin button list to the field.

After you have the spin button lists in a memory file, you assign a spin button list to a specific field with the set field to spin button function, sf_spin():

int sf_spin(keyword, mfp, fldp)

UCHAR *keyword;        /* Keyword marking spin button list items        */

MFILEPTR mfp;        /* Memory file holding spin button list         */

FIELDPTR fldp;        /* Field to assign spin button list            */

For the argument keyword you should specify the keyword for the section of the memory file that contains the spin button list for the field in question. You must include the keyword character in the string, for example, "*COLORS". You should set the keyword to NULLP for a memory file that contains only a single spin button list and has no keywords.

In the code example below, the following line:

sf_spin("*COLORS", mfp, fldp);

assigns a spin button list, whose items are listed under the keyword *COLORS in the memory file mfp, to the field fldp.

Step 6: Process the form.

Process the form with fm_proc(). Collect the data. Free the form with fm_free().

Step 7: Free the memory file with mf_free().

When the form is freed, the spin button structures associated with any fields on the form are also freed. However, the memory file containing the spin button lists is not freed. If you are finished with all of the contents of the memory file, free this memory before returning from your program. To do this, call the function mf_free():

void mf_free(mfp)

MFILEPTR mfp;        /* Memory file to free            */

If you have other sections in the memory file marked with keywords, make sure you do not need these sections before freeing the memory file.