@database "commodities"
@master "Work:RKM/Includes&Autodocs/doc/commodities.doc"

@Node Main "commodities.doc"
@toc "2.0Includes_Autodocs/Autodocs"

@{" ActivateCxObj() " Link "ActivateCxObj()"}      @{" CxObjError() " Link "CxObjError()"}        @{" ParseIX() " Link "ParseIX()"}
@{" AddIEvents() " Link "AddIEvents()"}         @{" CxObjType() " Link "CxObjType()"}         @{" RemoveCxObj() " Link "RemoveCxObj()"}
@{" AttachCxObj() " Link "AttachCxObj()"}        @{" DeleteCxObj() " Link "DeleteCxObj()"}       @{" RouteCxMsg() " Link "RouteCxMsg()"}
@{" ClearCxObjError() " Link "ClearCxObjError()"}    @{" DeleteCxObjAll() " Link "DeleteCxObjAll()"}    @{" SetCxObjPri() " Link "SetCxObjPri()"}
@{" CreateCxObj() " Link "CreateCxObj()"}        @{" DisposeCxMsg() " Link "DisposeCxMsg()"}      @{" SetFilter() " Link "SetFilter()"}
@{" CxBroker() " Link "CxBroker()"}           @{" DivertCxMsg() " Link "DivertCxMsg()"}       @{" SetFilterIX() " Link "SetFilterIX()"}
@{" CxMsgData() " Link "CxMsgData()"}          @{" EnqueueCxObj() " Link "EnqueueCxObj()"}      @{" SetTranslate() " Link "SetTranslate()"}
@{" CxMsgID() " Link "CxMsgID()"}            @{" InsertCxObj() " Link "InsertCxObj()"}
@{" CxMsgType() " Link "CxMsgType()"}          @{" InvertKeyMap() " Link "InvertKeyMap()"}

@EndNode

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

NAME
    ActivateCxObj -- change the activation state of a commodity object.
                     (V36)

SYNOPSIS
    previous = ActivateCxObj(co,true);
                             A0 D0

    LONG ActivateCxObj(CxObj *,LONG);

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

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

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

INPUTS
    co - the commodity object to affect
    true - 0 to deactivate the object, anything else to activate it

RESULTS
    previous - the previous activation state: 0 if the object was
               inactive, anything else if the object was active

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

@EndNode

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

NAME
    AddIEvents -- add input events to commodities' input stream. (V36)

SYNOPSIS
    AddIEvents(events)
               A0

    VOID AddIEvents(struct @{"InputEvent" Link "ADCD_v1.2:Inc&AD2.0/Includes/devices/inputevent.h/Main" 198} *);

FUNCTION
    This function adds a null-terminated linked list of input events 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 commodity
    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" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/lists.h/Main" 21}.

INPUTS
    events - the list of input events to add

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

@EndNode

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

NAME
    AttachCxObj -- attach a commodity object to the end of an existing
                   list of objects. (V36)

SYNOPSIS
    AttachCxObj(headObj,co);
                A0      A1

    VOID AttachCxObj(CxObj *,CxObj *);

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

INPUTS
    headObj - pointer to a list of objects
    co - the object to add to the list

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

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

@EndNode

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

NAME
    ClearCxObjError -- clear the accumulated error value of a commodity
                       object. (V36)

SYNOPSIS
    ClearCxObjError(co);
            A0

    VOID ClearCxObjError(CxObj *);

FUNCTION
    This function clears the accumulated error value of commodity object
    'co'.

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

INPUTS
    co - the object to affect

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

@EndNode

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

NAME
    CreateCxObj -- create a new commodity object. (V36)

SYNOPSIS
    co = CreateCxObj(type,arg1,arg2);
                     D0   A0   A1

    CxObj *CreateCxObj(ULONG,LONG,LONG);

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

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

INPUTS
    type - the type of object to create as defined in
           @{"<libraries/commodities.h>" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/commodities.h/Main" 0}
   arg1 - first argument, meaning depends on 'type'
    arg2 - second argument, meaning depends on 'type'

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

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

@EndNode

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

NAME
    CxBroker -- create a commodity broker. (V36)

SYNOPSIS
    broker = CxBroker(nb,error);
                      A0 D0

    CxObj *CxBroker(struct @{"NewBroker" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/commodities.h/Main" 47} *,LONG *);

FUNCTION
    This function creates a broker from the specification found in the
    @{"NewBroker" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/commodities.h/Main" 47} structure pointed to by 'nb'. The purpose and meaning of the
    fields of the @{"NewBroker" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/commodities.h/Main" 47} structure are described below. Also see
    @{"<libraries/commodities.h>" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/commodities.h/Main" 0} for more info.

    struct @{"NewBroker" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/commodities.h/Main" 47}
    {
       BYTE            nb_Version;
       BYTE           *nb_Name;
       BYTE           *nb_Title;
       BYTE           *nb_Descr;
       SHORT           nb_Unique;
       BYTE            nb_Pri;
        struct @{"MsgPort" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/ports.h/Main" 29} *nb_Port;
        WORD            nb_ReservedChannel;
    };

    nb_Version
    This is the way that future versions of commodities.library
    can identify which version of the @{"NewBroker" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/commodities.h/Main" 47} structure you are using.
    This should be set to NB_VERSION, defined in @{"<libraries/commodities.h>" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/commodities.h/Main" 0}

    nb_Name
    This is the name of the broker. This name is used to find the broker
    in the Commodities Object @{"List" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/lists.h/Main" 21} and is the name shown in the list
    gadget of the Exchange program. The name string is copied in the
    broker object upon creation, so this string can be discarded right
    after CxBroker() returns. The maximum length of the name string is
    defined by a constant in @{"<libraries/commodities.h>" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/commodities.h/Main" 0}.

    nb_Title, nb_Descr
    These are two strings which appear to the user in the Exchange
    program and describe the application the broker is representing.
    Note that these strings are copied into the broker object.
    The maximum length of these strings that will be recognized are
    defined by constants in @{"<libraries/commodities.h>" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/commodities.h/Main" 0}.

    nb_Unique
    This field indicates what should happen if a broker of the same name
    (nb_Name) already exists in the Commodities Object @{"List" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/lists.h/Main" 21}. Constants
    in @{"<libraries/commodities.h>" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/commodities.h/Main" 0} allow the caller to specify whether
    another broker is to be created, and whether any existing broker of
    the same name should be notified that an attempt at creating a
    duplicate has been made.

    nb_Pri
    This specifies with what priority the new broker is to be inserted
    within the Commodities Object @{"List" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/lists.h/Main" 21}. Higher priority nodes appear
    earlier in a list. See @{"<libraries/commodities.h>" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/commodities.h/Main" 0} 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.

INPUTS
    nb - an initialized @{"NewBroker" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/commodities.h/Main" 47} structure
    error - a pointer to a longword where to store a failure code, this
            may be NULL

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

                    CBERR_OK
                    No problems; broker created OK.

                    CBERR_SYSERR
                    System problems, not your fault. Sign of low memory 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 version specified in 'nb_Version' is unknown to the
                    library.

SEE ALSO
    @{"SetCxObjPri()" Link "SetCxObjPri()"}, @{"<libraries/commodities.h>" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/commodities.h/Main" 0}

@EndNode

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

NAME
    CxMsgData -- obtain a pointer to a commodity message's data area. (V36)

SYNOPSIS
    data = CxMsgData(cxm);
                     A0

    UBYTE *CxMsgData(struct CxMsg *);

FUNCTION
    Most commodity messages contain meaningful data, such as an @{"InputEvent" Link "ADCD_v1.2:Inc&AD2.0/Includes/devices/inputevent.h/Main" 198}
    structure. This function returns a pointer to this data.

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

INPUTS
    cxm - the commodity message to get the data pointer from

RESULTS
    data - a pointer to the message's data, or NULL if 'cxm' is NULL.

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

@EndNode

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

NAME
    CxMsgID -- obtain the ID of a commodity message. (V36)

SYNOPSIS
    id = CxMsgID(cxm);
                 A0

    LONG CxMsgID(struct CxMsg *);

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

INPUTS
    cxm - the commodity message to inquire about

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

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

@EndNode

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

NAME
    CxMsgType -- obtain the type of a commodity message. (V36)

SYNOPSIS
    type = CxMsgType(cxm);
                     A0

    ULONG CxMsgType(struct CxMsg *);

FUNCTION
    This function returns the type of a commodity message. Possible values
    of 'type' are defined in @{"<libraries/commodities.h>" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/commodities.h/Main" 0}. Most commodity
    messages are of type CXM_IEVENT.

INPUTS
    cxm - the commodity message to inquire about

RESULTS
    type - the type of the commodity message, possible values are defined
           in @{"<libraries/commodities.h>" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/commodities.h/Main" 0}

@EndNode

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

NAME
    CxObjError -- obtain a commodity object's accumulated error. (V36)

SYNOPSIS
    error = CxObjError(co);
                       A0

    LONG CxObjError(CxObj *);

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

    The currently defined errors are:

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

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

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

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

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

INPUTS
    co - the commodity object to get the accumulated error from

RESULTS
    error - the accumulated error

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

@EndNode

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

NAME
    CxObjType -- obtain the type of a commodity object. (V36)

SYNOPSIS
    type = CxObjType(co);
                     A0

    ULONG CxObjType(CxObj *);

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

INPUTS
    co - the commodity object to inquire about

RESULTS
    type - the type of the commodity object, possible values are
           defined in @{"<libraries/commodities.h>" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/commodities.h/Main" 0}

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

@EndNode

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

NAME
    DeleteCxObj -- delete a commmodity object. (V36)

SYNOPSIS
    DeleteCxObj(co);
                A0

    VOID DeleteCxObj(CxObj *);

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

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

INPUTS
    co - the commodity object to delete

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

@EndNode

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

NAME
    DeleteCxObjAll -- recursively delete a tree of commodity objects.
                      (V36)

SYNOPSIS
    DeleteCxObjAll(co);
                   A0

    VOID DeleteCxObjAll(CxObj *);

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

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

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

INPUTS
    co - the first commodity object to delete

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

@EndNode

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

NAME
    DisposeCxMsg -- delete a commodity message. (V36)

SYNOPSIS
    DisposeCxMsg(cxm);
                 A0

    VOID DisposeCxMsg(struct CxMsg *);

FUNCTION
    This function eliminates the commodity message pointed to by 'cxm'.
    Can be used to 'swallow' InputEvents by disposing of every commodity
    message of type CXM_IEVENT.

INPUTS
    cxm - the commodity message to delete

@EndNode

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

NAME
    DivertCxMsg -- send a commodity message down an object list. (V36)

SYNOPSIS
    DivertCxMsg(cxm,headObj,returnObj);
                A0  A1      A2

    VOID DivertCxMsg(struct CxMsg *,CxObj *,CxObj *);

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

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

            DivertCxMsg(cxm,filter,filter);

INPUTS
    cxm - the commodity message to divert
    headObj - the list of objects to divert the message to
    returnObj - the object to use as a place holder

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

@EndNode

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

NAME
    EnqueueCxObj -- insert a commodity object within a list of objects
                    based on object priority. (V36)

SYNOPSIS
    EnqueueCxObj(headObj,co);
                 A0      A1

    VOID EnqueueCxObj(CxObj *,CxObj *);

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

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

INPUTS
    headObj - pointer to a list of objects
    co - the object to add to the list

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

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

@EndNode

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

NAME
    InsertCxObj -- insert a commodity object in a list after a given
                   object. (V36)

SYNOPSIS
    InsertCxObj(headObj,co,pred);
                A0      A1 A2

    VOID InsertCxObj(CxObj *,CxObj *,CxObj *);

FUNCTION
    Adds 'co' to the list of objects pointed to by 'headObj' after
    object 'pred'.

INPUTS
    headObj - pointer to a list of objects
    co - the object to insert in the list
    pred - the object after which 'co' should be inserted. If this is NULL
           then 'co' is added to the head of the list.

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

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

@EndNode

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

NAME
    InvertKeyMap -- generate an input event from an ANSI code. (V36)

SYNOPSIS
    success = InvertKeyMap(ansicode,event,km)
                           D0       A0    A1

    BOOL InvertKeyMap(ULONG,struct @{"InputEvent" Link "ADCD_v1.2:Inc&AD2.0/Includes/devices/inputevent.h/Main" 198} *,struct @{"KeyMap" Link "ADCD_v1.2:Inc&AD2.0/Includes/devices/keymap.h/Main" 22} *);

FUNCTION
    This function uses the system call @{"MapANSI()" Link "keymap/MapANSI()"} to figure out what
    @{"InputEvent" Link "ADCD_v1.2:Inc&AD2.0/Includes/devices/inputevent.h/Main" 198} translates to an ANSI character code 'ansicode'. The
    @{"InputEvent" Link "ADCD_v1.2:Inc&AD2.0/Includes/devices/inputevent.h/Main" 198} pointed to by 'event' is filled in with that information.
    The @{"KeyMap" Link "ADCD_v1.2:Inc&AD2.0/Includes/devices/keymap.h/Main" 22} 'km' is used for the translation, unless it is NULL, in
    which case the system default keymap (as defined when
    commodities.library is initialized) is used.

INPUTS
    ansicode - the ANSI code to convert to an input event
    event - the @{"InputEvent" Link "ADCD_v1.2:Inc&AD2.0/Includes/devices/inputevent.h/Main" 198} to fill-in
    km - the keymap to use for the translation, or NULL to use the
         system default keymap.

RESULTS
    success - TRUE if the translation worked, FALSE otherwise.

BUGS
    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.

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

@EndNode

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

NAME
    ParseIX -- initialize an input expression given a description string.
               (V36)

SYNOPSIS
    failureCode = ParseIX(description,ix);
                          A0          A1

    LONG ParseIX(STRPTR,IX *);

FUNCTION
    Given an input description string and an allocated input
    expression, sets the fields of the input expression to
    correspond to the description string.

INPUTS
    description - the string to parse
    ix - the input expression to hold the result of the parse

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

@EndNode

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

NAME
    RemoveCxObj -- remove a commodity object from a list. (V36)

SYNOPSIS
    RemoveCxObj(co);
                A0

    VOID RemoveCxObj(CxObj *);

FUNCTION
    This function remove 'co' from any list it may be a part of.
    Will not crash if 'co' is NULL, or if it has not been inserted
    in a list (and is not corrupted).

    It is not recommended to remove a broker from the master list.

INPUTS
   co - the object to remove, may be NULL

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

@EndNode

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

NAME
    RouteCxMsg -- set the next destination of a commodity message. (V36)

SYNOPSIS
    RouteCxMsg(cxm,co);
               A0  A1

    VOID RouteCxMsg(struct CxMsg *,CxObj *);

FUNCTION
    Establishes the next destination of a commodity message
    to be 'co', which must be a valid commodity object, and
    must be linked in ultimately to the Commodities Object @{"List" Link "ADCD_v1.2:Inc&AD2.0/Includes/exec/lists.h/Main" 21}.

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

INPUTS
    cxm - the commodity message to route
    co - the commodity object to route the message to

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

@EndNode

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

NAME
    SetCxObjPri -- set the priority of a commodity object. (V36)

SYNOPSIS
    SetCxObjPri(co,pri)
                A0 D0

    VOID SetCxObjPri(CxObj *,LONG);

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

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

INPUTS
    co - the commodity object to affect
    pri - the object's new priority in the range -128 to +127. A value
          of 0 is normal.

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

@EndNode

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

NAME
    SetFilter -- change the matching condition of a commodity filter.
                 (V36)

SYNOPSIS
    SetFilter(filter,text);
              A0     A1

    VOID SetFilter(CxObj *,STRPTR);

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

INPUTS
    filter - the filter object to affect
    text - the new matching conditions for the filter

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

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

@EndNode

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

NAME
    SetFilterIX -- change the matching condition of a commodity filter.
                   (V36)

SYNOPSIS
    SetFilterIX(filter,ix);
                A0     A1

    VOID SetFilterIX(CxObj *,IX *);

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

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

INPUTS
    filter - the filter object to affect
    ix - the new matching conditions for the filter

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

SEE ALSO
    @{"SetFilter()" Link "SetFilter()"}, @{"CxObjError()" Link "CxObjError()"}, @{"<libraries/commodities.h>" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/commodities.h/Main" 0}

@EndNode

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

NAME
    SetTranslate -- replace a translator object's translation list. (V36)

SYNOPSIS
    SetTranslate(translator,events);
                 A0         A1

    VOID SetTranslate(CxObj *,struct @{"InputEvent" Link "ADCD_v1.2:Inc&AD2.0/Includes/devices/inputevent.h/Main" 198} *);

FUNCTION
    This function replaces the translation list of a commodity
    translator object with the linked list starting at 'events'.

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

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

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

INPUTS
    translator - the translator object to affect
    events - the new input event translation list

SEE ALSO
    @{"<devices/inputevent.h>" Link "ADCD_v1.2:Inc&AD2.0/Includes/devices/inputevent.h/Main" 0}, @{"cx_lib/CxTranslate()" Link "amiga_lib/CxTranslate()"}

@EndNode

