home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / Misc / TRSICAT.LZX / CATS_CD2_TRSI / Inc&AD2.0 / Text_Autodocs / commodities.doc < prev    next >
Encoding:
Text File  |  1992-09-02  |  24.2 KB  |  853 lines
  1. TABLE OF CONTENTS
  2.  
  3. commodities.library/ActivateCxObj
  4. commodities.library/AddIEvents
  5. commodities.library/AttachCxObj
  6. commodities.library/ClearCxObjError
  7. commodities.library/CreateCxObj
  8. commodities.library/CxBroker
  9. commodities.library/CxMsgData
  10. commodities.library/CxMsgID
  11. commodities.library/CxMsgType
  12. commodities.library/CxObjError
  13. commodities.library/CxObjType
  14. commodities.library/DeleteCxObj
  15. commodities.library/DeleteCxObjAll
  16. commodities.library/DisposeCxMsg
  17. commodities.library/DivertCxMsg
  18. commodities.library/EnqueueCxObj
  19. commodities.library/InsertCxObj
  20. commodities.library/InvertKeyMap
  21. commodities.library/ParseIX
  22. commodities.library/RemoveCxObj
  23. commodities.library/RouteCxMsg
  24. commodities.library/SetCxObjPri
  25. commodities.library/SetFilter
  26. commodities.library/SetFilterIX
  27. commodities.library/SetTranslate
  28. commodities.library/ActivateCxObj           commodities.library/ActivateCxObj
  29.  
  30.    NAME
  31.     ActivateCxObj -- change the activation state of a commodity object.
  32.              (V36)
  33.  
  34.    SYNOPSIS
  35.     previous = ActivateCxObj(co,true);
  36.                  A0 D0
  37.  
  38.     LONG ActivateCxObj(CxObj *,LONG);
  39.  
  40.    FUNCTION
  41.     Commodity objects of all types maintain an "activation state".
  42.     If an object is "active", then it performs its particular action
  43.     whenever a commodity message arrives. If the object is "inactive"
  44.     no action is taken, and the message goes on to its next destination.
  45.  
  46.     All objects are created in the "active" state except brokers
  47.     which are created "inactive". Thus, after you create your
  48.     broker and hang a tree of objects off of it, you must remember
  49.     to use this function to activate it. This causes it to divert all
  50.     messages to your tree of objects.
  51.  
  52.     This function activates 'co' if 'true' is different than 0. and
  53.     deactivates it otherwise. The previous activation state is
  54.     returned.
  55.  
  56.    INPUTS
  57.     co - the commodity object to affect
  58.     true - 0 to deactivate the object, anything else to activate it
  59.  
  60.    RESULTS
  61.     previous - the previous activation state: 0 if the object was
  62.            inactive, anything else if the object was active
  63.  
  64.    SEE ALSO
  65.     CxBroker()
  66.  
  67. commodities.library/AddIEvents                 commodities.library/AddIEvents
  68.  
  69.    NAME
  70.     AddIEvents -- add input events to commodities' input stream. (V36)
  71.  
  72.    SYNOPSIS
  73.     AddIEvents(events)
  74.            A0
  75.  
  76.     VOID AddIEvents(struct InputEvent *);
  77.  
  78.    FUNCTION
  79.     This function adds a null-terminated linked list of input events to
  80.     the input stream of commodities. It is a touch easier than using the
  81.     input device directly.
  82.  
  83.     The contents of the input events are copied into commodity
  84.     messages, so they may be disposed of as soon as this call returns.
  85.  
  86.     The messages are initially routed to the first broker in the
  87.     Commodities Object List.
  88.  
  89.    INPUTS
  90.     events - the list of input events to add
  91.  
  92.    SEE ALSO
  93.     cx_lib/FreeIEvents()
  94.  
  95. commodities.library/AttachCxObj               commodities.library/AttachCxObj
  96.  
  97.    NAME
  98.     AttachCxObj -- attach a commodity object to the end of an existing
  99.                list of objects. (V36)
  100.  
  101.    SYNOPSIS
  102.     AttachCxObj(headObj,co);
  103.             A0      A1
  104.  
  105.     VOID AttachCxObj(CxObj *,CxObj *);
  106.  
  107.    FUNCTION
  108.     Adds 'co' to the list of objects pointed to by 'headObj'. The
  109.     new object is added at the end of the list.
  110.  
  111.    INPUTS
  112.     headObj - pointer to a list of objects
  113.     co - the object to add to the list
  114.  
  115.    RESULTS
  116.     If 'co' is NULL, this function will record that fact in the
  117.     internal accumulated error of 'headObj'. This error record
  118.     can be retrieved using CxObjError() and cleared using
  119.     ClearCxObjError().
  120.  
  121.    SEE ALSO
  122.     CxObjError(), ClearCxObjError()
  123.  
  124. commodities.library/ClearCxObjError       commodities.library/ClearCxObjError
  125.  
  126.    NAME
  127.     ClearCxObjError -- clear the accumulated error value of a commodity
  128.                object. (V36)
  129.  
  130.    SYNOPSIS
  131.     ClearCxObjError(co);
  132.                A0
  133.  
  134.     VOID ClearCxObjError(CxObj *);
  135.  
  136.    FUNCTION
  137.     This function clears the accumulated error value of commodity object
  138.     'co'.
  139.  
  140.     It is unwise to do this to a filter if COERR_BADFILTER is set.
  141.     This will fool commodities into thinking the filter is OK. Set
  142.     another valid filter, or leave the error value alone.
  143.  
  144.    INPUTS
  145.     co - the object to affect
  146.  
  147.    SEE ALSO
  148.     CxObjError()
  149.  
  150. commodities.library/CreateCxObj               commodities.library/CreateCxObj
  151.  
  152.    NAME
  153.     CreateCxObj -- create a new commodity object. (V36)
  154.  
  155.    SYNOPSIS
  156.     co = CreateCxObj(type,arg1,arg2);
  157.              D0   A0   A1
  158.  
  159.     CxObj *CreateCxObj(ULONG,LONG,LONG);
  160.  
  161.    FUNCTION
  162.     This function creates a commodity object of type 'type'. It is not
  163.     proper to call this function directly. Each object creation routine
  164.     except CxBroker() is defined as a macro in <libraries/commodities.h>
  165.     These are independently documented.
  166.  
  167.     All functions which operate on a commodity object are made with
  168.     a reference to the thirty-two bit value returned by this function
  169.     (or by CxBroker()).
  170.  
  171.    INPUTS
  172.     type - the type of object to create as defined in
  173.            <libraries/commodities.h>
  174.        arg1 - first argument, meaning depends on 'type'
  175.     arg2 - second argument, meaning depends on 'type'
  176.  
  177.    RESULTS
  178.     co - a pointer to the new object or NULL if it could not be created.
  179.          A NULL return indicates typically a lack of system memory. Minor
  180.          problems in creating an object, such as providing a bad filter
  181.          description to cx_lib/CxFilter(), typically don't cause failure,
  182.          but are recorded in an internal error field in the new object
  183.          which can be accessed via CxObjError().
  184.  
  185.    SEE ALSO
  186.     CxObjError(), cx_lib/CxFilter(), cx_lib/CxSender(),
  187.     cx_lib/CxSignal(), cx_lib/CxTranslate(), cx_lib/CxDebug(),
  188.     cx_lib/CxCustom(), CxBroker()
  189.  
  190. commodities.library/CxBroker                     commodities.library/CxBroker
  191.  
  192.    NAME
  193.     CxBroker -- create a commodity broker. (V36)
  194.  
  195.    SYNOPSIS
  196.     broker = CxBroker(nb,error);
  197.               A0 D0
  198.  
  199.     CxObj *CxBroker(struct NewBroker *,LONG *);
  200.  
  201.    FUNCTION
  202.     This function creates a broker from the specification found in the
  203.     NewBroker structure pointed to by 'nb'. The purpose and meaning of the
  204.     fields of the NewBroker structure are described below. Also see
  205.     <libraries/commodities.h> for more info.
  206.  
  207.     struct NewBroker
  208.     {
  209.            BYTE            nb_Version;
  210.            BYTE           *nb_Name;
  211.            BYTE           *nb_Title;
  212.            BYTE           *nb_Descr;
  213.            SHORT           nb_Unique;
  214.            BYTE            nb_Pri;
  215.         struct MsgPort *nb_Port;
  216.         WORD            nb_ReservedChannel;
  217.     };
  218.  
  219.     nb_Version
  220.     This is the way that future versions of commodities.library
  221.     can identify which version of the NewBroker structure you are using.
  222.     This should be set to NB_VERSION, defined in <libraries/commodities.h>
  223.  
  224.     nb_Name
  225.     This is the name of the broker. This name is used to find the broker
  226.     in the Commodities Object List and is the name shown in the list
  227.     gadget of the Exchange program. The name string is copied in the
  228.     broker object upon creation, so this string can be discarded right
  229.     after CxBroker() returns. The maximum length of the name string is
  230.     defined by a constant in <libraries/commodities.h>.
  231.  
  232.     nb_Title, nb_Descr
  233.     These are two strings which appear to the user in the Exchange
  234.     program and describe the application the broker is representing.
  235.     Note that these strings are copied into the broker object.
  236.     The maximum length of these strings that will be recognized are
  237.     defined by constants in <libraries/commodities.h>.
  238.  
  239.     nb_Unique
  240.     This field indicates what should happen if a broker of the same name
  241.     (nb_Name) already exists in the Commodities Object List. Constants
  242.     in <libraries/commodities.h> allow the caller to specify whether
  243.     another broker is to be created, and whether any existing broker of
  244.     the same name should be notified that an attempt at creating a
  245.     duplicate has been made.
  246.  
  247.     nb_Pri
  248.     This specifies with what priority the new broker is to be inserted
  249.     within the Commodities Object List. Higher priority nodes appear
  250.     earlier in a list. See <libraries/commodities.h> for guidelines for
  251.     priorities of different types of applications. It is strongly
  252.     recommended that the ToolTypes environment of an application be used
  253.     to allow the end-user to set the priority of the broker.
  254.  
  255.    INPUTS
  256.     nb - an initialized NewBroker structure
  257.     error - a pointer to a longword where to store a failure code, this
  258.         may be NULL
  259.  
  260.    RESULTS
  261.     broker - a pointer to the broker object or NULL upon failure. If the
  262.          'error' is not NULL, a further diagnostic code is placed at
  263.          that address. Error codes are in <libraries/commodities.h> and
  264.          include:
  265.  
  266.             CBERR_OK
  267.                 No problems; broker created OK.
  268.  
  269.              CBERR_SYSERR
  270.                 System problems, not your fault. Sign of low memory or
  271.             big problems.
  272.  
  273.             CBERR_DUP
  274.             The nb_Unique field specified that only one broker of
  275.             'nb_Name' should be allowed, and one already exists.
  276.  
  277.             CBERR_VERSION
  278.             The version specified in 'nb_Version' is unknown to the
  279.             library.
  280.  
  281.    SEE ALSO
  282.     SetCxObjPri(), <libraries/commodities.h>
  283.  
  284. commodities.library/CxMsgData                   commodities.library/CxMsgData
  285.  
  286.    NAME
  287.     CxMsgData -- obtain a pointer to a commodity message's data area. (V36)
  288.  
  289.    SYNOPSIS
  290.     data = CxMsgData(cxm);
  291.              A0
  292.  
  293.     UBYTE *CxMsgData(struct CxMsg *);
  294.  
  295.    FUNCTION
  296.     Most commodity messages contain meaningful data, such as an InputEvent
  297.     structure. This function returns a pointer to this data.
  298.  
  299.     You may get a commodity message from a synchronous (custom object) or
  300.     asynchronous (sender object) source. In the second case, 'data' is
  301.     not valid after you have replied to the message.
  302.  
  303.    INPUTS
  304.     cxm - the commodity message to get the data pointer from
  305.  
  306.    RESULTS
  307.     data - a pointer to the message's data, or NULL if 'cxm' is NULL.
  308.  
  309.    SEE ALSO
  310.     cx_lib/CxSender(), cx_lib/CxCustom()
  311.  
  312. commodities.library/CxMsgID                       commodities.library/CxMsgID
  313.  
  314.    NAME
  315.     CxMsgID -- obtain the ID of a commodity message. (V36)
  316.  
  317.    SYNOPSIS
  318.     id = CxMsgID(cxm);
  319.              A0
  320.  
  321.     LONG CxMsgID(struct CxMsg *);
  322.  
  323.    FUNCTION
  324.     This function returns the value associated with the cause or source
  325.     of the commodity message 'cxm'. Values are provided by the application
  326.     when a sender or custom object is created.
  327.  
  328.    INPUTS
  329.     cxm - the commodity message to inquire about
  330.  
  331.    RESULTS
  332.     id - if not specified by the application, the ID value of a
  333.             commodity message will be 0. It is suggested that using
  334.          non-zero values in your program as a rule may identify some
  335.          possible errors.
  336.  
  337.    SEE ALSO
  338.     cx_lib/CxSender(), cx_lib/CxCustom()
  339.  
  340. commodities.library/CxMsgType                   commodities.library/CxMsgType
  341.  
  342.    NAME
  343.     CxMsgType -- obtain the type of a commodity message. (V36)
  344.  
  345.    SYNOPSIS
  346.     type = CxMsgType(cxm);
  347.              A0
  348.  
  349.     ULONG CxMsgType(struct CxMsg *);
  350.  
  351.    FUNCTION
  352.     This function returns the type of a commodity message. Possible values
  353.     of 'type' are defined in <libraries/commodities.h>. Most commodity
  354.     messages are of type CXM_IEVENT.
  355.  
  356.    INPUTS
  357.     cxm - the commodity message to inquire about
  358.  
  359.    RESULTS
  360.        type - the type of the commodity message, possible values are defined
  361.            in <libraries/commodities.h>
  362.  
  363. commodities.library/CxObjError                 commodities.library/CxObjError
  364.  
  365.    NAME
  366.     CxObjError -- obtain a commodity object's accumulated error. (V36)
  367.  
  368.    SYNOPSIS
  369.     error = CxObjError(co);
  370.                A0
  371.  
  372.     LONG CxObjError(CxObj *);
  373.  
  374.    FUNCTION
  375.     When a function acting on an object fails, it records the failure
  376.     in the object. This function returns the accumulated error value.
  377.     The values are represented by flag bits defined in
  378.     <libraries/commodities.h>. Several errors may be recorded by multiple
  379.     bits in 'error'.
  380.  
  381.     The currently defined errors are:
  382.  
  383.     COERR_ISNULL
  384.       The value of parameter 'co' was in fact NULL. This error
  385.       means "the problem with the object you inquire about is
  386.       that it failed to be created."
  387.  
  388.       COERR_NULLATTACH
  389.       Using the commodities' list manipulation functions, an attempt was
  390.       made to add a NULL object to the list belonging to 'co'. This allows
  391.       a line of code as follows to exist in an error-tolerant program:
  392.  
  393.         AttachCxObj(filter,CxSender(myport,MY_ID));
  394.  
  395.       COERR_BADFILTER
  396.       The most recent filter specification for a filter object
  397.       was faulty. This happens if no sense can be made out of a
  398.       description string, or if an input expression (IX) has an
  399.       invalid format or version byte. When this bit is set in a
  400.       filter's error field, the filter will match nothing, but this
  401.       is not the proper way to "turn off" a filter, use ActivateCxObj().
  402.  
  403.       COERR_BADTYPE
  404.       A type specific operation, such as SetFilterIX(), was called
  405.       for object 'co', but 'co' isn't of the proper type.
  406.  
  407.    INPUTS
  408.     co - the commodity object to get the accumulated error from
  409.  
  410.    RESULTS
  411.     error - the accumulated error
  412.  
  413.    SEE ALSO
  414.     SetFilter(), SetFilterIX(), AttachCxObj(), ActivateCxObj(),
  415.     ClearCxObjError()
  416.  
  417. commodities.library/CxObjType                   commodities.library/CxObjType
  418.  
  419.    NAME
  420.     CxObjType -- obtain the type of a commodity object. (V36)
  421.  
  422.    SYNOPSIS
  423.     type = CxObjType(co);
  424.              A0
  425.  
  426.     ULONG CxObjType(CxObj *);
  427.  
  428.    FUNCTION
  429.     This function should not really be necessary. It returns
  430.     the type of a commodity object, which you should already
  431.     know, since you created it in the first place.
  432.  
  433.    INPUTS
  434.     co - the commodity object to inquire about
  435.  
  436.    RESULTS
  437.     type - the type of the commodity object, possible values are
  438.            defined in <libraries/commodities.h>
  439.  
  440.    SEE ALSO
  441.     CreateCxObj()
  442.  
  443. commodities.library/DeleteCxObj               commodities.library/DeleteCxObj
  444.  
  445.    NAME
  446.     DeleteCxObj -- delete a commmodity object. (V36)
  447.  
  448.    SYNOPSIS
  449.     DeleteCxObj(co);
  450.                 A0
  451.  
  452.     VOID DeleteCxObj(CxObj *);
  453.  
  454.    FUNCTION
  455.     Deletes a commodity object of any type. If the object
  456.     is linked into a list, it is first removed. Note that
  457.     the handle 'co' is invalid after this function is called.
  458.  
  459.     Also note that deleting an object which has other objects attached
  460.     to it may be undesirable. Use the function DeleteCxObjAll()
  461.     to delete an entire sub-tree of objects.
  462.  
  463.    INPUTS
  464.     co - the commodity object to delete
  465.  
  466.    SEE ALSO
  467.     DeleteCxObjAll()
  468.  
  469. commodities.library/DeleteCxObjAll         commodities.library/DeleteCxObjAll
  470.  
  471.    NAME
  472.     DeleteCxObjAll -- recursively delete a tree of commodity objects.
  473.               (V36)
  474.  
  475.    SYNOPSIS
  476.     DeleteCxObjAll(co);
  477.                A0
  478.  
  479.     VOID DeleteCxObjAll(CxObj *);
  480.  
  481.    FUNCTION
  482.     This function deletes the commodity object 'co', and
  483.     recursively deletes all objects attached to it, and the
  484.     objects attached to them, etc.
  485.  
  486.     If 'co' is linked into a list, it is first removed. Note
  487.     that the handle 'co' is invalid after this function is called.
  488.  
  489.     This function is useful when an application exits: most
  490.     applications can clean up completely by deleting the
  491.     entire sub-tree of objects starting at their broker.
  492.  
  493.    INPUTS
  494.     co - the first commodity object to delete
  495.  
  496.    SEE ALSO
  497.     DeleteCxObj()
  498.  
  499. commodities.library/DisposeCxMsg             commodities.library/DisposeCxMsg
  500.  
  501.    NAME
  502.     DisposeCxMsg -- delete a commodity message. (V36)
  503.  
  504.    SYNOPSIS
  505.     DisposeCxMsg(cxm);
  506.              A0
  507.  
  508.     VOID DisposeCxMsg(struct CxMsg *);
  509.  
  510.    FUNCTION
  511.     This function eliminates the commodity message pointed to by 'cxm'.
  512.     Can be used to 'swallow' InputEvents by disposing of every commodity
  513.     message of type CXM_IEVENT.
  514.  
  515.    INPUTS
  516.     cxm - the commodity message to delete
  517.  
  518. commodities.library/DivertCxMsg               commodities.library/DivertCxMsg
  519.  
  520.    NAME
  521.     DivertCxMsg -- send a commodity message down an object list. (V36)
  522.  
  523.    SYNOPSIS
  524.     DivertCxMsg(cxm,headObj,returnObj);
  525.             A0  A1      A2
  526.  
  527.     VOID DivertCxMsg(struct CxMsg *,CxObj *,CxObj *);
  528.  
  529.    FUNCTION
  530.     This function sends the commodity message 'cxm' down the list of
  531.     objects attached to 'headObj'. The pointer 'returnObj' is first
  532.     pushed onto the routing stack of 'cxm' so that when the end of the
  533.     list of 'headObj' is reached the SUCCESSOR of 'returnObj' is the
  534.     next destination.
  535.  
  536.     For example, when a filter finds a match with a message, the
  537.     message is diverted down the filter's list like this:
  538.  
  539.         DivertCxMsg(cxm,filter,filter);
  540.  
  541.    INPUTS
  542.     cxm - the commodity message to divert
  543.     headObj - the list of objects to divert the message to
  544.     returnObj - the object to use as a place holder
  545.  
  546.    SEE ALSO
  547.     RouteCxMsg()
  548.  
  549. commodities.library/EnqueueCxObj             commodities.library/EnqueueCxObj
  550.  
  551.    NAME
  552.     EnqueueCxObj -- insert a commodity object within a list of objects
  553.                 based on object priority. (V36)
  554.  
  555.    SYNOPSIS
  556.     EnqueueCxObj(headObj,co);
  557.              A0      A1
  558.  
  559.     VOID EnqueueCxObj(CxObj *,CxObj *);
  560.  
  561.    FUNCTION
  562.     This function puts object 'co' into the list of object 'headObj'.
  563.     The insertion point is determined by the object's priority. The
  564.     objects are kept in the list from the highest priority to the
  565.     lowest. New nodes are inserted in front of the first node with a
  566.     lower priority. Hence a FIFO queue for nodes of equal priority.
  567.  
  568.     The priority of the commodity object can be set using SetCxObjPri().
  569.  
  570.    INPUTS
  571.     headObj - pointer to a list of objects
  572.     co - the object to add to the list
  573.  
  574.    RESULTS
  575.     If 'co' is NULL, this function will record that fact in the
  576.     internal accumulated error of 'headObj'. This error record
  577.     can be retrieved using CxObjError() and cleared using
  578.     ClearCxObjError().
  579.  
  580.    SEE ALSO
  581.     SetCxObjPri(), CxObjError(), ClearCxObjError()
  582.  
  583. commodities.library/InsertCxObj               commodities.library/InsertCxObj
  584.  
  585.    NAME
  586.     InsertCxObj -- insert a commodity object in a list after a given
  587.                object. (V36)
  588.  
  589.    SYNOPSIS
  590.     InsertCxObj(headObj,co,pred);
  591.             A0      A1 A2
  592.  
  593.     VOID InsertCxObj(CxObj *,CxObj *,CxObj *);
  594.  
  595.    FUNCTION
  596.     Adds 'co' to the list of objects pointed to by 'headObj' after
  597.     object 'pred'.
  598.  
  599.    INPUTS
  600.     headObj - pointer to a list of objects
  601.     co - the object to insert in the list
  602.     pred - the object after which 'co' should be inserted. If this is NULL
  603.            then 'co' is added to the head of the list.
  604.  
  605.    RESULTS
  606.     If 'co' is NULL, this function will record that fact in the
  607.     internal accumulated error of 'headObj'. This error record
  608.     can be retrieved using CxObjError() and cleared using
  609.     ClearCxObjError().
  610.  
  611.    SEE ALSO
  612.     CxObjError(), ClearCxObjError()
  613.  
  614. commodities.library/InvertKeyMap             commodities.library/InvertKeyMap
  615.  
  616.    NAME
  617.     InvertKeyMap -- generate an input event from an ANSI code. (V36)
  618.  
  619.    SYNOPSIS
  620.     success = InvertKeyMap(ansicode,event,km)
  621.                     D0       A0    A1
  622.  
  623.     BOOL InvertKeyMap(ULONG,struct InputEvent *,struct KeyMap *);
  624.  
  625.    FUNCTION
  626.     This function uses the system call MapANSI() to figure out what
  627.     InputEvent translates to an ANSI character code 'ansicode'. The
  628.     InputEvent pointed to by 'event' is filled in with that information.
  629.     The KeyMap 'km' is used for the translation, unless it is NULL, in
  630.     which case the system default keymap (as defined when
  631.     commodities.library is initialized) is used.
  632.  
  633.    INPUTS
  634.     ansicode - the ANSI code to convert to an input event
  635.     event - the InputEvent to fill-in
  636.     km - the keymap to use for the translation, or NULL to use the
  637.          system default keymap.
  638.  
  639.    RESULTS
  640.     success - TRUE if the translation worked, FALSE otherwise.
  641.  
  642.    BUGS
  643.     This function currently handles one-deep dead keys (such as
  644.     <alt f>o). It does not look up the high key map (keystrokes
  645.     with scan codes greater than 0x40), and misses system changes to
  646.     the default key map.
  647.  
  648.    SEE ALSO
  649.     cx_lib/InvertString()
  650.  
  651. commodities.library/ParseIX                       commodities.library/ParseIX
  652.  
  653.    NAME
  654.     ParseIX -- initialize an input expression given a description string.
  655.            (V36)
  656.  
  657.    SYNOPSIS
  658.     failureCode = ParseIX(description,ix);
  659.                   A0          A1
  660.  
  661.     LONG ParseIX(STRPTR,IX *);
  662.  
  663.    FUNCTION
  664.     Given an input description string and an allocated input
  665.     expression, sets the fields of the input expression to
  666.     correspond to the description string.
  667.  
  668.    INPUTS
  669.     description - the string to parse
  670.     ix - the input expression to hold the result of the parse
  671.  
  672.    RESULTS
  673.     failureCode -  0 if all went well,
  674.               -1 if tokens after end (code spec)
  675.                   -2 if 'description' was NULL
  676.  
  677. commodities.library/RemoveCxObj               commodities.library/RemoveCxObj
  678.  
  679.    NAME
  680.     RemoveCxObj -- remove a commodity object from a list. (V36)
  681.  
  682.    SYNOPSIS
  683.     RemoveCxObj(co);
  684.             A0
  685.  
  686.     VOID RemoveCxObj(CxObj *);
  687.  
  688.    FUNCTION
  689.     This function remove 'co' from any list it may be a part of.
  690.     Will not crash if 'co' is NULL, or if it has not been inserted
  691.     in a list (and is not corrupted).
  692.  
  693.     It is not recommended to remove a broker from the master list.
  694.  
  695.    INPUTS
  696.        co - the object to remove, may be NULL
  697.  
  698.    SEE ALSO
  699.     AttachCxObj(), EnqueueCxObj(), InsertCxObj()
  700.  
  701. commodities.library/RouteCxMsg                 commodities.library/RouteCxMsg
  702.  
  703.    NAME
  704.     RouteCxMsg -- set the next destination of a commodity message. (V36)
  705.  
  706.    SYNOPSIS
  707.     RouteCxMsg(cxm,co);
  708.            A0  A1
  709.  
  710.     VOID RouteCxMsg(struct CxMsg *,CxObj *);
  711.  
  712.    FUNCTION
  713.     Establishes the next destination of a commodity message
  714.     to be 'co', which must be a valid commodity object, and
  715.     must be linked in ultimately to the Commodities Object List.
  716.  
  717.     Routing of an object is analogous to a 'goto' in a program.
  718.     There is no effect on the message's routing stack.
  719.  
  720.    INPUTS
  721.     cxm - the commodity message to route
  722.     co - the commodity object to route the message to
  723.  
  724.    SEE ALSO
  725.     DivertCxMsg()
  726.  
  727. commodities.library/SetCxObjPri               commodities.library/SetCxObjPri
  728.  
  729.    NAME
  730.     SetCxObjPri -- set the priority of a commodity object. (V36)
  731.  
  732.    SYNOPSIS
  733.     SetCxObjPri(co,pri)
  734.             A0 D0
  735.  
  736.     VOID SetCxObjPri(CxObj *,LONG);
  737.  
  738.    FUNCTION
  739.     This function sets the priority of a commodity object for the
  740.     purposes of EnqueueCxObj().
  741.  
  742.     It is strongly recommended that the ToolTypes environment be
  743.     utilized to provide end-user control over the priority of
  744.      brokers, but application specific ordering of other objects
  745.     within their lists is not dictated.
  746.  
  747.    INPUTS
  748.     co - the commodity object to affect
  749.     pri - the object's new priority in the range -128 to +127. A value
  750.           of 0 is normal.
  751.  
  752.    SEE ALSO
  753.     EnqueueCxObj()
  754.  
  755. commodities.library/SetFilter                   commodities.library/SetFilter
  756.  
  757.    NAME
  758.     SetFilter -- change the matching condition of a commodity filter.
  759.              (V36)
  760.  
  761.    SYNOPSIS
  762.     SetFilter(filter,text);
  763.           A0     A1
  764.  
  765.     VOID SetFilter(CxObj *,STRPTR);
  766.  
  767.    FUNCTION
  768.     This function changes the matching condition of a commodity input
  769.     filter to that described by the input description string 'text'.
  770.  
  771.    INPUTS
  772.     filter - the filter object to affect
  773.     text - the new matching conditions for the filter
  774.  
  775.    RESULTS
  776.     The internal error of 'filter' will have the COERR_BADFILTER
  777.     bit set or cleared depending on the failure or success of this
  778.     function.
  779.  
  780.    SEE ALSO
  781.     SetFilterIX(), CxObjError()
  782.  
  783. commodities.library/SetFilterIX               commodities.library/SetFilterIX
  784.  
  785.    NAME
  786.     SetFilterIX -- change the matching condition of a commodity filter.
  787.                (V36)
  788.  
  789.    SYNOPSIS
  790.     SetFilterIX(filter,ix);
  791.             A0     A1
  792.  
  793.     VOID SetFilterIX(CxObj *,IX *);
  794.  
  795.    FUNCTION
  796.     This function changes the matching condition of a commodity input
  797.     filter to that described by the binary input expression pointed by
  798.     'ix'.
  799.  
  800.     Input expressions are defined in <libraries/commodities.h>.
  801.     It is important to remember that the first field of the input
  802.     expression structure must indicate which version of the
  803.     input expression structure is being used.
  804.  
  805.    INPUTS
  806.     filter - the filter object to affect
  807.     ix - the new matching conditions for the filter
  808.  
  809.    RESULTS
  810.     The internal error of 'filter' will have the COERR_BADFILTER
  811.     bit set or cleared depending on the failure or success of this
  812.     function.
  813.  
  814.    SEE ALSO
  815.     SetFilter(), CxObjError(), <libraries/commodities.h>
  816.  
  817. commodities.library/SetTranslate             commodities.library/SetTranslate
  818.  
  819.    NAME
  820.     SetTranslate -- replace a translator object's translation list. (V36)
  821.  
  822.    SYNOPSIS
  823.     SetTranslate(translator,events);
  824.              A0         A1
  825.  
  826.     VOID SetTranslate(CxObj *,struct InputEvent *);
  827.  
  828.    FUNCTION
  829.     This function replaces the translation list of a commodity
  830.     translator object with the linked list starting at 'events'.
  831.  
  832.     A NULL value for 'events' indicates that the object 'translator'
  833.     should swallow all commodity messages that are sent its way.
  834.  
  835.     Note that the input events are not copied into commodities' private
  836.     memory, but the value of 'events' is used -- asynchronously to the
  837.     application program -- to find a chain of InputEvents in the
  838.     application's data space. At the time of translation, each input event
  839.     is copied into its own new commodity message.
  840.  
  841.     The above means that no other commodities' user, nor
  842.     commodities.library itself will be modifying your list of InputEvents.
  843.     On the other hand, your program must not corrupt the input event
  844.     chain that has been presented to a translator.
  845.  
  846.    INPUTS
  847.     translator - the translator object to affect
  848.     events - the new input event translation list
  849.  
  850.    SEE ALSO
  851.     <devices/inputevent.h>, cx_lib/CxTranslate()
  852.  
  853.