ETI forms

Changing the form page

Two form functions enable your application program to change to another page on the form or to determine the current page of the form.

SYNOPSIS

   int set_form_page (form, page)
   FORM  form;
   int page;
   
   int form_page (form)
   FORM  form;

Upon execution of set_form_page, the current field is set to the first field on the new page that is visible and active (visited during form driver processing). Variable page must be in the range of 0 through N-1, where N is the total number of pages. The function form_page returns the page number of the page currently visible on the screen.

When function new_form creates a form or function set_form_fields changes the fields associated with a form, the form page is automatically set to 0.

NOTE: Your application program need not call set_form_page unless you want to implement page navigation requests that are not supported by the form driver and discussed in ``ETI form requests''.

``Example changing and checking the form page number'' illustrates the use of these functions. Function set_first_page uses set_form_page to change to the first page of the form, while function first_page uses form_page to return a Boolean value indicating whether the first page of the form is currently displayed. Note that the first page is numbered 0.

   int set_first_page (form) /* set to first form page */
   FORM * form;
   {
   	return set_form_page (form, 0);
   }
   
   int first_page (form) /* check if on the first form page */
   FORM * form;
   {
   	return form_page (form) == 0; /* return Boolean */
   }

Example changing and checking the form page number

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

E_SYSTEM_ERROR -: system error
E_BAD_ARGUMENT -: NULL form or page out of range
E_BAD_STATE -: called from init/term routines
E_INVALID_FIELD -: current field is invalid on posted form

The function form_page returns -1 if given a NULL form pointer or there are no fields connected to the form.