//////////////////////////////////////////////////////////////
	PLUGIN SDK

	(c) NeXO Software, Benoit SCHERRER
	p.c.scherrer@wanadoo.fr
//////////////////////////////////////////////////////////////


INTRODUCTION
////////////
	The support of plugin is a really advanced function of
	PCTOOLS. What is powerful is that PCTOOLS is not
	supposed to know which plugin exists or not.

	When it is launching, it looks for every plugins in 
	each folders of the calculator and build a table of 
	compatible plugins.

	Then the idea is that plugins are able to intercept
	events : for instance, each plugin can intercept a
	key hit, the drawing of an item, the selection of
	an item... 	
	Thus everything become possible!


THE FORMAT OF PLUGINS
/////////////////////
	Plugins are standard assembly programs compiled by
	FargoII (for ti92) or DoorsOS/Teos (for ti92+,ti89).
	The only thing is that you should use the PRG_AS_PLUGIN
	macro definited in pctplug.h. It gives to the program
	the signatur and the possibility to be a plugin
	for PCTOOLS.
	Look at his source code :

	* PRG_AS_PLUGIN   MACRO
	* _main:
	*	bra.s	PLGJp
	*
	*	dc.b    "PLUG"                  ;Signatur
	* param_addr dc.l	0
	* vers:	dc.w	$0120			;Version
	*	dc.w	NB_PLUGINFCT		;Nb of functions
	*	dc.l	PLUGIN_TABLE		;Addr of table
	*	dc.l	EXTENSION_FILTER	;Extension Filter
	*
	* PLGJp:
	*	(...) code of the event loader


EXTENSION FILTER
////////////////
	The extension filter can be used to run the plugin
	ONLY if the user has selected a file with a given
	extension in PCTOOLS.
	The extension are those used by Api92 : the EXT_???
	constant can be found in api92cst.h.

	The format of the extension filter is the following :
	* EXTENSION_FILTER
	*	dc.b [FilterCount],[Filter1],[Filter2]...

	Thus, the extension filter used in LibInfo is :
	* EXTENSION_FILTER:
	*	dc.b	3,EXT_EXE,EXT_LIB,EXT_PLUG
	The plugin will be run ONLY if the user has selected
	a EXE file, a library or a plugin.

	However, you can not use the extension filter. See in
	apd.xas. You will found something like that :
	* EXTENSION_FILTER:
	*	dc.b	0
	And your plugin will be always run.


THE PLUGIN TABLE
////////////////
	The plugin table is the table that describes
	all the intercepted events.
	It has the following format :
	* PLUGIN_TABLE:
	*	dc.l	NOT_USED		;start_of_pct
	*	dc.l	NOT_USED		;end_of_pct
	*	dc.l	KeyPressed		;key_pressed
	*	dc.l	NOT_USED		;key_pressed_first
	*	dc.l	NOT_USED		;enter_pressed
	*	dc.l	NOT_USED		;cursor_moved
	*	dc.l	NOT_USED		;draw_item
	*	dc.l	MenuString		;plugin_menu_string
	*	dc.l	MenuFunction		;plugin_menu_function
	*	dc.l	NOT_USED		;compression_service
	* 	dc.l	NOT_USED		;use_menu
	* END_PLUGIN_TABLE:

	If your plugin is supposed to intercept one of these
	function, you put its label name. Else you put NOT_USED.

	Notice that the plugin_menu_string entry is a special
	one. It doesn't point to a subroutine, but to the
	address of a string. This string will be show in the
	Plugin menu of PCTOOLS. You can see there is nothing
	more easy than to appear in the Plugin menu of PCTOOLS!


HOW TO PROGRAM PLUGIN SUBROUTINES
/////////////////////////////////
	Each time a plugin subroutine is executed, a0.l
	will point to a PluginParameters structure.

	Here is its format :
	* 00.l	:	Usable by the user to pass/return a value
	* 04.w	:	Zero based index of selected item
	*		in the list buffer
	* 06.w	: 	Zero based index of selected item on
	*		the screen
	* 08.l	:	Address of current STYLE structure
	*		used by PCTOOLS
	* 0C.w	:	Handle of current buffered list
	* 0E.w	:	Handle of current real list
	* 10.w	:	Handle of selected item
	* 12.l	:	reserved, for futur functions
	* 14.l	:	reserved, for futur functions
	* 18.l	:	reserved, for futur functions

	It enables your plugin event handler to know what
	are the conditions of the interception.

	Be careful : PCTOOLS doesn't use directly the
	VAT. It uses a buffer (with exactly the same format
	of the VAT) where are stored all showed variables.
	(it can change according to filters, order, ... )
	The PluginParameters structure gives the buffer handle,
	and also the handle of real VAT used by the buffer.

	It you want some information about this PluginParameter
	structure, don't hesitate, mail-me.

	!! Important !!
 	Plugin subroutines MUST be terminated using the rtplugin
	macro like that : rtplugin [value]

	The different values that a plugin can return are 
	* SKIP_PCTPROCESS :	it will skip the PCTOOLS standard
				function
	* REDRAW_SCREEN :	Require to redraw the whole screen
 	* REDRAW_LIST :		Require to redraw only the list
				area. (faster than REDRAW_SCREEN)
	* SKIP_NEXTPLUGINS :	Don't execute next plugins



CONCLUSION
//////////
	I am sure that the best way to program plugins is
	to look at existing sources. 
	What is more, it is very very easy. There is nothing
	difficult in programming plugins. 

	In all case, don't hesitate to mail-me at :
		> benoitscherrer@gmail.com <


---------------------------------------------------------------
	Ibrahim - Benoit SCHERRER
	NeXO Software
	mail: benoitscherrer@gmail.com