Otherware

home *** CD-ROM | disk | FTP | other *** search

/ Otherware / Otherware_1_SB_Development.iso / amiga / programm / libs / lib_coll.lha / COMMODIT.ZOO / Commodities / functions < prev next >

Wrap

Text File | 1987-07-08 | 30.6 KB | 1,181 lines

:bk=0 Commodities Exchange Function Reference v0.3 March 19, 1987 Jim Mackraz, San Jose, California NOTE: Starting with Version 0.3, new functions are added to the end of this file (and appended to the file "funcsummary"). NAME CreateCxObj() CxObj *co = CreateCxObj(type, arg1, arg2); LONG type; LONG arg1; LONG arg2; DESCRIPTION Creates a Commodities Object of type 'type.' It is not proper to call this function directly. Each object creation routine except CxBroker() is defined as a macro in "cxusr.h." The routines are independently documented. Note that the handle returned is a pointer to an abstract type named 'CxObj.' This type is defined as a LONG in "cxusr.h" but internally has more content. The specific size and contents of internal data structures are 'private.' All functions which operate on a Commodities object are made with a reference to the thirty-two bit value returned by this function (or CxBroker()). DIAGNOSTICS A NULL returned value indicates that the requested object could not be created, typically for lack of system memory. Minor problems in creating an object, such as providing a bad filter description to CxFilter(), typically don't cause failure, but are recorded in an internal error field in the new object. SEE ALSO CxObjError(), CxFilter(), CxTypeFilter(), CxSender(), CxSignal(), CxTranslate(), CxDebug(), CxCustom(), CxBroker() NAME CxBroker() CxObj *broker = CxBroker(nb, error); struct NewBroker *nb; LONG *error; DESCRIPTION Creates a broker from the specification found in the NewBroker structure pointed to by 'nb.' The purposes and meaning of the fields are described below. See also the include file "broker.h." struct NewBroker { BYTE nb_Version; BYTE *nb_Name; BYTE *nb_Title; BYTE *nb_Descr; SHORT nb_Unique; BYTE nb_Pri; }; 'nb_Version' is the way that future versions of the Commodities library can identify which version of the NewBroker structure you are using. This should be set to NB_VERSION, defined in "broker.h." 'nb_Name' is a string which is to be the name of the broker Node which is created. This name is application internal, and is used only to find the broker Node in the Commodities Object List. 'nb_Title' and 'nb_Descr' are two strings which appear to the user and describe the application the broker is representing. Note that all strings above are copied into the broker object. The maximum length of these strings that will be recognized are defined by constants in "broker.h." 'nb_Unique' is a field that indicates what should happen if a broker of the same name (nb_Name) already exists in the Commodities Object List. Constants in "broker.h" 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' specifies with what priority in the Commodities Object List that the new broker is to be inserted. Higher priority nodes appear earlier in a list. See "broker.h" for guidelines for priorities of different types of applications. 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. DIAGNOSTICS Returns NULL in the event of failure. If the pointer 'error' is non-null, a further diagnostic code will be placed at that address. Error codes are in "broker.h" and include: CBERR_OK No problems; broker created OK. CBERR_SYSERR System problems, not your fault. Sign of low memory or big problems. CBERR_DUP The nb_Unique field specified that only one broker of 'nb_Name' should be allowed, and one already exists. CBERR_VERSION The field 'nb_Version' is unknown to the running version of "commodities.library." SEE ALSO FindBroker() Brokers and Application Sub-Trees (in Reference Manual) NAME CxFilter() -- MACRO CxObj *filter = CxFilter(description); BYTE *description; DESCRIPTION Creates an input event filter object which matches Commodities Input Messages fitting the 'description' string. If 'description' is NULL, the filter will not match any messages. A filter may be modified by the functions SetFilter(), using a description string, and SetFilterIX(), which takes a binary Input Expression as a parameter. This function is a C-language macro for CreateCxObj(), defined in "cxfunctions.h." DIAGNOSTICS Returns NULL if the function fails, which only occurs if there is no memory for the new filter object. If there is a problem in the description string, the internal error code of the filter object will be set to so indicate. This error code may be interrogated using the function CxObjError(). SEE ALSO CreateCxObj() SetFilter(), SetFilterIX(), CxObjError() Objects and Message (in Reference Manual) Input Expressions and Description Strings Objects and Messages (in Reference Manual) Error Handling (in Reference Manual) NAME CxTypeFilter() -- MACRO CxObj *typef = CxTypeFilter(typemask); LONG typemask; DESCRIPTION Creates a Commodities Object similar to CxFilter(), but one that diverts all Commodities messages whose type, which is always a power of two, matches a bit set in 'typemask.' Values of message types are given in "cxusr.h." This function is a C-language macro for CreateCxObj(), defined in "cxfunctions.h." DIAGNOSTICS Returns NULL if the function fails, which only occurs if there is no memory for the new filter object. If there is a problem in the description string, the internal error code of the filter object will be set to so indicate. This error code may be interrogated using the function CxObjError(). SEE ALSO CreateCxObj() SetFilter(), SetFilterIX(), CxObjError() Object and Messages (in Reference Manual) Input Expressions and Description Strings Error Handling NAME CxSignal() -- MACRO CxObj *signaler = CxSignal(task, signal); struct Task *task; LONG signal; DESCRIPTION This function creates a Commodities signal object. The action of this object on receiving a Commodities message is to send the 'signal' to the 'task.' The caller is responsible for allocating the signal and determining the proper task ID. Note that 'signal' is the signal value as returned by AllocSignal() (example: 3) , not the mask made from that value (i.e., not binary 0000000000001000). This function is a C-language macro for CreateCxObj(), defined in "cxfunctions.h." DIAGNOSTICS Returns NULL if the object could not be created. SEE ALSO CreateCxObj() Objects and Messages (in Reference Manual) exec.library/Signal(), exec.library/AllocSignal(), exec.library/FindTask() NAME CxSender() -- MACRO CxObj *sender = CxSender(port, id) struct MsgPort *port; LONG id; DESCRIPTION This function creates a Commodities sender object. The action of this object on receiving a Commodities message is to copy the Commodities message into a standard Exec Message, to put the value 'id' in the message as well, and to send the message off to the Message Port 'port.' The value 'id' is used so that an application can monitor messages from several senders at a single port. It can be retrieved from the Exec message by using the function CxMsgID(). The value can be a simple integer ID, or a pointer to some application data structure, for example. Note that Exec messages sent by sender objects arrive asynchronously at the destination port. Do not assume anything about the status of the Commodities message which was copied into the Exec message you received. All Exec messages sent to your ports must be replied. Messages may be replied after the sender object has been deleted. This function is a C-language macro for CreateCxObj(), defined in "cxfunctions.h." DIAGNOSTICS Returns NULL if the sender object cannot be created. SEE ALSO CreateCxObj() exec.library/PutMsg(), exec.library/ReplyMsg() CxMsgID() NAME CxTranslate() -- MACRO CxObj *translator = CxTranslate(ie); struct InputEvent *ie; DESCRIPTION This function creates a Commodities 'translate' object. The action of this object on receiving a Commodities message is to replace that message in the commodities network with a chain of Commodities input messages. One new Commodities input message for each input event in the linked list starting at 'ie' (and NULL terminated). The routing information of the new input messages will be copied from the input message they replace. The linked list of input events associated with a translate object can be changed using the SetTranslate() function. If 'ie' is NULL, the null translation occurs: that is, the original commodities input message is disposed, and no others are created to take its place. This function is a C-language macro for CreateCxObj(), defined in "cxfunctions.h." DIAGNOSTICS Returns NULL if the translate object cannot be created. SEE ALSO CreateCxObj() SetTranslate() Commodities Input Messages and Filters NAME CxCustom() -- MACRO CxObj *custom = CxCustom(action, id); LONG (*action)(); LONG id; DESCRIPTION This function creates a custom Commodities object. The action of this object on receiving a Commodities message is to call a function of the application programmer's choice. The function provided ('action') will be passed a pointer to the actual commodities message (in commodities private data space), and will actually execute as part of the input handler system task. Among other things, the value of 'id' can be recovered the message by using the function CxMsgID(). The purpose of this function is two-fold. First, it allows programmers to create Commodities Exchange objects with functionality that was not imagined or chosen for inclusion by the designers. Secondly, this is the only way to act synchronously with Commodities. For further explanation and examples, consult the Reference Manual. This function is a C-language macro for CreateCxObj(), defined in "cxfunctions.h." DIAGNOSTICS Returns NULL if the custom object cannot be created. SEE ALSO CreateCxObj() Custom Objects (in Reference Manual) CxMsgID() NAME CxDebug() -- MACRO CxObj *debugger = CxDebug(id); LONG id; DESCRIPTION This function creates a Commodities debug object. The action of this object on receiving a Commodities message is to print out information about the Commodities message through the Serial port (using the kprintf() routine). The value 'id' will also be displayed. Note that this is a synchronous occurence (the printing is done by the input device task). If screen or file output is desired, using a sender object instead of debug object is necessary, since such output is best done by your application process. This function is a C-language macro for CreateCxObj(), defined in "cxfunctions.h." DIAGNOSTICS Returns NULL if the debug object cannot be created. SEE ALSO CreateCxObj() CxSender() exec_support/kprintf() NAME DeleteCxObj() void DeleteCxObj(co); CxObj *co; DESCRIPTION Deletes a Commodities object of any type. If the object is linked into a list, will first be removed. Note that the handle 'co' is invalid after this function is called. Note also that deleting an object which has other objects attached to it may be undesirable. Use the function DeleteCxObjAll() to delete an entire sub-tree of objects. DIAGNOSTICS None. Possible system crash if fed fiction. SEE ALSO exec.library/Remove() DeleteCxObjAll() NAME DeleteCxObjAll() void DeleteCxObjAll(co); CxObj *co; DESCRIPTION This function deletes the Commodities object 'co,' and also recursively deletes all objects attached to 'co,' and the objects attached to them. If 'co' is linked into a list, it is removed first. 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. DIAGNOSTICS None. Definite system crash if fed fiction. SEE ALSO exec.library/Remove() DeleteCxObj() NAME CxObjType() LONG type = CxObjType(co); CxObj *co; DESCRIPTION This function should not really be necessary. It returns the type of a Commodities object, which you should already know, since you created it in the first place. Values for 'type' are given in "cxusr.h." DIAGNOSTICS The value of 'type' will be CX_INVALID if you pass in a value of NULL for 'co.' If you pass a random value for 'co,' you will get a random answer. SEE ALSO All Commodities object creation routines. NAME ActivateCxObj() LONG previous = ActivateCxObj(co, true); CxObj *co; LONG true; /* Aztec user's take note */ DESCRIPTION Commodities objects of all types maintain an "activation state." If an object is "active," then it performs its particular action whenever a Commodities 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 your broker. This causes it it to divert all messages to your tree of objects. This function activates 'co' if 'true,' and deactivates it otherwise. The previous value of activation is returned: zero for inactive, non-zero for active. DIAGNOSTICS None. SEE ALSO CxBroker() Brokers and Application Sub-Trees (in Reference Manual) NAME SetTranslate() LONG error = SetTranslate(translator, ie); CxObj *translator; struct InputEvent *ie; DESCRIPTION This function replaces the translation list of a Commodities translate object 'translator' with the linked list starting at 'ie.' A null value for 'ie' indicates that the object 'translator' should swallow all Commodities messages that are sent its way. Note that the input events are not copied into Commodities private memory, but the value of ie is used--asynchronously to the application program--to find a chain of InputEvents in the application's data space. At the time of translation, though, each input event is copied into its own new Commodities message. This means that no other Commodities user, nor Commodities 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. DIAGNOSTICS Returns zero if there is no problem, otherwise an error code with values found in "cxusr.h." The only forseeable error could occur if 'translator' was not in fact a translate object. SEE ALSO include:devices/inputevent.h CxTranslate() NAME SetFilter() void SetFilter(filter, text); CxObj *filter; char *text; DESCRIPTION Changes the matching condition of a Commodities input filter to that described by the input description string 'text.' DIAGNOSTICS The internal error of 'filter' will have the COERR_BADFILTER bit set or cleared depending on the failure or success (resp.) of SetFilter(). SEE ALSO SetFilter(), SetFilterIX(), CxObjError() Commodities Input Messages and Filters Input Expressions and Description Strings NAME SetFilterIX() LONG error = SetFilterIX(filter, ix); CxObj *filter; IX *ix; DESCRIPTION Changes the matching condition of a Commodities input filter to that described by the binary input expression pointed by 'ix.' Input expressions are defined in the file "ix.h." It is important to remember that the first field of the input expression structure must indicate which type of version of the input expression structure is being used. See "ix.h." DIAGNOSTICS If 'error' returned is non-zero, it contains an error code from "cxusr.h." SEE ALSO SetFilter(), SetFilterIX(), CxObjError() Commodities Input Messages and Filters Input Expressions and Description Strings NAME ParseIX() LONG failurecode = ParseIX(string, ix); char *string; IX *ix; DESCRIPTION Given an input description string and an allocated, valid input expression, sets the fields of the input expression to correspond to the description string. DIAGNOSTICS CHANGED FOR v0.3!!! Returns zero if the string WAS successfully parsed. Error codes will be formalized later. SEE ALSO Input Expressions and Description Strings NAME CxObjError() LONG error = CxObjError(co); CxObj *co; DESCRIPTION When a function acting on an object fails, it records the failure in the object's internal data. This function returns the accumulated error value. The values are represented by flag bits defined in "cxusr.h." Several errors may be recorded by multiple bits in 'error.' The possible errors (at current writing) 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 in invalid format or version byte. (See "ix.h.") 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(). COERR_BADTYPE A type specific operation, such as SetFilterIX(), was called for object 'co,' but 'co' isn't of the proper type. DIAGNOSTICS Nothing but. SEE ALSO SetFilter(), SetFilterIX(), AttachCxObj(), ActivateCxObj(), ClearCxObjError() NAME ClearCxObjError() void ClearCxObjError(co); CxObj *co; DESCRIPTION Clears the accumulated error value of Commodities object 'co.' It is unwise to do this to a filter if COERR_BADFILTER is set. This will fool the Commodities Exchange into thinking the filter is OK. Set another, valid, filter, or leave it alone. DIAGNOSTICS None. SEE ALSO CxObjError() NAME CxMsgID() LONG id = CxMsgID(cxm); CxMsg *cxm; DESCRIPTION Returns the value associated with the cause or source of the Commodities message 'cxm.' Values are provided by the application when a Sender or Custom object is created. DIAGNOSTICS If not specified by the application, the ID value of a Commodities message will be null. It is suggested that using non-null values in your program as a rule may identify some possible errors. SEE ALSO CxSender() CxCustom() NAME AttachCxObj() void AttachCxObj(headobj, co); CxObj *headobj; CxObj *co; DESCRIPTION Appends object 'co' to the list of object 'headobj,' using the Exec function AddTail(). Returns 'headobj.' DIAGNOSTICS 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() and cleared using ClearCxObjError(). SEE ALSO exec.library/AddTail() Objects and Messages (in Reference Manual) CxObjError(), ClearCxObjError() NAME EnqueueCxObj() void EnqueueCxObj(headobj, co); CxObj *headobj; CxObj *co; DESCRIPTION Puts object 'co' into the list of object 'headobj,' using the Exec function Enqueue(). Returns 'headobj.' This function uses the priority of the Commodities object as a node. This priority can be set using SetCxObjPri(). DIAGNOSTICS If 'co' is null, will record that fact in the internal accumulated error of 'headobj.' This error record can be retrieved using CxObjError() and cleared using ClearCxObjError(). SEE ALSO exec.library/Enqueue() SetCxObjPri() Objects and Messages (in Reference Manual) CxObjError(), ClearCxObjError() NAME InsertCxObj() void InsertCxObj(headobj, co, pred); CxObj *headobj; CxObj *co; CxObj *pred; DESCRIPTION Adds object 'co' to the list of object 'headobj,' using the Exec function Insert(). Returns 'headobj.' As described in the autodocs for exec.library/Insert(), 'co' will be inserted in the list of 'headobj' prior to 'pred.' Even though Insert() doesn't use the list header unless 'pred' is null, calling InsertCxObj() you should always pass a valid 'headobj' and a possibly null 'pred.' DIAGNOSTICS If 'co' is null, this will be recorded in the internal accumulated error of 'headobj.' This error record can be retrieved using CxObjError() and cleared using ClearCxObjError(). SEE ALSO exec.library/Insert() Objects and Messages (in Reference Manual) CxObjError(), ClearCxObjError() NAME RemoveCxObj() void RemoveCxObj(co); CxObj *co; DESCRIPTION Removes Commodities object 'co' from any list he is be a part of. Will not crash if 'co' is null, or if it has not been inserted in a list (and is not corrupted). It is not recommended to remove a broker from the master list. DIAGNOSTICS None. SEE ALSO Objects and Messages (in Reference Manual) NAME SetCxObjPri() void SetCxObjPri(co, pri) CxObj *co; LONG pri; DESCRIPTION This function sets the priority of a Commodities object for the purposes of EnqueueCxObj(). Note that the Commodities list mechanisms are based on Amiga Exec lists, so the priority is recorded as a signed byte. Please keep values in range. A value of zero is usually fine. 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. DIAGNOSTICS None. SEE ALSO ToolTypes and the Commodities Environment (in Reference Manual) EnqueueCxObj() NAME FindBroker() CxObj *broker = FindBroker(name); char *name; DESCRIPTION Looks for a Commodities broker whose node name is 'name' in the Commodities Object List. All uses of this function by applications are highly suspect. DIAGNOSTICS Returns NULL if 'name' not found. SEE ALSO Objects and Messages (in Reference Manual) NAME CxMsgType() ULONG type = CxMsgType(cxm); CxMsg *cxm; DESCRIPTION Returns the type of a Commodities message. Possible values of 'type' are found in "cxusr.h." Most Commodities messages are Input Event messages. DIAGNOSTICS The value NULL should never be returned, if 'cxm' points to a valid message. SEE ALSO NAME CxMsgData() char *contents = CxMsgData(cxm); CxMsg *cxm; DESCRIPTION Most Commodities messages contain meaningful data, such as an InputEvent structure. A pointer to this data may be obtained by using this function. A valid, non-null pointer will always be returned if 'cxm' is valid. You may get a Commodities message from a synchronous (custom object) or asynchronous (sender object) source. In the second case, 'contents' is not valid after you have replied to the message. DIAGNOSTICS If 'cxm' is null, returns NULL. SEE ALSO CxSender() CxCustom() NAME DisposeCxMsg() void DisposeCxMsg(cxm); CxMsg *cxm; DESCRIPTION Eliminates the Commodities message pointed to by 'cxm.' Can be used to 'swallow' InputEvents by disposing of every Commodities message of type CXM_IEVENT. DIAGNOSTICS None. SEE ALSO NAME RouteCxMsg() void RouteCxMsg(cxm, co); CxMsg *cxm; CxObj *co; DESCRIPTION Establishes the next destination of a Commodities message to be 'co,' which must be a valid Commodities object, and must be linked in ultimately to the Commodities Object List. Such a routing of an object is analogous to a 'goto' in a program. There is no effect on the message's routing stack. DIAGNOSTICS None. SEE ALSO DivertCxMsg() NAME DivertCxMsg() void DivertCxMsg(cxm, headobj, returnobj); CxMsg *cxm; CxObj *headobj; CxObj *returnobj; DESCRIPTION Sends Commodities 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);. DIAGNOSTICS None. SEE ALSO Reference Manual NAME HotKey() -- SCANNED LIBRARY CxObj *filter = Hotkey(descr, port, ID); char *descr; struct MsgPort *port; LONG ID; DESCRIPTION This function is not part of "commodities.library," but is in the scanned library cx_support.lib. It creates a triad of Commodities objects to accomplish a high-level function. The three objects are a filter, which is created to match by the call CxFilter(descr), a sender created by the call CxSender(port, ID), and a translator which is created by CxTranslate(NULL), so that it swallows any Commodities input event messages that are passed down by the filter. This is the simple way to get a message sent to your program when the user performs a particular input action. It is strongly recommended that the ToolTypes environment be used to allow the user to specify the input descriptions for your application's hotkeys. DIAGNOSTICS Returns NULL and cleans up after itself if any problems occur creating the objects. It may be wise to test filter using CxObjError() to insure that 'descr' was a valid description. SEE ALSO ToolTypes and the Commodities Environment (in Reference Manual) CxFilter(), CxSender(), CxTranslate(), CxObjError() NAME ArgArray -- SCANNED LIBRARY char **ttypes = ArgArrayInit(argc, argv); int argc; char **argv; DESCRIPTION This function is not part of "commodities.library," but is in "cx_support.lib." ArgArrayInit() returns a null-terminated array of strings suitable for sending to the icon.library function FindToolType(). This array will be the ToolTypes array of the program's icon, if it was started from the workbench. It will be just 'argv' if the program was started from the CLI. NOTE WELL: Your C compiler must null terminate '*argv[]' for this scheme to work. Aztec does, in the version Commodities was developed with. Pass ArgArrayInit() your startup arguments passed to main(). ArgArrayInit() opens the icon.library (even if the caller was started from a CLI, so that the function FindToolType() can be used) and may call GetDiskObject(), so clean up is necessary when the strings are no longer needed. The function ArgArrayDone() does just that. Use of these routines facilitates the use of ToolTypes or command line arguments to control end-user parameters in Commodities applications. For example, a filter used to trap a keystroke for popping up a window might be created by something like this: char *ttypes = ArgArrayInit(argc, argv); CxObj *filter = UserFilter(ttypes, "POPWINDOW", "alt f1"); ... with ... CxObj * UserFilter(tt, action_name, default_descr) char **tt; /* null-terminated (char *(*)[]) */ char *action_name; /* name of your semantic action */ char *default_descr; /* used if user doesn't provide */ { char *desc; desc = FindToolType(tt, action_name); return ( CxFilter(desc? desc: default_descr) ); } In this way the user can assign "alt f2" to the action by entering a tooltype in the programs icon of the form: POPWINDOW=alt f2 or by starting the program from the CLI with like so: myprogram "POPWINDOW=alt f2" DIAGNOSTICS ArgArrayInit() would return NULL if any problems occured. SEE ALSO ArgArrayDone() ArgString() ArgInt() icon.library/FindToolType() cx_support.lib probably will have UserFilter(). NAME ArgArrayDone() --- SCANNED LIBRARY void ArgArrayDone(); DESCRIPTION This function closes the disk object and Icon Library opened by ArgArrayInit(). Don't call this until you are done using the ToolTypes argument strings. DIAGNOSTICS None. SEE ALSO ArgArrayInit() NAME ArgString() --- SCANNED LIBRARY char *string = ArgString(tt, string, defaultstring) char **tt; char *t; char *defaultstring; DESCRIPTION This function looks in the ToolTypes array 'tt' returned by ArgArrayInit() for the entry for 'string' and returns the "value" for 'string.' The entry and value have the standard ToolTypes format such as: ENTRY=Value If an entry for 'string' is not found, the defaultstring will be returned. DIAGNOSTICS None. SEE ALSO ArgArrayInit() NAME ArgInt() --- SCANNED LIBRARY int value = ArgInt(tt, string, defaultval) char **tt; char *t; int defaultval; DESCRIPTION This function looks in the ToolTypes array 'tt' returned by ArgArrayInit() for the entry for 'string' and returns the "value" for 'string.' The entry and value have the standard ToolTypes format such as: ENTRY=Value In the case of this function, value will be passed through 'atoi()' before returning. If an entry for 'string' is not found, the integer 'defaultval' will be returned. DIAGNOSTICS None. SEE ALSO ArgArrayInit() NAME InvertKeyMap() ULONG retval = InvertKeyMap(ansicode, ie, km) ULONG ansicode; struct InputEvent *ie; struct KeyMap *km; DESCRIPTION Figures out what InputEvent translates to an ANSI character code 'ansicode.' The InputEvent pointed to by 'ie' is filled in with that information. The KeyMap 'km' is used, unless it is NULL, in which case the system standard keymap (as defined when commodities.library is initialized) is used. 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), and misses system changes to the default key map. DIAGNOSTICS Returns non-negative value if it worked, less than zero, with error values to be defined in the future. SEE ALSO InvertString() NAME InvertString() -- SCANNED LIBRARY struct InputEvent *InvertString(str, km) char *str; struct KeyMap *km; DESCRIPTION This function returns a linked list of input events which would translate into the string using the keymap 'km' (of the system default keymap if 'km' is NULL). The null-terminated 'str' may contain: -ANSI character codes -backslash escaped characters: \n - return \r - return \t - tab \0 - don't use this, ok? \\ - backslash -a text description of an input event as used by ParseIX(), enclosed in angle brackets. An example is: abc<alt f1>\nhi there. NOTE: you are responsible for freeing the InputEvents that this function allocates. You may use FreeIEvents(). DIAGNOSTICS Returns NULL if there is a problem, most often an illegal description enclosed in angles. SEE ALSO ParseIX() FreeIEvents() NAME AddIEvents() void AddIEvents(ie) struct InputEvent *ie; DESCRIPTION This function adds a null-terminated linked list to the input stream of Commodities. It is a touch easier than using the input device directly. The contents of the input events are copied into Commodities internal messages, so they may be disposed of as soon as this call returns. The messages are initially routed to the first Broker in the Commodities Object List. DIAGNOSTICS None. SEE ALSO FreeIEvents()