@database "commodities"

@Node Main "commodities.doc"
@toc "Includes_&_Autodocs/Main"
    @{" ActivateCxObj() " Link "ActivateCxObj()"}
    @{" AddIEvents() " Link "AddIEvents()"}
    @{" AttachCxObj() " Link "AttachCxObj()"}
    @{" ClearCxObjError() " Link "ClearCxObjError()"}
    @{" CreateCxObj() " Link "CreateCxObj()"}
    @{" CxBroker() " Link "CxBroker()"}
    @{" CxMsgData() " Link "CxMsgData()"}
    @{" CxMsgID() " Link "CxMsgID()"}
    @{" CxMsgType() " Link "CxMsgType()"}
    @{" CxObjError() " Link "CxObjError()"}
    @{" CxObjType() " Link "CxObjType()"}
    @{" DeleteCxObj() " Link "DeleteCxObj()"}
    @{" DeleteCxObjAll() " Link "DeleteCxObjAll()"}
    @{" DisposeCxMsg() " Link "DisposeCxMsg()"}
    @{" DivertCxMsg() " Link "DivertCxMsg()"}
    @{" EnqueueCxObj() " Link "EnqueueCxObj()"}
    @{" InsertCxObj() " Link "InsertCxObj()"}
    @{" InvertKeyMap() " Link "InvertKeyMap()"}
    @{" MatchIX() " Link "MatchIX()"}
    @{" ParseIX() " Link "ParseIX()"}
    @{" RemoveCxObj() " Link "RemoveCxObj()"}
    @{" RouteCxMsg() " Link "RouteCxMsg()"}
    @{" SetCxObjPri() " Link "SetCxObjPri()"}
    @{" SetFilter() " Link "SetFilter()"}
    @{" SetFilterIX() " Link "SetFilterIX()"}
    @{" SetTranslate() " Link "SetTranslate()"}
@EndNode

@Node "ActivateCxObj()" "commodities.library/ActivateCxObj"

@{b}   NAME@{ub}
	ActivateCxObj -- change the activation state of a commodity object.
			 (V36)

@{b}   SYNOPSIS@{ub}
	previous = ActivateCxObj(co,true);
	D0			 A0 D0

	@{"LONG" Link "includes/exec/types.h/Main" 35} ActivateCxObj(CxObj *,LONG);

@{b}   FUNCTION@{ub}
	Commodity objects of all types maintain an activation state.
	If an object is "active", then it performs its particular action
	whenever a commodity message arrives. If the object is "inactive"
	no action is taken, and the message goes on to its next destination.

	All objects are created in the "active" state except brokers
	which are created "inactive". Thus, after you create your
	broker and hang a tree of objects off of it, you must remember
	to use this function to activate it. This causes it to divert all
	messages to your tree of objects.

	This function activates 'co' if 'true' is different than 0. and
	deactivates it otherwise. The previous activation state is
	returned.

@{b}   INPUTS@{ub}
	co - the commodity object to affect (may be NULL)
	true - 0 to deactivate the object, anything else to activate it

@{b}   RESULTS@{ub}
	previous - the previous activation state: 0 if the object was
		   inactive or if 'co' was NULL, anything else if the object
		   was active

@{b}   SEE ALSO@{ub}
	@{"CxBroker()" Link "CxBroker()"}

@EndNode

@Node "AddIEvents()" "commodities.library/AddIEvents"

@{b}   NAME@{ub}
	AddIEvents -- add input events to commodities' input stream. (V36)

@{b}   SYNOPSIS@{ub}
	AddIEvents(events)
		   A0

	VOID AddIEvents(struct @{"InputEvent" Link "includes/devices/inputevent.h/Main" 256} *);

@{b}   FUNCTION@{ub}
	This function adds a null-terminated linked list of input events to
	the input stream processed by commodities. It is a touch easier than
	using the input device directly.

	The contents of the input events are copied into commodity messages,
	so they may be disposed of as soon as this call returns.

	The messages are initially routed to the first broker in
	commodities' object list.

@{b}   INPUTS@{ub}
	events - the list of input events to add (may be NULL)

@{b}   WARNING@{ub}
	The @{"cx_lib/InvertString()" Link "amiga_lib/InvertString()"} function creates lists of input events that
	are in reverse order. Thus, passing the result of @{"InvertString()" Link "amiga_lib/InvertString()"}
	to this function will insert a series of input events that will
	generate a string that's a mirror image of the string passed to
	@{"InvertString()" Link "amiga_lib/InvertString()"} originally.

	The solution to the above is to either flip the string before
	passing it to @{"InvertString()" Link "amiga_lib/InvertString()"}, or flip the resulting list of input
	events.

@{b}   BUGS@{ub}
	Prior to V40, this function did not copy the data pointed to by
	ie_EventAddress for any events of type IECLASS_NEWPOINTERPOS.

@{b}   SEE ALSO@{ub}
	@{"cx_lib/FreeIEvents()" Link "amiga_lib/FreeIEvents()"}

@EndNode

@Node "AttachCxObj()" "commodities.library/AttachCxObj"

@{b}   NAME@{ub}
	AttachCxObj -- attach a commodity object to the end of an existing
		       list of objects. (V36)

@{b}   SYNOPSIS@{ub}
	AttachCxObj(headObj,co);
		    A0      A1

	VOID AttachCxObj(CxObj *,@{"CxObj" Link "includes/libraries/commodities.h/Main" 74} *);

@{b}   FUNCTION@{ub}
	Adds 'co' to the list of objects pointed to by 'headObj'. The
	new object is added at the end of the list.

@{b}   INPUTS@{ub}
	headObj - pointer to a list of objects. If this value is NULL, then
		  the entire tree of objects pointed to by 'co' is deleted
		  and becomes invalid.
	co - the object to add to the list (may be NULL)

@{b}   RESULTS@{ub}
	If 'co' is NULL, this function will record that fact in the
	internal accumulated error of 'headObj'. This error record
	can be retrieved using @{"CxObjError()" Link "CxObjError()"} and cleared using
	@{"ClearCxObjError()" Link "ClearCxObjError()"}.

@{b}   BUGS@{ub}
	Until V38, passing a NULL 'headObj' parameter would cause low-memory
	access and unpredictable results.

@{b}   SEE ALSO@{ub}
	@{"CxObjError()" Link "CxObjError()"}, @{"ClearCxObjError()" Link "ClearCxObjError()"}

@EndNode

@Node "ClearCxObjError()" "commodities.library/ClearCxObjError"

@{b}   NAME@{ub}
	ClearCxObjError -- clear the accumulated error value of a commodity
			   object. (V36)

@{b}   SYNOPSIS@{ub}
	ClearCxObjError(co);
	      	        A0

	VOID ClearCxObjError(CxObj *);

@{b}   FUNCTION@{ub}
	This function clears the accumulated error value of commodity object
	'co'.

	It is unwise to do this to a filter if COERR_BADFILTER is set.
	This will fool commodities into thinking the filter is OK. Set
	another valid filter, or leave the error value alone.

@{b}   INPUTS@{ub}
	co - the object to affect (may be NULL)

@{b}   SEE ALSO@{ub}
	@{"CxObjError()" Link "CxObjError()"}

@EndNode

@Node "CreateCxObj()" "commodities.library/CreateCxObj"

@{b}   NAME@{ub}
	CreateCxObj -- create a new commodity object. (V36)

@{b}   SYNOPSIS@{ub}
	co = CreateCxObj(type,arg1,arg2);
	D0		 D0   A0   A1

	@{"CxObj" Link "includes/libraries/commodities.h/Main" 74} *CreateCxObj(ULONG,@{"LONG" Link "includes/exec/types.h/Main" 35},LONG);

@{b}   FUNCTION@{ub}
	This function creates a commodity object of type 'type'. It is not
	proper to call this function directly. Each object creation routine
	except @{"CxBroker()" Link "CxBroker()"} is defined as a macro in @{"<libraries/commodities.h>" Link "includes/libraries/commodities.h/Main" 0}
	These are independently documented.

	All functions which operate on a commodity object are made with
	a reference to the thirty-two bit value returned by this function
	(or by @{"CxBroker()" Link "CxBroker()"}).

@{b}   INPUTS@{ub}
	type - the type of object to create as defined in
	       @{"<libraries/commodities.h>" Link "includes/libraries/commodities.h/Main" 0}
	arg1 - first argument, meaning depends on 'type'
	arg2 - second argument, meaning depends on 'type'

@{b}   RESULTS@{ub}
	co - a pointer to the new object or NULL if it could not be created.
	     A NULL return indicates typically a lack of system memory. Minor
	     problems in creating an object, such as providing a bad filter
	     description to @{"cx_lib/CxFilter()" Link "amiga_lib/CxFilter()"}, typically don't cause failure,
	     but are recorded in an internal error field in the new object
	     which can be accessed via @{"CxObjError()" Link "CxObjError()"}.

@{b}   SEE ALSO@{ub}
	@{"CxObjError()" Link "CxObjError()"}, @{"cx_lib/CxFilter()" Link "amiga_lib/CxFilter()"}, @{"cx_lib/CxSender()" Link "amiga_lib/CxSender()"},
	@{"cx_lib/CxSignal()" Link "amiga_lib/CxSignal()"}, @{"cx_lib/CxTranslate()" Link "amiga_lib/CxTranslate()"}, @{"cx_lib/CxDebug()" Link "amiga_lib/CxDebug()"},
	@{"cx_lib/CxCustom()" Link "amiga_lib/CxCustom()"}, @{"CxBroker()" Link "CxBroker()"}

@EndNode

@Node "CxBroker()" "commodities.library/CxBroker"

@{b}   NAME@{ub}
	CxBroker -- create a commodity broker. (V36)

@{b}   SYNOPSIS@{ub}
	broker = CxBroker(nb,error);
	D0		  A0 D0

	@{"CxObj" Link "includes/libraries/commodities.h/Main" 74} *CxBroker(struct @{"NewBroker" Link "includes/libraries/commodities.h/Main" 39} *,@{"LONG" Link "includes/exec/types.h/Main" 35} *);

@{b}   FUNCTION@{ub}
	This function creates a broker from the specification found in the
	@{"NewBroker" Link "includes/libraries/commodities.h/Main" 39} structure pointed to by 'nb'. The purpose and meaning of the
	fields of the @{"NewBroker" Link "includes/libraries/commodities.h/Main" 39} structure are described below. Also see
	@{"<libraries/commodities.h>" Link "includes/libraries/commodities.h/Main" 0} for more info.

	struct @{"NewBroker" Link "includes/libraries/commodities.h/Main" 39}
	{
	    @{"BYTE" Link "includes/exec/types.h/Main" 44}            nb_Version;
	    @{"STRPTR" Link "includes/exec/types.h/Main" 53}          nb_Name;
	    @{"STRPTR" Link "includes/exec/types.h/Main" 53}          nb_Title;
	    @{"STRPTR" Link "includes/exec/types.h/Main" 53}          nb_Descr;
	    WORD            nb_Unique;
	    WORD	    nb_Flags;
	    @{"BYTE" Link "includes/exec/types.h/Main" 44}            nb_Pri;
	    struct @{"MsgPort" Link "includes/exec/ports.h/Main" 27} *nb_Port;
	    WORD            nb_ReservedChannel;
	};

	nb_Version
	This is the way that future versions of commodities can identify
	which version of the @{"NewBroker" Link "includes/libraries/commodities.h/Main" 39} structure you are using. This should be
	set to NB_VERSION as defined in @{"<libraries/commodities.h>" Link "includes/libraries/commodities.h/Main" 0}

	nb_Name
	This is the name of the broker. This name is used to find the broker
	in commodities' object list and is the name shown in the listview
	gadget of the Exchange program. The name string is copied in the
	broker object upon creation so it can be discarded right after
	CxBroker() returns. The maximum length of the name string is defined
	by a constant in @{"<libraries/commodities.h>" Link "includes/libraries/commodities.h/Main" 0}.

	nb_Title, nb_Descr
	These are two strings which appear to the user in the Exchange
	program and describe the application the broker is representing.
	Note that these strings are copied into the broker object so they
	can be discarded right after CxBroker() returns. The maximum length
	of these strings that will be recognized are defined by constants in
	@{"<libraries/commodities.h>" Link "includes/libraries/commodities.h/Main" 0}.

	nb_Unique
	This field indicates what should happen if a broker of the same name
	(nb_Name) already exists in commodities' object list. Constants
	in @{"<libraries/commodities.h>" Link "includes/libraries/commodities.h/Main" 0} allow the caller to specify whether
	another broker is to be created, and whether any existing broker of
	the same name should be notified that an attempt at creating a
	duplicate has been made.

	nb_Pri
	This specifies with what priority the new broker is to be inserted
	within commodities' object list. Higher priority nodes appear
	earlier in a list. It is strongly recommended that the ToolTypes
	environment of an application be used to allow the end-user to set
	the priority of the broker.

@{b}   INPUTS@{ub}
	nb - an initialized @{"NewBroker" Link "includes/libraries/commodities.h/Main" 39} structure
	error - a pointer to a longword where to store a failure code (may be
		NULL)

@{b}   RESULTS@{ub}
	broker - a pointer to the broker object or NULL upon failure. If the
		 'error' pointer is not NULL, a further diagnostic code is
		 placed at that address. Error codes are defined in
		 @{"<libraries/commodities.h>" Link "includes/libraries/commodities.h/Main" 0} and include:

			CBERR_OK
			No problems; broker created OK.

 			CBERR_SYSERR
			System problems, not your fault, sign of low memory.

			CBERR_DUP
			The nb_Unique field specified that only one broker of
			'nb_Name' should be allowed, and one already exists.

			CBERR_VERSION
			The version specified in 'nb_Version' is unknown to the
			library.

@{b}   SEE ALSO@{ub}
	@{"SetCxObjPri()" Link "SetCxObjPri()"}, @{"<libraries/commodities.h>" Link "includes/libraries/commodities.h/Main" 0}

@EndNode

@Node "CxMsgData()" "commodities.library/CxMsgData"

@{b}   NAME@{ub}
	CxMsgData -- obtain a pointer to a commodity message's data area. (V36)

@{b}   SYNOPSIS@{ub}
	data = CxMsgData(cxm);
	D0		 A0

	@{"APTR" Link "includes/exec/types.h/Main" 33} CxMsgData(struct CxMsg *);

@{b}   FUNCTION@{ub}
	Most commodity messages contain meaningful data such as an @{"InputEvent" Link "includes/devices/inputevent.h/Main" 256}
	structure. This function returns a pointer to this data.

	You may get a commodity message from a synchronous (custom object) or
	asynchronous (sender object) source. In the second case, 'data' is
	not valid after you have replied to the message.

@{b}   INPUTS@{ub}
	cxm - the commodity message to get the data pointer from (may be NULL)

@{b}   RESULTS@{ub}
	data - a pointer to the message's data, or NULL if 'cxm' is NULL.
	       The meaning of the data varies depending on which kind of
	       object is being inspected.

@{b}   BUGS@{ub}
	Until V38, passing a NULL 'cxm' parameter would cause low-memory
	access and unpredictable results.

	Until V40, whenever the data pointer is a (struct InputEvent), the
	ie_EventAddress field of these structures was not reliable whenever
	the message was generated by a sender object.

@{b}   SEE ALSO@{ub}
	@{"cx_lib/CxSender()" Link "amiga_lib/CxSender()"}, @{"cx_lib/CxCustom()" Link "amiga_lib/CxCustom()"}

@EndNode

@Node "CxMsgID()" "commodities.library/CxMsgID"

@{b}   NAME@{ub}
	CxMsgID -- obtain the ID of a commodity message. (V36)

@{b}   SYNOPSIS@{ub}
	id = CxMsgID(cxm);
	D0	     A0

	@{"LONG" Link "includes/exec/types.h/Main" 35} CxMsgID(struct CxMsg *);

@{b}   FUNCTION@{ub}
	This function returns the value associated with the cause or source
	of the commodity message 'cxm'. Values are provided by the application
	when a sender or custom object is created.

@{b}   INPUTS@{ub}
	cxm - the commodity message to inquire about (must NOT be NULL)

@{b}   RESULTS@{ub}
	id - if not specified by the application, the ID value of a
	     commodity message will be 0. It is suggested that using
	     non-zero values in your program as a rule may identify some
	     possible errors.

@{b}   SEE ALSO@{ub}
	@{"cx_lib/CxSender()" Link "amiga_lib/CxSender()"}, @{"cx_lib/CxCustom()" Link "amiga_lib/CxCustom()"}

@EndNode

@Node "CxMsgType()" "commodities.library/CxMsgType"

@{b}   NAME@{ub}
	CxMsgType -- obtain the type of a commodity message. (V36)

@{b}   SYNOPSIS@{ub}
	type = CxMsgType(cxm);
	D0		 A0

	ULONG CxMsgType(struct CxMsg *);

@{b}   FUNCTION@{ub}
	This function returns the type of a commodity message. Possible values
	of 'type' are defined in @{"<libraries/commodities.h>" Link "includes/libraries/commodities.h/Main" 0}. Most commodity
	messages are of type CXM_IEVENT.

@{b}   INPUTS@{ub}
	cxm - the commodity message to inquire about (must NOT be NULL)

@{b}   RESULTS@{ub}
@{b}   	type - the type of the commodity message, possible values are defined@{ub}
	       in @{"<libraries/commodities.h>" Link "includes/libraries/commodities.h/Main" 0}

@EndNode

@Node "CxObjError()" "commodities.library/CxObjError"

@{b}   NAME@{ub}
	CxObjError -- obtain a commodity object's accumulated error. (V36)

@{b}   SYNOPSIS@{ub}
	error = CxObjError(co);
	D0		   A0

	@{"LONG" Link "includes/exec/types.h/Main" 35} CxObjError(CxObj *);

@{b}   FUNCTION@{ub}
	When a function acting on an object fails, it records the failure
	in the object. This function returns the accumulated error value.
	The values are represented by flag bits defined in
	@{"<libraries/commodities.h>" Link "includes/libraries/commodities.h/Main" 0}. Several errors may be recorded by multiple
	bits in 'error'.

	The currently defined errors are:

	COERR_ISNULL
	  The value of parameter 'co' was in fact NULL. This error
	  means "the problem with the object you inquire about is
	  that it failed to be created."

  	COERR_NULLATTACH
	  Using the commodities' list manipulation functions, an attempt was
	  made to add a NULL object to the list belonging to 'co'. This allows
	  a line of code as follows to exist in an error-tolerant program:

	    AttachCxObj(filter,CxSender(myport,MY_ID));

  	COERR_BADFILTER
	  The most recent filter specification for a filter object
	  was faulty. This happens if no sense can be made out of a
	  description string, or if an input expression (IX) has an
	  invalid format or version byte. When this bit is set in a
	  filter's error field, the filter will match nothing, but this
	  is not the proper way to "turn off" a filter, use @{"ActivateCxObj()" Link "ActivateCxObj()"}.

  	COERR_BADTYPE
	  A type specific operation, such as @{"SetFilterIX()" Link "SetFilterIX()"}, was called
	  for object 'co', but 'co' isn't of the proper type.

@{b}   INPUTS@{ub}
	co - the commodity object to get the accumulated error from (may be
	     NULL)

@{b}   RESULTS@{ub}
	error - the accumulated error, or 0 if 'co' is NULL

@{b}   SEE ALSO@{ub}
	@{"SetFilter()" Link "SetFilter()"}, @{"SetFilterIX()" Link "SetFilterIX()"}, @{"AttachCxObj()" Link "AttachCxObj()"}, @{"ActivateCxObj()" Link "ActivateCxObj()"},
	@{"ClearCxObjError()" Link "ClearCxObjError()"}

@EndNode

@Node "CxObjType()" "commodities.library/CxObjType"

@{b}   NAME@{ub}
	CxObjType -- obtain the type of a commodity object. (V36)

@{b}   SYNOPSIS@{ub}
	type = CxObjType(co);
	D0		 A0

	ULONG CxObjType(CxObj *);

@{b}   FUNCTION@{ub}
	This function should not really be necessary. It returns
	the type of a commodity object, which you should already
	know, since you created it in the first place.

@{b}   INPUTS@{ub}
	co - the commodity object to inquire about (may be NULL)

@{b}   RESULTS@{ub}
	type - the type of the commodity object, possible values are
	       defined in @{"<libraries/commodities.h>" Link "includes/libraries/commodities.h/Main" 0}. Returns CX_INVALID
	       if 'co' is NULL.

@{b}   SEE ALSO@{ub}
	@{"CreateCxObj()" Link "CreateCxObj()"}

@EndNode

@Node "DeleteCxObj()" "commodities.library/DeleteCxObj"

@{b}   NAME@{ub}
	DeleteCxObj -- delete a commmodity object. (V36)

@{b}   SYNOPSIS@{ub}
	DeleteCxObj(co);
	            A0

	VOID DeleteCxObj(CxObj *);

@{b}   FUNCTION@{ub}
	Deletes a commodity object of any type. If the object
	is linked into a list, it is first removed. Note that
	the handle 'co' is invalid after this function is called.

	Also note that deleting an object which has other objects attached
	to it may be undesirable. Use the function @{"DeleteCxObjAll()" Link "DeleteCxObjAll()"}
	to delete an entire sub-tree of objects.

@{b}   INPUTS@{ub}
	co - the commodity object to delete (may be NULL)

@{b}   SEE ALSO@{ub}
	@{"DeleteCxObjAll()" Link "DeleteCxObjAll()"}

@EndNode

@Node "DeleteCxObjAll()" "commodities.library/DeleteCxObjAll"

@{b}   NAME@{ub}
	DeleteCxObjAll -- recursively delete a tree of commodity objects.
			  (V36)

@{b}   SYNOPSIS@{ub}
	DeleteCxObjAll(co);
		       A0

	VOID DeleteCxObjAll(CxObj *);

@{b}   FUNCTION@{ub}
	This function deletes the commodity object 'co', and
	recursively deletes all objects attached to it, and the
	objects attached to them, etc.

	If 'co' is linked into a list, it is first removed. Note
	that the handle 'co' is invalid after this function is called.

	This function is useful when an application exits: most
	applications can clean up completely by deleting the
	entire sub-tree of objects starting at their broker.

@{b}   INPUTS@{ub}
	co - the first commodity object to delete (may be NULL)

@{b}   SEE ALSO@{ub}
	@{"DeleteCxObj()" Link "DeleteCxObj()"}

@EndNode

@Node "DisposeCxMsg()" "commodities.library/DisposeCxMsg"

@{b}   NAME@{ub}
	DisposeCxMsg -- delete a commodity message. (V36)

@{b}   SYNOPSIS@{ub}
	DisposeCxMsg(cxm);
		     A0

	VOID DisposeCxMsg(struct CxMsg *);

@{b}   FUNCTION@{ub}
	This function eliminates the commodity message pointed to by 'cxm'.
	Can be used to 'swallow' input events by disposing of every commodity
	message of type CXM_IEVENT.

	This function can only be called from within a custom object running
	on the input handler's context. It cannot be called from code running
	on a commodities' context, such as when receiving a CXM_IEVENT message
	from a sender object. CxMsg sent to a commodity program from a sender
	object must be sent back using @{"ReplyMsg()" Link "exec/ReplyMsg()"}.

@{b}   INPUTS@{ub}
	cxm - the commodity message to delete (must NOT be NULL)

@EndNode

@Node "DivertCxMsg()" "commodities.library/DivertCxMsg"

@{b}   NAME@{ub}
	DivertCxMsg -- send a commodity message down an object list. (V36)

@{b}   SYNOPSIS@{ub}
	DivertCxMsg(cxm,headObj,returnObj);
		    A0  A1      A2

	VOID DivertCxMsg(struct CxMsg *,@{"CxObj" Link "includes/libraries/commodities.h/Main" 74} *,@{"CxObj" Link "includes/libraries/commodities.h/Main" 74} *);

@{b}   FUNCTION@{ub}
	This function sends the commodity message 'cxm' down the list of
	objects attached to 'headObj'. The pointer 'returnObj' is first
	pushed onto the routing stack of 'cxm' so that when the end of the
	list of 'headObj' is reached the SUCCESSOR of 'returnObj' is the
	next destination.

	For example, when a filter finds a match with a message, the
	message is diverted down the filter's list like this:

	  DivertCxMsg(cxm,filter,filter);

@{b}   INPUTS@{ub}
	cxm - the commodity message to divert (must NOT be NULL)
	headObj - the list of objects to divert the message to
	returnObj - the object to use as a place holder

@{b}   SEE ALSO@{ub}
	@{"RouteCxMsg()" Link "RouteCxMsg()"}

@EndNode

@Node "EnqueueCxObj()" "commodities.library/EnqueueCxObj"

@{b}   NAME@{ub}
	EnqueueCxObj -- insert a commodity object within a list of objects
		        based on object priority. (V36)

@{b}   SYNOPSIS@{ub}
	EnqueueCxObj(headObj,co);
		     A0      A1

	VOID EnqueueCxObj(CxObj *,@{"CxObj" Link "includes/libraries/commodities.h/Main" 74} *);

@{b}   FUNCTION@{ub}
	This function puts object 'co' into the list of object 'headObj'.
	The insertion point is determined by the object's priority. The
	objects are kept in the list from the highest priority to the
	lowest. New nodes are inserted in front of the first node with a
	lower priority. Hence a FIFO queue for nodes of equal priority.

	The priority of the commodity object can be set using @{"SetCxObjPri()" Link "SetCxObjPri()"}.

@{b}   INPUTS@{ub}
	headObj - pointer to a list of objects. If this value is NULL, then
		  the entire tree of objects pointed to by 'co' is deleted
		  and becomes invalid.
	co - the object to add to the list (may be NULL)

@{b}   RESULTS@{ub}
	If 'co' is NULL, this function will record that fact in the
	internal accumulated error of 'headObj'. This error record
	can be retrieved using @{"CxObjError()" Link "CxObjError()"} and cleared using
	@{"ClearCxObjError()" Link "ClearCxObjError()"}.

@{b}   BUGS@{ub}
	Until V38, passing a NULL 'headObj' parameter would cause low-memory
	access and unpredictable results.

@{b}   SEE ALSO@{ub}
	@{"SetCxObjPri()" Link "SetCxObjPri()"}, @{"CxObjError()" Link "CxObjError()"}, @{"ClearCxObjError()" Link "ClearCxObjError()"}

@EndNode

@Node "InsertCxObj()" "commodities.library/InsertCxObj"

@{b}   NAME@{ub}
	InsertCxObj -- insert a commodity object in a list after a given
		       object. (V36)

@{b}   SYNOPSIS@{ub}
	InsertCxObj(headObj,co,pred);
		    A0      A1 A2

	VOID InsertCxObj(CxObj *,@{"CxObj" Link "includes/libraries/commodities.h/Main" 74} *,@{"CxObj" Link "includes/libraries/commodities.h/Main" 74} *);

@{b}   FUNCTION@{ub}
	Adds 'co' to the list of objects pointed to by 'headObj' after
	object 'pred'.

@{b}   INPUTS@{ub}
	headObj - pointer to a list of objects. If this value is NULL, then
		  the entire tree of objects pointed to by 'co' is deleted
		  and becomes invalid.
	co - the object to add to the list (may be NULL)
	pred - the object after which 'co' should be inserted. If this is NULL
	       then 'co' is added to the head of the list.

@{b}   RESULTS@{ub}
	If 'co' is NULL, this function will record that fact in the
	internal accumulated error of 'headObj'. This error record
	can be retrieved using @{"CxObjError()" Link "CxObjError()"} and cleared using
	@{"ClearCxObjError()" Link "ClearCxObjError()"}.

@{b}   BUGS@{ub}
	Until V38, passing a NULL 'headObj' parameter would cause low-memory
	access and unpredictable results.

@{b}   SEE ALSO@{ub}
	@{"CxObjError()" Link "CxObjError()"}, @{"ClearCxObjError()" Link "ClearCxObjError()"}

@EndNode

@Node "InvertKeyMap()" "commodities.library/InvertKeyMap"

@{b}   NAME@{ub}
	InvertKeyMap -- generate an input event from an ANSI code. (V36)

@{b}   SYNOPSIS@{ub}
	success = InvertKeyMap(ansiCode,event,km)
	D0	 	       D0       A0    A1

	@{"BOOL" Link "includes/exec/types.h/Main" 68} InvertKeyMap(ULONG,struct @{"InputEvent" Link "includes/devices/inputevent.h/Main" 256} *,struct @{"KeyMap" Link "includes/devices/keymap.h/Main" 20} *);

@{b}   FUNCTION@{ub}
	This function uses the system call @{"MapANSI()" Link "keymap/MapANSI()"} to figure out what
	@{"InputEvent" Link "includes/devices/inputevent.h/Main" 256} translates to an ANSI character code 'ansiCode'. The
	@{"InputEvent" Link "includes/devices/inputevent.h/Main" 256} pointed to by 'event' is filled in with that information.
	The @{"KeyMap" Link "includes/devices/keymap.h/Main" 20} 'km' is used for the translation, unless it is NULL, in
	which case the current system default keymap is used.

@{b}   INPUTS@{ub}
	ansiCode - the ANSI code to convert to an input event
	event - the @{"InputEvent" Link "includes/devices/inputevent.h/Main" 256} to fill-in
	km - the keymap to use for the translation, or NULL to use the
	     current system default keymap.

@{b}   RESULTS@{ub}
	success - TRUE if the translation worked, FALSE otherwise.

@{b}   BUGS@{ub}
	This function currently handles one-deep dead keys (such as
	<alt f>o ). It does not look up the high key map (keystrokes
	with scan codes greater than 0x40).

	Prior to V40, this function was not initializing the ie_SubClass
	and ie_TimeStamp fields of the @{"InputEvent" Link "includes/devices/inputevent.h/Main" 256} structure. A simple work
	around to the problem is to clear these values to 0 before making
	a call to this function:

		struct @{"InputEvent" Link "includes/devices/inputevent.h/Main" 256} ie;

		    ie.ie_SubClass           = 0;
		    ie.ie_TimeStamp.tv_secs  = 0;
		    ie.ie_TimeStamp.tv_micro = 0;
		    if (InvertKeyMap(ansiCode,&ie,NULL))
		    ...

@{b}   SEE ALSO@{ub}
	@{"cx_lib/InvertString()" Link "amiga_lib/InvertString()"}

@EndNode

@Node "MatchIX()" "commodities.library/MatchIX"

@{b}   NAME@{ub}
	MatchIX -- see if an input event matches an initialized input
		   expression. (V38)

@{b}   SYNOPSIS@{ub}
	match = MatchIX(event,ix);
	D0		A0    A1

	@{"BOOL" Link "includes/exec/types.h/Main" 68} MatchIX(struct @{"InputEvent" Link "includes/devices/inputevent.h/Main" 256} *,IX *);

@{b}   FUNCTION@{ub}
	This function determines whether an input event matches an
	initialized input expression. Applications generally do not
	need to call this function as filter objects will normally provide
	all the event filtering needed. Nevertheless, MatchIX()
	can come in handy as it is the same function used to match an
	event to the various filter objects when an event makes its way
	through the input network.

@{b}   INPUTS@{ub}
	event - the input event to match against the input expression
	ix - the input expression for the comparison

@{b}   RESULTS@{ub}
	match - TRUE if the input event matches the input expression, or
		FALSE if not

@{b}   SEE ALSO@{ub}
	@{"<libraries/commodities.h>" Link "includes/libraries/commodities.h/Main" 0}, @{"ParseIX()" Link "ParseIX()"}

@EndNode

@Node "ParseIX()" "commodities.library/ParseIX"

@{b}   NAME@{ub}
	ParseIX -- initialize an input expression given a description string.
		   (V36)

@{b}   SYNOPSIS@{ub}
	failureCode = ParseIX(description,ix);
	D0		      A0          A1

	@{"LONG" Link "includes/exec/types.h/Main" 35} ParseIX(STRPTR,IX *);

@{b}   FUNCTION@{ub}
	Given an input description string and an allocated input
	expression, sets the fields of the input expression to
	correspond to the description string.

@{b}   INPUTS@{ub}
	description - the string to parse
	ix - the input expression to hold the result of the parse

@{b}   RESULTS@{ub}
	failureCode -  0 if all went well,
		      -1 if tokens after end (code spec)
	              -2 if 'description' was NULL

@{b}   SEE ALSO@{ub}
	@{"<libraries/commodities.h>" Link "includes/libraries/commodities.h/Main" 0}, @{"MatchIX()" Link "MatchIX()"}

@EndNode

@Node "RemoveCxObj()" "commodities.library/RemoveCxObj"

@{b}   NAME@{ub}
	RemoveCxObj -- remove a commodity object from a list. (V36)

@{b}   SYNOPSIS@{ub}
	RemoveCxObj(co);
		    A0

	VOID RemoveCxObj(CxObj *);

@{b}   FUNCTION@{ub}
	This function removes 'co' from any list it may be a part of.
	Will not crash if 'co' is NULL, or if it has not been inserted
	in a list.

@{b}   INPUTS@{ub}
	co - the object to remove (may be NULL)

@{b}   SEE ALSO@{ub}
	@{"AttachCxObj()" Link "AttachCxObj()"}, @{"EnqueueCxObj()" Link "EnqueueCxObj()"}, @{"InsertCxObj()" Link "InsertCxObj()"}

@EndNode

@Node "RouteCxMsg()" "commodities.library/RouteCxMsg"

@{b}   NAME@{ub}
	RouteCxMsg -- set the next destination of a commodity message. (V36)

@{b}   SYNOPSIS@{ub}
	RouteCxMsg(cxm,co);
		   A0  A1

	VOID RouteCxMsg(struct CxMsg *,@{"CxObj" Link "includes/libraries/commodities.h/Main" 74} *);

@{b}   FUNCTION@{ub}
	Establishes the next destination of a commodity message
	to be 'co', which must be a valid commodity object, and
	must be linked in ultimately to commodities' object list.

	Routing of an object is analogous to a 'goto' in a program.
	There is no effect on the message's routing stack.

@{b}   INPUTS@{ub}
	cxm - the commodity message to route (must NOT be NULL)
	co - the commodity object to route the message to (must NOT be NULL)

@{b}   SEE ALSO@{ub}
	@{"DivertCxMsg()" Link "DivertCxMsg()"}

@EndNode

@Node "SetCxObjPri()" "commodities.library/SetCxObjPri"

@{b}   NAME@{ub}
	SetCxObjPri -- set the priority of a commodity object. (V36)

@{b}   SYNOPSIS@{ub}
	oldPri = SetCxObjPri(co,pri)
	D0                   A0 D0

	@{"LONG" Link "includes/exec/types.h/Main" 35} SetCxObjPri(CxObj *,LONG);

@{b}   FUNCTION@{ub}
	This function sets the priority of a commodity object for the
	purposes of @{"EnqueueCxObj()" Link "EnqueueCxObj()"}.

	It is strongly recommended that the ToolTypes environment be
	utilized to provide end-user control over the priority of
 	brokers, but application specific ordering of other objects
	within their lists is not dictated.

@{b}   INPUTS@{ub}
	co - the commodity object to affect (may be NULL)
	pri - the object's new priority in the range -128 to +127. A value
	      of 0 is normal.

@{b}   RESULTS@{ub}
	oldPri - the previous priority of the object or 0 if 'co' was NULL.
		 This value is only returned in V38 and beyond.

@{b}   BUGS@{ub}
	This function will not reposition an object within its list when
	its priority changes. To attain the same effect, first remove the
	object from its list using @{"RemoveCxObj()" Link "RemoveCxObj()"}, set its priority using
	SetCxObjPri(), and reinsert it in the list using @{"EnqueueCxObj()" Link "EnqueueCxObj()"}.

@{b}   SEE ALSO@{ub}
	@{"EnqueueCxObj()" Link "EnqueueCxObj()"}

@EndNode

@Node "SetFilter()" "commodities.library/SetFilter"

@{b}   NAME@{ub}
	SetFilter -- change the matching condition of a commodity filter.
		     (V36)

@{b}   SYNOPSIS@{ub}
	SetFilter(filter,text);
		  A0     A1

	VOID SetFilter(CxObj *,STRPTR);

@{b}   FUNCTION@{ub}
	This function changes the matching condition of a commodity input
	filter to that described by the input description string 'text'.

@{b}   INPUTS@{ub}
	filter - the filter object to affect (may be NULL)
	text - the new matching conditions for the filter

@{b}   RESULTS@{ub}
	The internal error of 'filter' will have the COERR_BADFILTER
	bit set or cleared depending on the failure or success of this
	function.

@{b}   SEE ALSO@{ub}
	@{"SetFilterIX()" Link "SetFilterIX()"}, @{"CxObjError()" Link "CxObjError()"}

@EndNode

@Node "SetFilterIX()" "commodities.library/SetFilterIX"

@{b}   NAME@{ub}
	SetFilterIX -- change the matching condition of a commodity filter.
		       (V36)

@{b}   SYNOPSIS@{ub}
	SetFilterIX(filter,ix);
		    A0     A1

	VOID SetFilterIX(CxObj *,IX *);

@{b}   FUNCTION@{ub}
	This function changes the matching condition of a commodity input
	filter to that described by the binary input expression pointed by
	'ix'.

	Input expressions are defined in @{"<libraries/commodities.h>" Link "includes/libraries/commodities.h/Main" 0}.
	It is important to remember that the first field of the input
	expression structure must indicate which version of the
	input expression structure is being used.

@{b}   INPUTS@{ub}
	filter - the filter object to affect (may be NULL)
	ix - the new matching conditions for the filter

@{b}   RESULTS@{ub}
	The internal error of 'filter' will have the COERR_BADFILTER
	bit set or cleared depending on the failure or success of this
	function.

@{b}   SEE ALSO@{ub}
	@{"SetFilter()" Link "SetFilter()"}, @{"CxObjError()" Link "CxObjError()"}

@EndNode

@Node "SetTranslate()" "commodities.library/SetTranslate"

@{b}   NAME@{ub}
	SetTranslate -- replace a translator object's translation list. (V36)

@{b}   SYNOPSIS@{ub}
	SetTranslate(translator,events);
		     A0         A1

	VOID SetTranslate(CxObj *,struct @{"InputEvent" Link "includes/devices/inputevent.h/Main" 256} *);

@{b}   FUNCTION@{ub}
	This function replaces the translation list of a commodity
	translator object with the linked list starting at 'events'.

	A NULL value for 'events' indicates that the object 'translator'
	should swallow all commodity messages that are sent its way.

	Note that the input events are not copied into commodities' private
	memory, but the value of 'events' is used -- asynchronously to the
	application program -- to find a chain of InputEvents in the
	application's data space. At the time of translation, each input event
	is copied into its own new commodity message.

	The above means that no other commodities' user, nor
	commodities.library itself will be modifying your list of InputEvents.
	On the other hand, your program must not corrupt the input event
	chain that has been presented to a translator.

@{b}   INPUTS@{ub}
	translator - the translator object to affect (may be NULL)
	events - the new input event translation list

@{b}   BUGS@{ub}
	The list of input events manipulated by a translator object is
	inserted in reverse order in the commodities network, and come out
	of the network in reverse order as well. The @{"cx_lib/InvertString()" Link "amiga_lib/InvertString()"}
	function creates lists of input events that are in reverse order so
	they can be used directly with translator objects.

@{b}   SEE ALSO@{ub}
	@{"<devices/inputevent.h>" Link "includes/devices/inputevent.h/Main" 0}, @{"cx_lib/CxTranslate()" Link "amiga_lib/CxTranslate()"}

@EndNode

