To add a new field type, you must add an entry in the field type information table. This entry will include all the information needed by the system to process a new field type.
Step 1: Write all necessary functions.
To set up a field and process entered data, Vermont Views uses a number of conversion and validation functions that are field-type specific. These functions are:
Adding string-type fields is a fairly simple task. The validation function will generally be straightforward and the conversion functions need only to deal with the PICSKIP and TRAILBLANKS field options. The picture validation function is optional.
For any of these functions, you can use one of the functions provided in the library or write your own. How to write each type of function required by the system is described in later sections of this chapter.
Step 2: Add a field type structure in the field information table.
All of the field type-specific information is contained in an array of field type structures located in vv_main.h. The array, _fldinfo[ ], contains one structure of type Field type:FLDTYPE for each field type. The FLDTYPE structure is defined in vv_form.h as follows:
|
||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
||
If you wish to add a new field type to the system, you need to initialize a field type structure for the new field type and add it at the end of the fldinfo[ ] array.
The following explains what to specify for each field type structure member:
tag: Specify Field type:FIELDTAG for the tag. In the development libraries, fld_def() and srf_def() check the tag structure member of the _fldinfo[ ] structure for the field type specified in the call. If the tag does not equal FIELDTAG, you have not #included the header file to enable this field type.
st_varfp: Specify the name of the function to be called by the system to convert the string displayed in a field to a value of the appropriate type.
var_stfp: Specify the name of the function to be called to convert a data variable to a string for display in the field.
sysvalfp: Specify the name of the function to be called to validate the data entered by the user. All field types must have a field validation function associated with it unless (1) it is a string-type field and you will store the string exactly as it appears in the field and (2) you will do no range checking for a field of this type.
picvalfp: Specify the name of the function to be called to validate the picture for a field of this type. This function is called by fld_def() to ensure that the picture specified is valid for the specified field type. Since this is a development error, you do not have to install a picture validation function.
In most cases, the system picture validation function, pic_val() #defined as PICVALFP, can be used. (A #defined value is used so that this development aid can be removed from the production libraries.) You will need to write your own picture validation function if the picture flags available for the testing a picture are insufficient (see flags below). Specify NULLFP if you do not want to install a picture validation function.
al_offset: Specify the alignment offset for Vermont Views to use when searching for data in an array of structures. This is mainly used for accessing the data storage area for a particular field on the scrollable region and for accessing the data storage area when using a Designer-generated form structure. Specify one of the following: OFF_CHAR (for field with an underlying variable type of char), OFF_LONG (long int variable), OFF_DOUBLE (double variable), OFF_INT (for int variable), OFF_SHORT (for short int variable), or OFF_STRING (for string variable).
varsize: Specify the size of the variable needed to store the data for a field of this type. Use the compiler's sizeof() function and the data variable type you are using. For instance, sizeof(int). If the variable is stored as a pointer to a null terminated string which holds the value, specify 0.
cvbufsize: Specify the maximum size that the string representation of a variable of this type might be, excluding a byte for the null terminator (the system takes care of this). For example, the largest value that a long integer can be is LONGMAX. If this value is 2147483647, as initialized by the system, 10 characters are needed for the number and 1 character for the sign. Thus, you would specify 11 as the conversion buffer size. Note that for string-based fields, you may have to allocate a larger conversion buffer to allow for adding characters when right or left justifying the string. If no conversion buffer is needed during the conversion process, specify 0.
rangesize: If you plan to use the Vermont Views facility for checking ranges, you must define a range structure whose first structure member holds a minimum value and the second structure member holds a maximum value. These structure members must be of the correct data type for the field type. You can use one of the range structures already defined in vv_form.h for the various types of data.
Use the compiler's sizeof() function to determine the size of the range structure. Specify 0 if you do not plan to use the range checking facility for this field type.
fld_opts: Specify the default field options for this field type.
picch: Specify the picture control characters that you want to use for defining a picture for a field of this field type.
setrangefp: Specify the name of the function to be called to initialize the range structure used for range checking. If this is a numeric field type (including characters), you can specify the system range set function rgset(). If data entered in a field of this field type is stored as a pointer (this includes such fields as dates and times), you must write your own range set function. Specify NULLFP if you are not planning to use the range checking facility for a field of this type.
flags: Specify the flags used by the picture validation function to validate a picture for this field type. Picture flags and their meanings are as follows:
| ALLOW_PROT_CH | Protected characters are allowed |
| ALLOW_DECIMAL | One decimal point (soft or hard) is permitted |
| ALLOW_MULT_PICSYM | More than one picture control character can be used in the picture. |
| ALLOW_E | One exponential symbol (E) is permitted |
Pictures are always checked to make sure that only allowed picture control characters are used and that there is at least one picture control character in the picture.
Step 3: Determine the number of the field type.
Field types are identified by #defined numbers. Field types and their #defined values are declared in vv_form.h. The number of field types defined in Vermont Views is stored as VCSFLDTYPEQ.
To allow for expansion of the system, the first field type you add should be #defined as Field type:VCSFLDTYPEQ. The second should be #defined as VCSFLDTYPEQ + 1. VCSFLDTYPEQ is a #defined value for the number of system field types. By using VCSFLDTYPEQ, you are ensured that you will not overlap any future additions to the field types.
For convenience, add a #define for the new field type with the system defined field types in vv_form.h.
Step 4: Increment the counter for the number of user field types.
The number of user-defined field types is stored as the defined constant USRFLDTYPEQ in vv_form.h. USRFLDTYPEQ is used by internal Vermont Views functions to correctly determine how many field types there are.
As the package is provided, Field type:USERFLDTYPEQ is defined as 0. When you add a new field type, increment this number.
Step 5: Add prototype or extern statements for the new functions.
Function prototype 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, but the Vermont Views convention is to use a separate header file for declarations for each field type. If you choose to follow this convention, use one of the existing header files as a guide to creating one for your field type.
