ETI forms

Associating windows and subwindows with a form

Remember that two windows are associated with every form -- the form window and the form subwindow. The following functions assign windows and subwindows to forms and fetch those previously assigned to them.

SYNOPSIS

   int set_form_win (form, window)
   FORM  form;
   WINDOW  window;
   
   WINDOW  form_win (form)
   FORM  form;
   

   int set_form_sub (form, window)
   FORM  form;
   WINDOW  window;
   

   WINDOW  form_sub (form)
   FORM  form;

These functions enable you to place stylistic borders, titles, and other decoration around a form.

NOTE: Remember that if the form window is NULL (the default), ETI uses stdscr. If the form subwindow is NULL (the default), ETI uses the form window so you need not use functions set_form_win or set_form_sub at all.

If you do not want to use stdscr, you should create a window and a subwindow for every form. ETI automatically writes all low-level ETI (curses) output of the form proper on the form subwindow. If you want further output (such as borders, titles, or static messages), you should write it on the form window. However, you need not write any further output at all.

NOTE: Be sure to apply all low-level ETI (curses(3ocurses)) command output and refresh operations to your form's window, not its subwindow.

``Form functions write to subwindow, application to window'' diagrams the relationship between ETI Form functions, your application program, and its form window and subwindow.

Form functions write to subwindow, application to window

``Creating a border around a form'' shows how to create a form with a border of the terminal's default vertical and horizontal characters.

   	/*  create window 4 characters larger than form dimensions
   	with top left corner at (0, 0).  subwindow is positioned
   	at (2, 2) relative to the form window origin with dimensions
   	equal to the form dimensions.  */
   
   FORM * f;
   WINDOW * w;
   int rows, cols;
   

   scale_form (f, &rows, &cols); /* get dimensions of form */
   

   if (w = newwin (rows+4, cols+4, 0, 0))
   {
   	set_form_win (f, w);  /* associate window and subwindow with form */
   

   	set_form_sub (f, derwin (w, rows, cols, 2, 2));
   

   	box (w, 0, 0);       /* create border */
   }

Creating a border around a form

Function scale_form sets the values of the variables rows and cols, which provide the form dimensions without the border. Adding four to the dimensions of the form window clearly sets off the form border from the fields of the form (the form proper).

If functions set_form_win or set_form_sub encounter an error, they return one of the following:

E_SYSTEM_ERROR -: system error
E_POSTED -: form is posted

As usual, you can change the default form window or subwindow. For instance, you can change the default form window from stdscr to a window w by passing a NULL form pointer, as follows:

   int rows, cols, firstrow, firstcol;
   
   			 /* create form window */
   

   WINDOW * w = newwin (rows, cols, firstrow, firstcol);
   

   set_form_win((FORM *)0, w);
   		/* change default form window to w */

Note that if you later change a posted form by writing directly to its window, before continuing you must reposition the form window cursor using pos_form_cursor. See ``Positioning the form cursor''.