Programming guideline of WinDom

Terminate a WinDom application

There is no unique way to terminate an application, but we give here some examples to quit in a clean manner. Proceed in three steps: quit the main event loop, close and delete all windows and clean up memory and other ressources.

The end of a program may occur in various situations:

the user selects the Quit options of the menu application: you have to inspect the MN_SELECTED or WM_MNSELECTED messages.
all windows are closed and your application has no global menu. This should terminate the application and can be detected with the WinDom variable wglb.first being NULL (this means that all windows are closed and deleted).
the application received an AP_TERM message: this message means that the application should terminate now.
the application produced an error and received a MiNT crash signal.

The better method is to write a function which terminates properly the application. It typically looks like that:

void ap_term_( void) {
	/* Close all windows: see the previous section */
	while( wglb.first) {
		ApplWrite( wglb.first, WM_DESTROY);
		EvntWindom( MU_MESAG);
	}
	/* Free all ressource */
    /* if you have install extended object type ...*/
	RsrcXtype( 0, NULL, 0);
	/* ... and free the ressource */
	RsrcFree();

	/* Others ressources to free */
	...
	/* Quit WinDom environment */
	ApplExit();

	/* Finish Application */
	exit( 0);
}

Now your application should handle the message AP_TERM. As we nowadays have multitasking OS, handling this message is a general rule for any GEM application. You can attribute the ap_term() function to this message like that:

	EvntAttach( NULL, AP_TERM, ap_term);

Then the ap_term() function is invoqued when EvntWindom() recieves an AP_TERM message.

You can deal with your application crashing by trapping the MiNT signals sent with the function Psignal():

	Psignal( SIGQUIT, ap_term);
	Psignal( SIGBUS,  ap_term);
	etc ...

Note: MiNT signals are available with MagiC.

If your application does not install a desktop menu, the main function may look like:

int main( void) {

	ApplInit();
	EvntAttach( NULL, AP_TERM, ap_term);
	Psignal( SIGQUIT, ap_term);
	/* ... others signals ... */

	/* Main loop event */
	while( wglb.first) EvntWindom( MU_MESAG);
}

And if your application has a desktop menu:


/*
 * This function manages the desktop menu
 * The evnt.buff variable is a WinDom global variable
 * that contains the AES buffer message returned by
 * evnt_multi() after a MU_MESAG event.
 */

void do_menu( void) {
	int title = evnt.buff[3];

	switch( evnt.buff[4]) {
	case QUIT:
		ApplWrite( NULL, AP_TERM);
		break;
	}
	MenuTnormal( NULL, title, 1);
}

int main( void) {
	OBJECT *menu;

	ApplInit();
	/* Install the menu */
	RsrcLoad( "myrsc.rsc");
	rsrc_gaddr( 0, DESKTOP_MENU, &tree);
	MenuBar( tree, 1);
	EvntAttach( NULL, AP_TERM, ap_term);
	Psignal( SIGQUIT, ap_term);
	/* ... others signals ... */
	/* trap the menu selections */
	EvntAttach( NULL, MN_SELECTED, do_menu);

	/* Main loop event */
	while(1) EvntWindom( MU_MESAG);
}

Remark 1:

The EvntAttach() is more powerfull than, for example, a simple test on the message gets by EvntWindom() :

		do
			EvntWindom( MU_MESAG);
		while( evnt.buff[3] != AP_TERM)
		apterm();

In this case, the action of ap_term() is local. With the EvntAttach() method, the ap_term() function will be always called by any EvntWindom() invocation. It is more global because some WinDom functions call EvntWindom() and the ap_term() function may have then to be invoked. It is the case with the font selector or the popup menu manager.

More about AP_TERM

This message indicates:

a system shutdown, in this case, the sixth word of the AES message buffer containts the value of AP_TERM(50),
a screen resolution change, in this case, the sixth word of the AES message buffer containts the value AP_RESCHG(57),
a user terminaison request (eg via a taskapp bar), in this case the sixth word of AES message buffer is different of AP_TERM(50) and AP_RESCHG(57).

After a system shutdown or a screen resolution change, if your application cannot finish, you have to inform AES by sending a AP_TFAIL(51) message by using the shel_write() function with the mode=SWM_NEWMSG(9). At beginning of your application you have to inform AES that your application understands the AP_TERM message like that:

	if( has_appl_getinfo()) {
		int val1, dum;

		appl_getinfo( 12, &val1, &dum, &dum, &dum);
		if( val1 & 0x8) shel_write( 9, 1, 1, NULL, NULL);
	}