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