/*	XForm.h
 *
 *		This is the code template for the 'form' handler; this is the
 *	message handling and control layer which nominally coordinates the
 *	behaviour of a window.
 */

/*  YAAF - Yet another application framework
 *  Copyright (C) 1997, 1998 William Edward Woody
 *  
 *  This library is free software; you can redistribute it
 *  and/or modify it under the terms of the GNU Library
 *  General Public License as published by the Free Software
 *  Foundation; either version 2 of the License, or any
 *  later version.
 *  
 *  This library is distributed in the hope that it will be
 *  useful, but WITHOUT ANY WARRANTY; without even the implied
 *  warranty of MERCHANTABIILITY or FITNESS FOR A PARTICULAR
 *  PURPOSE. See the GNU Library General Public License for
 *  more details.
 *  
 *  You should have received a copy of the GNU Library General
 *  Public License along with this library; if not, write to the
 *  Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 *  Boston, MA 02111-1307, USA.
 *  
 *  To contact the author, either e-mail me at woody@pandawave.com, 
 *	or write to
 *  
 *          William Edward Woody
 *          In Phase Consulting
 *          1545 Ard Eevin Avenue
 *          Glendale, CA 91202
 *
 *	Or visit us on the web at http://www.pandawave.com
 */

#ifndef PandaWave_XFORM
#define PandaWave_XFORM

#include <XConfig.h>

/************************************************************************/
/*																		*/
/*	Forwards															*/
/*																		*/
/************************************************************************/

class XGWindow;
class XGDocument;

/************************************************************************/
/*																		*/
/*	Form manager template												*/
/*																		*/
/************************************************************************/

/*	@C"XGForm"
 *	@H"XForm.h"
 *	@I
 *
 *		This is the 'form' class; this is an abstract class which provides
 *	the callbacks for managing a window.
 *
 *		The idea here is that a window is contructed out of a collection
 *	of self-contained views; these views are then controlled by the
 *	form belonging to that window. The forms themselves insert between
 *	the document and the window, and control the contents of the
 *	views in that window from the contents of the document.
 *
 *		How that works varies, depending on the view. A view can be
 *	rather promiscuous and actually get into the hands of the document
 *	database, though this is highly unusual. In most cases, the form
 *	mediates the communications between the document and the window,
 *	by reading the document database and entering the information into
 *	the window views.
 */

class XGForm {
	public:
								XGForm();
		virtual					~XGForm();
		
		// @G"Attach/Detach Semantics"
		
		/*	@F"XGForm::Attach" @I
		 *
		 *		Increments the attach count for this form object
		 */
		
		void					Attach()
									{
										fAttach++;
									}
									
		/*	@F"XGForm::Detach" @I
		 *
		 *		Decrements the attach count, and disposes of this
		 *	object when the count reaches zero.
		 */
		
		void					Detach()
									{
										fAttach--;
										if (fAttach <= 0) delete this;
									}
		
		/*
		 *	Document modified messages
		 */
		
		virtual long			DoDispatch(XGWindow *, long msg, 
													   long arg, 
													   void *parg);
		
		virtual struct _FormDispatchTable *_GetFormTable();
															
	private:
		long					fAttach;
};

/************************************************************************/
/*																		*/
/*	Form Message Dispatch												*/
/*																		*/
/************************************************************************/

/*	_FormDispatchTable
 *
 *		The structure of the record which is used to dispatch mesages
 *	received by a form object
 */

struct _FormDispatchTable {
	long						messageID;
	long						(XGForm::*procID)(XGWindow *, long, void *);
};

/*	@F"BEGINFORM"
 *	@U"BEGINFORM(classID)"
 *	@H"XForm.h"
 *	@I
 *
 *		This macro is the shorthand macro for constructing the form
 *	event dispatch table. This is used to build the table; the contents
 *	of the table is made by one or more DISPATCHFORM macros, and ended
 *	with the ENDFORM macro.
 */

#define BEGINFORM(classID)												\
				_FormDispatchTable *classID::_GetFormTable()			\
										{								\
											return classID::_FormDisp;	\
										}								\
				_FormDispatchTable classID::_FormDisp[] = {				

/*	@F"DISPATCHFORM"
 *	@U"DISPATCHFORM(message,method)"
 *	@H"XForm.h"
 *	@I
 *
 *		This macro constructs the contents of a form event dispatch
 *	table, the table associated with dispatching events for an XGForm
 *	object. The table is started with BEGINFORM, and ended with ENDFORM
 */

#define DISPATCHFORM(msg,proc)											\
				{ msg, (long (XGForm::*)(XGWindow *, long, void *))&proc },				

/*	@F"ENDFORM"
 *	@U"ENDFORM"
 *	@H"XForm.h"
 *	@I
 *
 *		This macro ends a form event dispatch table. Use BEGINFORM to
 *	start the table for an XGForm object, and DISPATCHFORM for building
 *	the contents.
 */

#define ENDFORM															\
											{ -1, NULL }				\
										};								

/*	@F"DECLAREFORM"
 *	@U"DECLAREFORM"
 *	@H"XForm.h"
 *	@I
 *
 *		For a form using this method of dispatching messages, this
 *	provides a good shorthand for declaring the dispatch proc
 */

#define	DECLAREFORM														\
				virtual struct _FormDispatchTable *_GetFormTable();		\
				static struct _FormDispatchTable _FormDisp[];			


#endif // PandaWave_XFORM
