:bk=0

	Commodities Exchange Reference Manual 
		version 0.3, March 18, 1987

	This manual and Commodities Exchange were written by Jim Mackraz.

	Copyright 1987, Jim Mackraz.  No part of this manual or
	accompanying software may be sold for profit or included in
	any for-profit product without written authorization from
	the author.

	Free and at-cost distribution of this package is welcome. 
	The source code for "commodities.library" is not to be compiled
	for any reason without written consent of the author.  All users
	of the Commodities Exchange are urged to respect the standards put
	forth in the documentation.


	-----	PREFACE		--------------------------------------------

	This manual is the first draft of the programmer's reference to
	Commodities Exchange.  It accompanies a release which might
	best be called "Alpha 2" but will be referred to as "Version
	0.3."  As the body of the manual describes, every attempt
	has been made to provide a complete system which will enable
	applications to be written in an upwardly compatible way.

	The end of this document contains sort of an Appendix on the
	major improvement of Version 0.3: InvertKeyMap() and the
	improvement to ParseIX().   Also, AddIEvents() is new.
	See also the function descriptions.

	More features and utilities will address new areas.

	The contents of a release are described in a file named README
	on the release disk.

	In addition to this document, required reading includes
	the collected function references, the application #include
	files, and the example applications provided.  Familiarity
	with the input.device, in particular the contents of the
	include file devices/inputevent.h is necessary.  Exec Lists,
	Messages and Message Ports play a fundamental role in the system,
	and must also be understood.  The source for the scanned support
	library, cx_support.lib, is also educational.

	The author wishes to warmly thank Neil Katin for his indispensible
	aid and suggestions, and Andy Finkel for being a patient, yet
	constant encouragement to complete the project.  Also, the team
	at Meridian Software have been very helpful and encouraging.

	The eventual distribution path for commodities.library has
	yet to be determined.  The attempt at a copyright notice
	above is trying to express these intentions:

	-The library may be distributed in object form for free.

	-No one makes money off of this without written consent,
	 which will be quite easily obtained.

	-I don't want the source to the library itself compiled;
	 I want control over that.  Any example application or
	 scanned library function may be freely used for non-for-
	 profit programs.

	-I hope people write programs which handle errors carefully,
	 use the ToolTypes as described, and look real sharp.

	-Later versions of the library and controller may be shareware,
	 but arrangements can be made with anyone wishing to use
	 the library with a commercial product.

	Lastly, I want to encourage all feedback possible.  In particular,
	I would be glad to recommend approaches to your envisioned
	applications, and will enhance the library to support
	needed features as I become aware of them.  This manual is
	also undoubtedly lacking.  Please forgive this first draft and
	feel welcome in giving advice for its revision.

	Please contact me by mail or in person:
		Jim Mackraz
		7101 Rainbow Dr. #8
		San Jose, CA  95129


	-----	INTRODUCTION	-------------------------------------

	Commodities Exchange has as its major component an Amiga
	Exec Library, named "commodities.library."  If this library
	is put in logical volume LIBS:, it can be opened and used
	by application programs to gain access to input in a
	very flexible way.

	In particular, an application of Commodities can monitor the
	Amiga input stream coming from the input.device without using
	an Intuition Window or a Console.  This gives rise to the
	following motivational paragraphs.

	The Amiga computer provides a low-overhead, message-based
	multi-tasking operating environment, complete with a
	multi-threaded DOS and Graphics/Windows environment.  No
	other PC provides this, yet the impact sometimes seems to
	be lost on the personal computing community at large.

	To some degree, this is explained by surrogate multi-tasking
	providing a high degree of satisfaction on popular competitors
	such as the Apple Macintosh and IBM PC.  Small programs
	called Desk Accessories, Pop-Up programs, Resident programs,
	Terminate-and-Stay-Resident programs and the like provide multiple
	application capability, with some limits.

	Technical problems with the ad hoc methods of providing these
	functions on existing microcomputers find their way to the
	user, who must often empirically determine what programs may
	safely coexist, and in what order they must be "loaded."

	Most of the technical problems in writing such programs are
	non-existent on the Amiga.  In particular, using disk
	operating system services in pop-up programs is a black art
	on an IBM PC.  A principle area of difficulty or awkwardness
	is the monitoring of input, be it for the purpose of 
	triggering a pop-up program, performing spelling checking as
	words are typed, or translating keystrokes into sequences.

	On the Amiga, the input problem is fundamentally solved by
	the input.device which provides an endorsed means of adding
	"input handlers."  Unfortunately, without standards, arbitrary
	use of input handlers by uncooperative programs can quickly
	lead to incompatibilities or "load-order dependence" even 
	on the Amiga.  Furthermore, writing input handlers is far
	from trivial, especially using "small model" compilation as
	provided by Aztec C.

	Which brings us to the goal of the Commodities Exchange.
	Commodities consists of a single input handler which precedes
	the Intuition input handler.  Like Intuition, Commodities
	will route input events to multiple applications.  Commodities
	applications typically are interested in input regardless of
	what Window is active, and thus Commodities is used as a
	simple, standardized way of managing the input of a "Resident"
	type program.

	Taken with the standards described in this document for 
	user-specification of the input which triggers an action,
	and for establishing the priority of individual Commodities
	applications, it is hoped that many high-quality, mutually
	co-existent "Resident" programs will be created by the
	amazing Amiga programming community.

	Next we describe the end-user's view of several Commodities
	applications.  The source code for these is provided with
	the release.  These programs together illustrate the most 
	common principles of Commodities, and will serve as examples
	for the rest of this manual.


	-----	SOME EXAMPLES	------------------------------------

	To run any of the following examples, the user must put
	a copy of the file "commodities.library" into his or her
	LIBS: directory, where it will be found when the program
	begins execution.

	All applications below would normally be started from the
	Workbench by opening (double-clicking) their icon.  As we
	shall see, information in the icon is used to configure the
	programs.


	--	IHELP	--

	This application is just in its infancy, I swear.  Its purpose
	is to provide keyboard control of Intuition window operations,
	to lessen (ultimately to eliminate) the need for using the mouse
	while doing keyboard intensive work, such as writing software or
	documents. 
	
	This program was the prime motivation for the Commodities Exchange. 
	It is the author's firm belief that managing a multi-tasking
	user interface is too important a task to assign exclusively to a
	low-bandwidth device such as a mouse.

	Currently, IHelp provides three functions:

	CYCLE -- this function causes the rearmost application window
	on the Workbench to be brought to the front and Activated.

	MAKESMALL -- the active window is shrunk to its minimum dimensions.

	MAKEBIG	-- the active window is made the maximum size possible
	respecting its limits and the edge of the screen.

	Each of these functions is assigned to an input event, typically
	a keystroke such as a function key.  Pressing the proper key
	causes the action to take place regardless of which window
	is active or what use the active window may be making of keyboard
	input.

	In order to allow the user the ability to associate keystrokes
	(or other events) with these actions, the ToolType fields in
	the program (Tool) icon are used.  The user selects (but does
	not open) the icon for IHelp, and selects "Info" from the
	Workbench menu.  The subsequent display allows the addition,
	editing, and deletion of parameter strings called ToolTypes.

	To assign the three functions above to new keystrokes, ToolType
	items are added or edited to read, for example:

	CYCLE=f1
	MAKEBIG=alt f5
	MAKESMALL=shift alt f5

	The icon is saved, and the next time IHelp is loaded these
	keystrokes prescribed by the user will be associated with
	the program's actions.


	--	NOCAPSLOCK	--

	This application is almost invisible to the user.  It monitors
	all keystrokes and insures that the CAPSLOCK key on the keyboard
	never has any effect (regardless of what its little red light
	says).

	The shift keys still function normally, but the frequent annoying
	effects of inadvertant pressing of the CAPSLOCK key are no more.

	This program provides nothing the user would want to change, 
	so no ToolType fields in its icon are used.


	--	AUTOPOINT2	--

	This function was inspired by Jude Katsch's Autopoint, which
	is a program to emulate SunWindows style window activation.

	Whenever the mouse is moved (without a button depressed) this
	program triese to activate the window under the mouse pointer
	if it is not already active.

	The tricky part of this program was to make it work with the
	Workbench Rename gadget, which it does nicely.

	Again, no ToolType fields are used.

	-----	COMMODITIES COMPONENTS	-------------------------------

	The Commodities Exchange consists of several identifiable
	components which we introduce now.


	--	commodities.library	--
	This is an Amiga Exec library which creates an input handler
	when it is initialized.  It provides a large number of functions
	to manipulate Commodities Objects and Messages, the building
	blocks of a Commodities application.  All access to data
	used by this library is done procedurally: no internal data 
	structures are read or modified directly by application programs.

	The functions provided by the library fall into classes:
		-Object Creation/Deletion
		-Object Linking
		-Object Data Access/Modify
		-Object Type-specific Functions
		-Input Event Matching Utilities
		-Message Routing/Disposing

	The library must be opened (using the Exec function OpenLibrary())
	by each Commodities application.

	All parameters to the library, following Amiga library convention,
	are thirty-two bit quantities.  Small-integer users must remember
	that integers and characters are not promoted to thirty-two
	bits by the compiler, so casts must be used.  In particular,
	don't forget to cast boolean and priority values to (LONG).


	--	Controller program	--
	An application program will be used to see the loaded Commodities
	and their functions.  It will be possible to use this program
	to terminate an application.  It is an unrealized design goal
	to write the controller using public information and interface
	functions so that it would be upwardly object compatible.
	In fact, the controller, if it exists at all, is very rudimentary
	at the present time.


	--	Support Scanned Library	--
	A "scanned" library is also provided.  Its name is "cx_support.lib."
	A scanned library contains functions which are linked into the
	executable file of an application.  Included are interface routines
	to commodities.library and some utility functions.  The functions
	are all compatible with Aztec C conventions, and are compiled
	"small code, small data, small integer."


	--	Include Files	--
	Various include files are provided.  For applications, the file
	"cxusr.h" contains the principle information and itself includes
	the other application include files.  The file "cx.h," if you ever
	see it, contains library private data structures and constants
	which are not guaranteed to be compatible from release to release.
	They should not be used by any Commodities applications.

	Assembler versions of the include files don't exist yet.


	--	Source Examples	--
	As mentioned, the source for the programs IHelp, NoCapsLock, and
	AutoPoint2 is provided.


	--	Commodities Applications	--
	You write these.  They open "commodities.library" and perhaps
	use functions in the scanned library.  They create and interconnect
	objects (see below) in such a way that particular events cause
	desired actions or notifications.

	-----	COMMODITIES OVERVIEW	-------------------------------


	--	Objects and Messages	--
	The basic building block is the Commodities Exchange Object,
	or CxObj.  Each object is of some particular 'type' which
	corresponds to the primitive action that occur when a Commodities
	Message arrives at the object.  The objects are connected together
	in a large tree structure and messages corresponding to input events
	rattle down different paths in the tree, triggering different actions
	as they encounter different objects.

	One particular object type is the Custom object, which calls an
	application provided function when a CxMsg arrives, so that
	programmers can provide virtually any function not available with
	the standard CxObj types.

	A Commodities Exchange Message, or CxMsg, corresponds with few
	exceptions to a single Input Event.  When such a message arrives
	at a CxObj, an action takes place.  This action might be
	the sending of an Exec message to an application message port, the
	diversion of the CxMsg down a sub-tree, or the calling of
	an application-provided function. 
	
	All objects can be disabled (inactivated), which inhibits any
	action being taken when a CxMsg arrives.  The message simply
	proceeds along to its default next destination.

	Each CxObj is itself an Exec Node; one finds objects linked
	together in linear lists.  Each object also contains a List
	Header, which we refer to as its "personal list," so branching
	off from any object can be another list.  So although the entire
	linked structure of CxObj's is indeed a tree, there is a definite
	preferred--or default--direction at each node of the tree.

	Starting with a Master List of CxObj's, CxMsg's tend to visit
	every object in a list in turn, but certain objects can divert
	them "90 degrees" whence they head off down another list, normally
	the "personal list" of the CxObj performing the diversion.

	When (and if) the CxMsg reaches the end of a list, it proceeds
	from where it was diverted.  A stack is maintained for
	each CxMsg to record and recover from multiple diversions.


	--	Brokers and Application Sub-Trees	--
	The CxObj's in the Master List are a special lot.  They
	are called Commodities Brokers (get it?) and are typically in
	one-to-one correspondence with application programs.  They
	are "representatives" of the application programs; the
	sub-tree starting with the personal list of a Broker consists
	of the CxObj's created by the application.

	When it is enabled, a Broker will divert ALL CxMsg's it receives
	down its personal list, into the network of objects the
	application has set up.

	Support is provided for preventing the creation of duplicate
	brokers.  This gives the application an easy way of determining
	during its initialization if there is another copy of itself
	already running.  The new copy can terminate, and it can be
	arranged that the existing copy be notified that a restart
	attempt was made.  A resident but dormant pop-up notepad program
	might take such a notification that it should open up a window
	and swing into action.


	--	Standard Objects	--
	The actions performed by CxObj's of the standard types are intended
	to be primitive.  An application wishing to receive an Exec message
	when a particular keystroke occurs must create three CxObj's for
	the task: one to filter the CxMsg's for one corresponding to 
	the keystroke, and attached to its list, a CxObj to send off
	an Exec Message and another (optional) to swallow the CxMsg.

	These three are in addition to the application's (single) broker.

	A filter acts by diverting a select set of CxMsg's down its
	personal list, where they will encounter the other two objects
	who unconditionally perform their action.

	Here is a summary of the CxObj types and a brief description
	of each:

		Broker	--	only CxObj's on Master List
					contain a description of the application
					diverts everything down its personal list
		Filter	--	if CxMsg matches some expression, divert 
		TypeFilter-	if CxMsg has type in specified set, divert
		Signal	--	signals some task when any CxMsg arrives
		Sender	--	sends copy of CxMsg to some port (asynchronous)
		Translate-	replaces CxMsg with a chain of zero or more
					new input event CxMsg's
		Debug	--	dumps message contents to debug device (kprintf)
		Custom	--	calls a programmer-provided function (synchronous)

	There is a more detailed description in the Function Reference
	sections for the functions which create the various types of 
	CxObj.


	--	Custom Objects	--
	Custom objects take a unique action.  They call a function
	provided by the application SYNCHRONOUSLY with the execution of
	the Commodities handler.  The delicacy of this cannot be over-
	emphasized.  The function will execute as part of the input.device
	task.  No DOS or Intuition functions may be called.  Although
	the handoff saves and restores all registers, no assumptions
	can be made about the values of registers upon entry.  For
	Aztec C functions, it is sufficient (and necessary!) to call
	the function geta4() (Aztec provided) to establish the context
	register for the routine.

	All such functions should be kept quick and simple, with a
	MINIMUM of stack usage.  A Custom CxObj is the only way to
	directly modify input events as their CxMsg's proceed
	through the Commodities network, but uses other than that 
	should be thought about long and hard and again.


	--	Input Events and Matching Conditions	--
	As mentioned above, most CxMsgs correspond to InputEvents.
	Now is a good time to reread the Chapter 9, The Input Device,
	in the ROM Kernel Reference Manual, volume 2.  See also
	the include file devices/inputevent.h.

	Each input event which reaches the Commodities handler is neatly
	copied into a CxMsg and sent through the CxObj network.
	If it makes it all the way through (i.e., to the end of the Master
	List) the contents--which may have been changed by some object--
	are copied into an input event and sent along to subsequent
	input handlers, including Intuition, and along to Window
	(i.e., non-Commodities) applications.

	Flow of an input event CxMsg is determined by its interactions
	with filter objects.  Each filter object has a "matching condition"
	assigned by the application which determines which messages will
	be diverted down the filter's personal list (those that match).

	The internal representation of this matching condition is private,
	but can be specified by two mechanisms.  Enhancements and additions
	to these mechanisms can be expected; provisions for upward
	compatibility are made for both.

	We spend some time going through the currently available capabilities
	in some detail, since they have avoided documentation elsewhere.


	-- Input Description Strings --
	NOTE: This material is significantly changed for version 0.3

	These are the character strings found in the ToolTypes fields
	described in the introduction to the sample program IHelp.

	Each string described a subset of input events.

	[class] [{[-](qual | syn)}] [[-]upstroke] [highmap|ansicode]

	which means an optional class (default is RAWKEY), zero or
	more qualifiers, and a mandatory code value,  where "class,"
	"qualifier," and "code" in lower case, from the following list:

	class	-- 	
		one of the strings: 
		rawkey, rawmouse, event, pointerpos, timer, newprefs,
		diskremoved, diskinserted.

		If not specified, the class is taken to be "rawkey."

	qual	--
		one of the strings: 
		shift, rshift, capslock, control, lalt, ralt, lcommand, rcommand,
		numericpad, repeat, midbutton, rbutton, leftbutton, relativemouse,

		A preceding '-' means that the value of the corresponding
		qualifier is to be considered irrelevant.

	syn		-- (synonym)
		one of the strings: shift, caps, alt
		shift	(means "left or right shift"), caps	(means "either shift
		or capslock"), alt (means "either alt key").

	upstroke--	 (literally "upstroke")
		if this token is absent, only downstrokes are considered
		for rawmouse (mousebuttons) and rawkey events.  If it is
		present alone, only upstrokes count.  If it preceded by
		'-' it means that both up and down strokes are included.

	highmap	--
		one of the strings: 
		space, backspace, tab, enter, return, esc, del, up, down,
		right, left, help, f1, f2, f3, f4, f5, f6, f7, f8, f9, f10.

	ansicode --
		a single character token is interpreted as a character code,
		which is looked up in the system default keymap. 

	Examples of strings are:

		"lshift right alt f2"
		"alt shift a"
		"-shift -alt -control help" (help key with or without qualifiers)
		"rawmouse rbutton"		(mouse move with menu button down)

	Enhancements to the grammar are anticipated.  Every attempt
	will be made to be compatibile with the input descriptions
	of the early version.

	--	Input Expressions	--
	Applications can also use a powerful binary specification of
	the matching condition for a filter.  In the future, perhaps
	a more powerful specification may be developed so the data 
	structures for the Input Expressions (type IX) are tagged with
	their version number.  This will allow easy handling of different
	specification types co-existing in a future Commodities
	version.

	The Version 2 IX structure is as follows and the conditions that
	it specifies a match with an InputEvent are described:

	typedef struct {
		UBYTE	ix_Version;
		UBYTE	ix_Class;

		UWORD	ix_Code;
		UWORD	ix_CodeMask;

		UWORD	ix_Qualifier;
		UWORD	ix_QualMask;
		UWORD	ix_QualSame;
	} IX;

	ix_Version -- must be set to the manifest constant IX_VERSION
	found in the same include file ("ix.h") as the structure
	definition.

	ix_Class  -- must exactly equal the ie_Class field of an InputEvent
	to match.

	ix_Code, ix_CodeMask -- for every bit set in ix_CodeMask, the
	state of the corresponding bits in ix_Code and ie_Code in the
	InputEvent must match.  Note that whether a keystroke or mouse
	button action is a down- or upstroke is encoded in the
	ie_Code field of the InputEvent (IE_CODE_UPPREFIX).

	ix_Qualifier, ix_QualMask, ix_QualSame -- the fields ix_QualMask
	and ix_QualMask work in the same way as for the Code: the Mask
	indicates the "do care" bits in ie_Qualifier, with ix_Qualifier
	specifying the required settings for those bits.  The ix_QualSame
	field is used to express simple synonyms in the ie_Qualifier.
	Using this, you can specify that left- and right Shift- are
	equivalent and whether the CAPSLOCK qualifier is also equivalent.
	Left- and right-Alt can also be made equivalent.


	--	Message Routing	--
	So far a few points have come out about routing CxMsg's:

	-In the absence of some action diverting them, after visiting
	 a CxObj, they will proceed to the next node in the same list.

	-They may be diverted down the "personal list" of some CxObj,
	 normally the list belonging to the object doing the diverting.
	 Diverting consists of pushing the address of the current CxObj
	 onto an internal stack and routing to the first CxObj in the list.

	-When they reach the end of a list of CxObj's, the address of a
	 CxObj is popped off of their stack, and they proceed to the
	 Successor of that object.

	 Reaching the end of the Master List sends the CxMsg to an internal
	 "Zero Object" which disposes of the message, first recovering
	 InputEvents from the contents of input event messages.

	Application programs (using Custom Objects) can route a message
	two ways: diverting it down the list of some object, or by routing
	it directly to another object.  Future functions may be provided
	for independently pushing or popping the routing stack.

	Note that it makes no sense and is indicative of greater misunder-
	standing to try to route a message sent to a port by a sender
	CxObj.


	-----	The Examples, Revisited		----------------------------
	With the background so far, it is helpful to consider the object
	structure used by the example programs discussed above.


	-- IHelp --
	IHelp has three "hotkeys."  These are triads of objects discussed
	briefly above.  There is a routine in the support library that
	creates these groups of objects easily.

	A hotkey triad, to review, consists of a filter object, which
	is the "trigger" for the hotkey.  Attached to its personal list
	is a sender which sends a notification message to a port allocated
	by IHelp. 
	
	The ID field of the several senders differ, so that IHelp can
	easily tell from which sender the messages were sent.  IHelp
	pays no attention to the data part of the messages it is sent.

	Following the sender in the personal list of the filter is a
	translator object which translates the trigger CxMsg to NULL,
	in effect swallowing it.

	IHelp, like all good Commodities, has a Broker, and the filter
	objects at the head of the hotkeys are all attached to its list.


	--	NoCapsLock	--
	Attached to the Broker list of this application is a single filter
	which watches for all RAWKEY events which have the CAPSLOCK bit
	set.  It diverts them down its list where a single custom object
	can be found.

	This custom object modifies the InputEvent included in each CxMsg
	it encounters, clearing the CAPSLOCK bit.  It has no effect on
	other Qualifier bits, so even if the CapsLock key is active, the
	shift keys will function normally.


	--	Autopoint2	--
	Attached to the Broker is a single filter, watching for RAWMOUSE
	events with neither mouse button depressed.  CxMsgs carrying such
	events are diverted down to a signal CxObj, which wakes up the
	AutoPoint task.  Once awakened it does magic.

	Note that a signal is just the ticket for this function, saving the
	overhead of creating, sending, and replying to an Exec message.
	

	-----	More Details	----------------------------------------

	--	Error Handling	--
	A well-behaved program must always check that functions which
	create CxObj's succeed, since each object requires some dynamically
	allocated memory.  To make this a little less tedious, it is
	possible to get by testing if entire list of objects was created
	successfully, and to recover gracefully if not.  See the examples.
	And check for and handle all errors, OK?


	--	ToolTypes and the Commodities Environment	--
	Some functions are provided to make it easy to use ToolTypes
	for providing user control over the parameters of your
	application.  Please let the user specify the input description
	for major semantic actions in your programs. 
	
	Also, even if there is no obvious reason in some cases, let the
	user set the priority for your broker.  That is the key step to
	making the functioning of a group of Commodities applications
	independent of the order in which they were loaded.

	Note that the functions provided also support command line
	argument parsing so Commodities can be started from the
	CLI with full user control (this is especially useful for
	starting up a batch of applications from an Execute script file).


	--	Library version	--
	Be sure to specify a non-zero version number to the OpenLibrary()
	call when opening Commodities.  This insures that the end user
	does not use your program with a version of the library that
	doesn't support new features you are depending on.


	--	Terminating a Commodities Application	--
	As is shown in the examples, the proper terminating condition of a
	Commodities application is the receipt of the Control-E break signal.

	This signal will be sent by controller software to the task which
	created a Broker when the user indicates that that Broker's program
	is to be terminated.  It is also easy to send such a signal to 
	a background task started from the CLI.  Use the "Status" command
	to find the tasks CLI ID, and then say "Break task <n> E" where
	<n> is the number from the Status output.

	Developing a Commodities application is made more convenient 
	using this convention (we often test them in the foreground,
	and typing Control-E usually works long before the rest of the
	program), and we also don't waste function keys or other input
	combinations on termination commands.


	--	Pools and Alerts	--
	The internal data structures used by the Commodities library are
	allocated and managed by a common "Pool" mechanism.  Normally,
	this mechanism is invisible to the programmer and end-user.  It
	is used to manage data storage for Commodities objects, messages,
	Exec messages, and InputEvents.

	In the early releases of Commodities, however, this one included,
	a recoverable alert will be put up if a program corrupts the
	secret header of a Commodities data structure, or uses an invalid
	handle in certain operations.  Another recoverable alert is
	posted when commodities.library expunges (which is done when the
	last application closes the library) if all data structures are
	not returned to Commodities before this time.  The frequent
	causes for this are not replying to all the Exec messages Commodities
	senders send to you, and not deleting all the objects that you
	have created.

	To properly reply all Exec messages sent to your program, a sequence
	like that used in IHelp is advised:

		DeleteCxObjAll(broker);
		while (msg = GetMsg(port)) ReplyMsg(msg);
		CloseLibrary(CxBase);


	-----	Future Versions and Compatibility	-------------------
	As stated in the Preface, this version of Commodities Exchange is
	not complete, with a few important things not present.  In this
	section we discuss things to come and compatibility issues.


	-- Controller	--
	Prominent in its absence is the controller application that will
	allow the user to view (the brokers of) all the Commodities
	applications, experiment with their priority, temporarily disable
	them, and terminate them.

	It was a design goal to provide enough procedural interface through
	the library to allow a "legal" application to walk through the
	Commodities object tree and report what it sees, but implementation
	of that interfered with the main functions of the library.

	Until at least a rudimentary controller is made available, Commodities
	applications are best started from the CLI, so that they may be
	terminated by the CLI "Break" command (using the Control-E signal).

	Note that the "ToolTypes" parameter environment can be specified
	on the CLI command line, like so:
		run ihelp "CYCLEBACK=alt shift f5"


	-- User Visible Filters	--
	Another dream for the controller is that it could report on some
	of the hotkeys or other event triggers that an application had
	installed.  This would provide, for example, an easy way for the
	user to see exactly what key cycles the windows in IHelp.

	To accomplish this, an extension will need to be made of the
	Filter, with the application further specifying descriptive text
	for user-visible filters, and whether the user may modify the
	event matching condition, and what restrictions apply to his
	modifications.  Prototypes of this have been played with, but
	the inclusion into the library will have to wait.  Existing
	filters will always be compatible, but even those that should
	be visible to the user never will be.


	--	Active Window Knowledge	--
	It is in the plans to hang another Commodities input handler
	on the input.device handler chain, but FOLLOWING Intuition 
	instead of preceeding (but preceding the Console).

	This would allow a keystroke enhancer to make different translations
	for different windows.  Another use of such a thing would be to
	allow non-interactive programs (i.e., those with no window) be
	informed of a preferences change.

	This will manifest itself as a new flag bit that can be set in
	the NewBroker structure to indicate post-Intuition processing,
	and a new kind of filter which only diverts events if a particular
	window is active.

	Religiously setting all undefined NewBroker.nb_Flags bits to zero
	will insure compatibility with this change.


	--	BindCommodities	--
	In spite of the lack of a controller today, the preferred method
	of starting a Commodities application and establishing a parameter
	environment will be through the use of icons.

	In the meantime, one can start up several Commodities applications
	with a batch file (which can't be run from the start-up script since
	jobs left in the background prevent the Initial CLI from closing).

	When we make it to icons, we will need a way to start up a collection
	of Commodities by referencing their icons.  Neil "Workbench" Katin,
	author also of BindDrivers, pledges a similar program which will 
	start every program with an icon in some specified drawer, with
	their start-up environment being identical to that when started
	from the Workbench.

	Such a program will have myriad uses (starting notepads, etc.) but
	our interest will be in starting a directory full of Commodities
	applications.


	--	Timer Support	--
	Right now, events of type IECLASS_TIMER don't go through the
	Commodities object network, largely because there wasn't time
	to profile the performance of the system, and they are a frequent
	and low-payoff burden.

	A new standard object, the "One-Shot Timer Filter," will someday
	exist, which will be set to some unsigned integer value by the
	application.  Each time a TIMER event passes its way, it will
	decrement the count.  When the count reaches zero, ONE timer
	CxMsg will be diverted down the filter's personal list, and
	the filter will then become dormant until the count is reset.


	--	Profile and Downcode	--
	We don't know how slow this beast is, especially with lots and
	lots of objects.  Existing profilers don't apply to Exec library
	code, and there hasn't been any time to do something about it.

	With the timers eliminated, the author's experience hacking Intuition
	indicates that human-schedule input is pretty slow, and that any
	input-response bottleneck typically occur on the output side of
	the fence.  That is to say, we hope it's fast enough.  There
	are several routines which are prime contestants for assembly
	language downcoding.

	If there is sufficient uproar, we will break apart the library
	interface functions of the scanned library into separate files,
	so that your program will only link in just the interface code
	it needs.


	-- Keystroke Programmers	--
	Although lots of features are present to make writing a keystroke
	macro utility much easier, reports of direct experience returned
	to the author will undoubtedly show areas of needed change.  We
	will try to be most responsive to people forging new ground.


	-- More CxMsg Types	--
	There are only two types of Commodities Messages currently:
	CXM_IEVENT, by far the most common; and CXM_UNIQUE, which notifies
	Brokers who are interested that another attempt was made to start
	their applications.

	More may be coming, perhaps in support of Post-Intuition Commodities.
	Program defensively by not assuming anything about the type of
	a CxMsg unless that message has passed through a filter of some
	sort.


	--	Support for More Languages	--
	Commodities Exchange was developed under Aztec-C, and the scanned
	library cx_support.lib is an Aztec convention, small model library.

	Amiga type naming, as found in exec/types.h, are used exclusively
	in commodities.library, but some 'ints' sneaked into cx_support.lib.

	Support for other compilers, languages, and assembler should be
	done someday.  Particularly lacking are assembler include files.


	--	Documentation	--
	Hopefully, the state of this manual will succumb to revision.

	APPENDIX (for now)

	Three big changes have been added:
	
	The function InvertKeyMap() converts an ANSI character code
	to the InputEvent that maps to it (using KeyMaps).  This function
	is used by the function InvertString() which translates a special
	extension of ANSI character strings into a chain of input events. 

	ParseIX() has been greatly enhances (and tested a little).  See
	the description above, in this document.

	AddIEvents() provides a trivial method of adding a chain of 
	input events to the Input Food Chain starting before Commodities.

	See the function descriptions for more information.
