DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 
ETI forms

Establishing field and form initialization and termination routines

As with the menu driver, you may sometimes want the form driver to execute a specific routine whenever the current field or form changes. The following routines let you do this.

SYNOPSIS

   typedef void (* PTF_void ) ();
   

int set_form_init (form, func) FORM * form; PTF_void func;

PTF_void form_init (form) FORM * form;

int set_form_term (form, func) FORM * form; PTF_void func;

PTF_void form_term (form) FORM * form;

int set_field_init (form, func) FORM * form; PTF_void func;

PTF_void field_init (form) FORM * form;

int set_field_term (form, func) FORM * form; PTF_void func;

PTF_void field_term (form) FORM * form;

The argument func is a pointer to the specific function you want executed by the form driver. This application-defined function itself takes a form pointer as an argument.

As with menus, if you want your application to execute a routine at one of the initialization or termination points listed below, you should call the appropriate form initialization or termination routine at the start of your program. If you do not want a specific function called in these cases, you may refrain from calling these routines altogether.

Function set_form_init

The argument func to this function is automatically called by the form driver

Function set_field_init

The argument func to this function is automatically called by the form driver

Function set_field_term

The argument func to this function is automatically called by the form driver

Function set_form_term

The argument func to this function is automatically called by the form driver

To see more precisely when the initialization and termination routines may be executed, note that your form page and current field can be changed in the following circumstances:


NOTE: All of these initialization and termination functions are NULL by default. This means that no function need be called.

These functions promote common operations, such as row or column total updates, display of previously invisible fields, activation of previously inactive fields, and more. As an example, ``Sample termination routine that updates a column total'' shows a field termination routine update_total, which dynamically adjusts a column total field whenever a row field value changes. Function main calls set_field_term to establish update_total as the field termination routine.

   void update_total (form)
   FORM * form;
   {
   	FIELD ** f = form_fields (form);
   	char buf[80];
   	double total, atof();  /* atof() converts string to float */
   

switch (field_index (current_field (form))) { case ROW_1: case ROW_2: case ROW_3:

/* field_buffer returns field's value as string, which atof converts to float */

total = atof (field_buffer (f[ROW_1], 0)) + /* calculate total */ atof (field_buffer (f[ROW_2], 0)) + atof (field_buffer (f[ROW_3], 0));

sprintf (buf, "%.2f", total); set_field_buffer (f[TOTAL], 0, buf); break; } }

main () { FORM * form;

set_field_term (form, update_total); /* establish termination routine */ }

Sample termination routine that updates a column total

Function set_field_buffer sets the column total field to the value total stored in buf. See ``Setting and reading field buffers'' for details on field_buffer and set_field_buffer.

For another example, consider ``Field initialization and termination to highlight current field''. It shows a common use for field initialization and termination--highlighting a field when it becomes current and removing the highlight when it is no longer current.

   void bold_off (form)
   FORM * form;
   {
   	/* remove highlight */
   

set_field_back (current_field (form), A_UNDERLINE); }

void bold_on (form) FORM * form; { /* highlight field */

set_field_back (current_field (form), A_STANDOUT | A_UNDERLINE); }

main () { FORM * form;

/* establish initialization and termination routines */

set_field_init (form, bold_on); set_field_term (form, bold_off); }

Field initialization and termination to highlight current field

If functions set_form_init, set_form_term, set_field_init, or set_field_term encounter an error, they return the following:


E_SYSTEM_ERROR -
system error
As usual, if you want a specific default initialization or termination function for all forms or all fields, you can pass the appropriate set function a NULL form pointer. Passing a NULL form pointer to the access functions returns the current ETI default.
Next topic: Manipulating the current field
Previous topic: An example of form driver usage

© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 27 April 2004