$RCSfile: commodityclass.doc,v $
        Description: Commodityclass documentation.
          Copyright: (C) Copyright 1994 Jaba Development.
                     (C) Copyright 1994 Jan van den Baard.
                     All Rights Reserved.

            $Author: jaba $
          $Revision: 1.1 $
              $Date: 1994/07/04 21:05:30 $
------------------------------------------------------------------------------

TABLE OF CONTENTS

commodityclass/--background--
commodityclass/Methods
commodityclass/Attributes

commodityclass/--background--                    commodityclass/--background--

    NAME
        Class:          commodityclass
        Superclass:     ROOTCLASS
        Include File:   <libraries/bgui.h>

    FUNCTION
        To  provide  a  BOOPSI based interface with the commodities.libraries.
        This  class  will allow you to setup and maintain a simple broker with
        simple  hotkeys.  The  attached hotkeys can also be seperatly disabled
        and enabled.

commodityclass/Methods                                  commodityclass/Methods

    NEW METHODS
        CM_ADDHOTKEY  --  This  method  must  be used to attach hotkeys to the
                broker. The following custom message structure is used:

                struct cmAddHotKey {
                        ULONG           MethodID; /* CM_ADDHOTKEY */
                        STRPTR          cah_InputDescription;
                        ULONG           cah_KeyID;
                        ULONG           cah_Flags;
                };

                cah_InputDescription -- This  must  point to a string in which
                        the hotkey is described.  The input description string
                        is the same string  as  you  would  pass  the HotKey()
                        routine from the amiga.lib link library.

                cah_KeyID -- This must be a 32Bit integer which represents the
                        ID of the key.  This must be a unique value as this ID
                        will be used to identify the key.

                cah_Flags -- This  field  may have  any of the following flags
                        set:

                        CAHF_DISABLED -- When  set  the  key  is  added to the
                                broker but it is disabled from usage.

                The return code of this method will be  TRUE uppon success and
                FALSE uppon failure.

        CM_REMHOTKEY -- This method must be used to remove a hotkey.
        CM_DISABLEHOTKEY -- This method must be used to disable a hotkey.
        CM_ENABLEHOTKEY -- This method must be used to enable a hotkey.
                All three methods above use the same custom  message structure
                which is defined as follows:

                struct cmDoKeyCommand {
                        ULONG           MethodID; /* Any of the above. */
                        ULONG           cdkc_KeyID;
                };

                cdkc_KeyID -- This must be the ID of the key  which  was  used
                        in the CM_ADDHOTKEY method.  When  the matching hotkey
                        is found the appropiate action is taken.

                The return code  of  these  methods will be TRUE uppon success
                and FALSE uppon failure.

        CM_ENABLEBROKER, CM_DISABLEBROKER -- These two methods must be used to
                switch the broker on or off.

        CM_MSGINFO -- This method must be used to  pull and  evaluate messages
                from the broker message port.  This method uses  the following
                custom message structure:

                struct cmMsgInfo {
                        ULONG           MethodID; /* CM_MSGINFO */
                        struct {
                                ULONG  *Type;
                                ULONG  *ID;
                                ULONG  *Data;
                        }               cm_Info;
                };

                cm_Info -- This field can contain pointer to a storage  space
                        which can  hold  32bits  each.  The  results  of  the
                        CxMsgType(), CxMsgID() and CxMsgData() are  stored in
                        here. When any of the storage fields is NULL  no data
                        is stored.

                This method will return CMMI_NOMORE  when  all messages  have
                been processed.

                Example:

                Object          *com_obj;
                ULONG            mask = 0, type, id, data, rc;
                BOOL             running = TRUE;

                GetAttr( COMM_SigMask, com_obj, &mask );

                do {
                        Wait( mask );
                        while (( rc = DoMethod( com_obj,
                                                CM_MSGINFO,
                                                &type,
                                                &id,
                                                &data )) != CMMI_NOMORE ) {
                                switch ( type ) {
                                        ...
                                }
                        }
                } while ( running );

commodityclass/Attributes                            commodityclass/Attributes

    NAME
        COMM_Name -- ( STRPTR )
        COMM_Title -- ( STRPTR )
        COMM_Description -- ( STRPTR )
        COMM_Priority -- ( LONG )
        COMM_Unique -- ( BOOL )
        COMM_Notify -- ( BOOL )
        COMM_ShowHide -- ( BOOL )

    FUNCTION
        These  attributes  correspond  to  the  fields  as  described  in  the
        NewBroker structure from the <libraries/commodities.h> file. The three
        boolean  attributes  can be used to set the NewBroker flags defined in
        this same file.

        Defaults are as follows:
                COMM_Name               NULL
                COMM_Title              NULL
                COMM_Description        NULL
                COMM_Priority           0
                COMM_Unique             TRUE
                COMM_Notify             TRUE
                COMM_ShowHide           FALSE

        Applicability is (I).

    NAME
        COMM_SigMask -- ( ULONG )

    FUNCTION
        To  obtain  the  broker signal mask.

        Example:

        Object         *CO_Com;
        ULONG           mask, sigrec;

        GetAttr( COMM_SigMask, CO_Com, &mask );

        do {
                sigrec = Wait( mask );
                ...
        } while ( ... );

        Applicability is (G).

    NAME
        COMM_ErrorCode -- ( ULONG )

    FUNCTION
        To find out exactly what went wrong when adding a hotkey to the broker
        failed.  Getting  this  attribute  can  result  in the following error
        codes:

        CMERR_OK -- OK. No problems.
        CMERR_NO_MEMORY -- Out of memory.
        CMERR_KEYID_IN_USE -- Key ID was already used.
        CMERR_KEY_CREATION -- Key creation failed.
        CMERR_CXOBJERROR -- CxObjError() reported failure.

        Applicability is (G).