Adding New Picture Control Characters

Each picture control character used by the system is associated with a character validation function. When the user types a printable character, the character validation function associated with the picture control character at the current position in the field is called. The character validation function ensures that the character typed by the user follows the rules signified by that picture control character.

To add new picture control functions, you need to write the character validation function, associate it with a picture control character, and install the function and picture control character in the appropriate system table. You may also want to modify or delete picture validation functions.

Step 1: Write a character validation function.

The control function must be an integer function. It should return FALSE if the keystroke is invalid for this picture control character. It should return TRUE if the keystroke is valid for this picture control character.

Character validation functions must accept one parameter: a pointer to an integer. When the form editor calls the function, the parameter will be a pointer to the keycode returned by ki(), the system keystroke input function.

The character validation function must check the validity of the character, given your definition of what characters are acceptable for this control character. Since the character validation function is passed a pointer to the entered keycode, the function can change the keycode value if necessary. The character validation function that automatically converts lowercase letters to uppercase makes use of this capability.

The call for a picture validation function is as follows:

int vc_test(keyp);

int *keyp;            /* Pointer to key typed by user        */

Step 2: Assign a #defined name for the picture control character.

vv_form.h contains a list of defined constants for accessing the picture control characters in the table. You should add a name for your picture control character to this list.

The defined constants are used by the system for ease in referring to the entries in the array of picture control symbols. Using defined constants also ensures that if the picture control character changes, it can still be accessed by its defined name.

Step 3: Add an entry to the picture control table.

Array _dpictbl[ ] in vv_main.h is an array of structures of type DPICDEF. Each structure contains a picture control character and a pointer to its associated character validation functions. A sample entry from that table is listed below:

{'9', vc_digit},

This entry in the table means that when the character "9" appears in a picture, the function vc_digit() is called as the character validation function during field editing. Function vc_digit() ensures that the character entered in the field is any digit from 0 to 9, a plus sign (+), or a minus sign (-).

To install your own function, you add your choice of control character and character validation function name to the array. Any character not already assigned as a picture control character may be used.

Two empty slots are provided for you to place your entry. You can change the header file or change this global array in code as such:

_dpictbl[HEXPICCH].dp_sym = 'H';

_dpictbl[HEXPICCH].dp_vfunc = vc_hex;

Warning: The order of this table must be preserved. Internal functions access the table by #defined values. Any additions to the table should be placed after the system entries.

Step 4: Modify the field type information table.

Picture control characters also appear in the field type information table _fldinfo[ ] in vv_main.h. The field type information table contains information specific to each field type in the system. The allowed picture characters for a field are given for each field type. For example, the entry for a date field is as follows:

{ FIELDTAG, dc_todate, dc_frdate, vf_date, PICVALFP, OFF_STRING, 0, 0,

  sizeof(RGLONG), TRAILBLANKS, (UCHAR *) "9UA*!X", rgset_date,

  ALLOW_PROT_CH | ALLOW_MULT_PICSYM },

This entry is a structure of type FLDTYPE. The eleventh member of the structure, in this case "9UA*!X", is a list of the allowed picture characters for the field type.

If you add a picture control character, you must look at each entry in the field type information table and change the allowed picture characters appropriately.

Step 5: Review the picture validation function for each field type.

The fifth member of the field type structure is a pointer to the picture validation function. For the date field, whose field type structure is shown above, the picture validation function is PICVALFP. The picture validation function is called by fld_def() to ensure that the picture is valid for a field of the specified type and is called only in the development libraries.

If you add a picture control character, you will have to consider the picture validation function for the field types whose allowed picture characters have changed. Generally, you will not have to change the picture validation function unless the picture flags set for the field type are incompatible with your allowed picture characters.

The picture flags are set in the last member of the field type structure and are interpreted as follows:

If, by adding your picture control characters, the picture will not conform to the picture flags set for that field type, you should remove or rewrite the picture validation function. To remove the picture validation function, specify NULLFP in the structure for that field type. See "Writing Picture Validation Functions" later in this chapter if you want to replace the picture validation function with your own.

Step 6: Add prototype or extern statements for the new functions.

Function prototypes or extern declarations for any added functions should be placed in a header file. The simplest place to add these is in vv_form.h.