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

when the form is posted
just after every form page operation, that is, after the page changes on a posted form

Function set_field_init

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

when the form is posted
just after a field change operation, that is, every time the current field changes on a posted form.

Function set_field_term

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

just after the field is validated, that is, just before the current field changes on a posted form
when the form is unposted

Function set_form_term

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

just before every form page operation, that is, just before the page changes on a posted form
when the form is unposted

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:

Both the form page and the current field may be changed automatically by the form driver in response to a user's request.
The form page may be changed when the current field is changed using set_current_field.
The current field is changed when the page is changed using set_form_page.

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.