Programming guideline of WinDom

The modal form

With the predefined modal form, the point of view is completly different: forms are handled in a similary way than the classical GEM forms (see the GEM form library). The idea is that a modal form stops the program (like the classical forms), but not the other applications. So, there are three steps:

Display the form: function FormWindBegin(),
Handle the events: function FormWindDo(),
Close the form: function FormWindEnd().

Let's see in details these three functions.

	WINDOW *FormWindBegin( OBJECT *form, (!B)char(!b) *nom);

creates the form window centered on screen (using the function GrectCenter() internaly) and returns the window descriptor. The default widgets of the window are a moving bar, a title and a smaller button but these widget can be changed by the user via the configuration file. The object tree form should containt a EXIT or TOUCHEXIT object.

	(!B)int(!b) FormWindDo( (!B)int(!b) evnt);

this function returns the index of the last object selected. The parameter evnt sets the event to handle: the MU_MESAG evnt should be handled. We will see that all events can be handled if needed.

	void FormWindEnd( void);

the function close the windom.

First example:

In this example, we draw a modal form and we return the index of the selected object.

int CallDialog( int index) {
   OBJECT *dialog;
   int res;

   rsrc_gaddr( 0, index, &dialog);
   FormWindBegin( dialog, "Formulaire");
   res = FormWindDo();
   FormWindEnd();
   return res;
}

Notice that, si the user clicks a EXIT or TOUCHEXIT object, the function terminates. It is not possible to handled, for example, a slider in this example.

Second example:

int CallDialog( int index) {
   OBJECT *dialog;
   int res;

   rsrc_gaddr( 0, index, &dialog);
   FormWindBegin( dialog, "Formulaire");
   do {
      res = FormWindDo( MU_MESAG);
      switch( res) {
         case OBJ_TOUCHEXIT1:
            ....
            break;
         ....
      }
   } while( dialog[res].ob_state & TOUCHEXIT);
   FormWindEnd();
   return res;
}

In this example, only EXIT objects selected can terminate the loop.

Third example:

The FormWindDo() function can handled all GEM event. If you set to 1 the bit FORM_EVNT of the evnt parameter of FormWindDo(), the function returns the last event detected by EvntWindom() (use internaly by FormWindDo()). For example, the call:

		res = FormWindDo( MU_MESAG|MU_TIMER|FORM_EVNT);

return the value MU_TIMER|FORM_EVNT if a timer
event occurs otherwise it returns an object index.

     int quit = 0;

     rsrc_gaddr( 0, index, &dialog);
     FormWindOpen( dialog, "Formulaire");
     do { /*
		   * loop on AES events (bit FORM_EVNT)
           */
          res = FormWindDo( MU_MESAG|FORM_EVNT);
          if( res & FORM_EVNT) {  /* A AES event occurs
								   * (in this case, only MU_MESAG
								   * is possible */
               if( res & MU_MESAG && evnt.buff[0] == AP_TERM) {
                    snd_msg( NULL, AP_TERM, 0, 0, 0, 0);
                    quit = 1;
               }
          } else { /* handle the form ... */
               switch( res) {
               case OK:
                    quit = 1;
                    break;
                    ...
               }
          }
     } while( !quit );
     FormWindEnd();


Fourth example: 

From Windom version of November 1999, it is possible to handle all
AES evnt using the fonctions from the Evnt Library. In particular,
FormWindDo() uses the EvntWindom() function. So to trap an AES event
during a FormWindDo() call, just use the EvntAttach() function.

{
	 void *oldfunc;
     int quit = 0;

     rsrc_gaddr( 0, index, &dialog);
     FormWindOpen( dialog, "Formulaire");
	 /* backup the old value */
	 oldfunc = Evntfind( NULL, AP_TERM);
	 /* give a new value */
     EvntAttach( NULL, AP_TERM, local_apterm);
     /* handle the form ... */
	 do {
	  	 res = FormWindDo( MU_MESAG);
	 	 switch( res) {
      	 case OK:
     	 	 quit = 1;
     	 	 break;
             ...
         }
	 } while( !quit);
	 /* Restore value */
	 EvntAttach( NULL, AP_TERM, oldfunc);
     FormWindEnd();
}


Important remark : the functions binded by EvntAttachj() have a
global action. So it is possible sonme function should be used during
a FormWindDo() or any function using EvntWIndom(). In this case, the
function should be provisary discarded (using EvntDelete()).