Manipulating the current field

The current field is the field where your end-user is positioned on the display screen. It changes as the end-user moves about the form entering or changing data. The cursor rests on the current field. To have your application program set or determine the current field, you use the following functions.

SYNOPSIS

   int set_current_field (form, field)
   FORM  form;
   FIELD  field;
   

   FIELD  current_field (form)
   FORM  form;
   

   int field_index (field)
   FIELD  field;

When a form is created by new_form or the fields associated with the form are changed by set_form_fields the current field is automatically set to the first visible, active field on page 0.

``Example manipulating the current field'' illustrates the use of these functions. Function set_first_field uses set_current_field to set the current field to the first field in the form's field pointer array. Function first_field, on the other hand, returns a Boolean value indicating whether the current field is the first field.

   int set_first_field (form) /* set current field to first field */
   FORM * form;
   {
   	FIELD ** f = form_fields (form);
   	return set_current_field (form, f[0]);
   }
   

   int first_field (form) /* check if current field is first field */
   FORM * form;
   {
   	FIELD * f = current_field (form);
   	return field_index (f) == 0;
   }

Example manipulating the current field

If function set_current_field encounters an error, it returns one of the following:

E_SYSTEM_ERROR -

system error

E_BAD_ARGUMENT -

NULL form pointer or field not connected to form

E_BAD_STATE -

called from init/term routines

E_INVALID_FIELD -

current field is invalid on posted form

E_REQUEST_DENIED -

field not active or not visible

The function field_index returns -1 if its field pointer argument is NULL or the field is not connected to a form.