home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Misc / bgui.lzx / bgui / docs / commodityclass.doc < prev    next >
Encoding:
Text File  |  1995-04-24  |  6.8 KB  |  187 lines
  1.  
  2.                File: commodityclass.doc
  3.         Description: Commodityclass documentation.
  4.           Copyright: (C) Copyright 1994-1995 Jaba Development.
  5.                      (C) Copyright 1994-1995 Jan van den Baard.
  6.                      All Rights Reserved.
  7.  
  8. ------------------------------------------------------------------------------
  9.  
  10. TABLE OF CONTENTS
  11.  
  12. commodityclass/--background--
  13. commodityclass/Methods
  14. commodityclass/Attributes
  15.  
  16. commodityclass/--background--                    commodityclass/--background--
  17.  
  18.     NAME
  19.         Class:          commodityclass
  20.         Superclass:     ROOTCLASS
  21.         Include File:   <libraries/bgui.h>
  22.  
  23.     FUNCTION
  24.         To  provide  a  BOOPSI based interface with the commodities.libraries.
  25.         This  class  will allow you to setup and maintain a simple broker with
  26.         simple  hotkeys.  The  attached hotkeys can also be seperatly disabled
  27.         and enabled.
  28.  
  29. commodityclass/Methods                                  commodityclass/Methods
  30.  
  31.     NEW METHODS
  32.         CM_ADDHOTKEY  --  This  method  must  be used to attach hotkeys to the
  33.                 broker. The following custom message structure is used:
  34.  
  35.                 struct cmAddHotKey {
  36.                         ULONG           MethodID; /* CM_ADDHOTKEY */
  37.                         STRPTR          cah_InputDescription;
  38.                         ULONG           cah_KeyID;
  39.                         ULONG           cah_Flags;
  40.                 };
  41.  
  42.                 cah_InputDescription -- This  must  point to a string in which
  43.                         the hotkey is described.  The input description string
  44.                         is the same string  as  you  would  pass  the HotKey()
  45.                         routine from the amiga.lib link library.
  46.  
  47.                 cah_KeyID -- This must be a 32Bit integer which represents the
  48.                         ID of the key.  This must be a unique value as this ID
  49.                         will be used to identify the key.
  50.  
  51.                 cah_Flags -- This  field  may have  any of the following flags
  52.                         set:
  53.  
  54.                         CAHF_DISABLED -- When  set  the  key  is  added to the
  55.                                 broker but it is disabled from usage.
  56.  
  57.                 The return code of this method will be  TRUE uppon success and
  58.                 FALSE uppon failure.
  59.  
  60.         CM_REMHOTKEY -- This method must be used to remove a hotkey.
  61.         CM_DISABLEHOTKEY -- This method must be used to disable a hotkey.
  62.         CM_ENABLEHOTKEY -- This method must be used to enable a hotkey.
  63.                 All three methods above use the same custom  message structure
  64.                 which is defined as follows:
  65.  
  66.                 struct cmDoKeyCommand {
  67.                         ULONG           MethodID; /* Any of the above. */
  68.                         ULONG           cdkc_KeyID;
  69.                 };
  70.  
  71.                 cdkc_KeyID -- This must be the ID of the key  which  was  used
  72.                         in the CM_ADDHOTKEY method.  When  the matching hotkey
  73.                         is found the appropiate action is taken.
  74.  
  75.                 The return code  of  these  methods will be TRUE uppon success
  76.                 and FALSE uppon failure.
  77.  
  78.         CM_ENABLEBROKER, CM_DISABLEBROKER -- These two methods must be used to
  79.                 switch the broker on or off.
  80.  
  81.         CM_MSGINFO -- This method must be used to  pull and  evaluate messages
  82.                 from the broker message port.  This method uses  the following
  83.                 custom message structure:
  84.  
  85.                 struct cmMsgInfo {
  86.                         ULONG           MethodID; /* CM_MSGINFO */
  87.                         struct {
  88.                                 ULONG  *Type;
  89.                                 ULONG  *ID;
  90.                                 ULONG  *Data;
  91.                         }               cm_Info;
  92.                 };
  93.  
  94.                 cm_Info -- This field can contain pointer to a storage  space
  95.                         which can  hold  32bits  each.  The  results  of  the
  96.                         CxMsgType(), CxMsgID() and CxMsgData() are  stored in
  97.                         here. When any of the storage fields is NULL  no data
  98.                         is stored.
  99.  
  100.                 This method will return CMMI_NOMORE  when  all messages  have
  101.                 been processed.
  102.  
  103.                 Example:
  104.  
  105.                 Object          *com_obj;
  106.                 ULONG            mask = 0, type, id, data, rc;
  107.                 BOOL             running = TRUE;
  108.  
  109.                 GetAttr( COMM_SigMask, com_obj, &mask );
  110.  
  111.                 do {
  112.                         Wait( mask );
  113.                         while (( rc = DoMethod( com_obj,
  114.                                                 CM_MSGINFO,
  115.                                                 &type,
  116.                                                 &id,
  117.                                                 &data )) != CMMI_NOMORE ) {
  118.                                 switch ( type ) {
  119.                                         ...
  120.                                 }
  121.                         }
  122.                 } while ( running );
  123.  
  124. commodityclass/Attributes                            commodityclass/Attributes
  125.  
  126.     NAME
  127.         COMM_Name -- ( STRPTR )
  128.         COMM_Title -- ( STRPTR )
  129.         COMM_Description -- ( STRPTR )
  130.         COMM_Priority -- ( LONG )
  131.         COMM_Unique -- ( BOOL )
  132.         COMM_Notify -- ( BOOL )
  133.         COMM_ShowHide -- ( BOOL )
  134.  
  135.     FUNCTION
  136.         These  attributes  correspond  to  the  fields  as  described  in  the
  137.         NewBroker structure from the <libraries/commodities.h> file. The three
  138.         boolean  attributes  can be used to set the NewBroker flags defined in
  139.         this same file.
  140.  
  141.         Defaults are as follows:
  142.                 COMM_Name               NULL
  143.                 COMM_Title              NULL
  144.                 COMM_Description        NULL
  145.                 COMM_Priority           0
  146.                 COMM_Unique             TRUE
  147.                 COMM_Notify             TRUE
  148.                 COMM_ShowHide           FALSE
  149.  
  150.         Applicability is (I).
  151.  
  152.     NAME
  153.         COMM_SigMask -- ( ULONG )
  154.  
  155.     FUNCTION
  156.         To  obtain  the  broker signal mask.
  157.  
  158.         Example:
  159.  
  160.         Object         *CO_Com;
  161.         ULONG           mask, sigrec;
  162.  
  163.         GetAttr( COMM_SigMask, CO_Com, &mask );
  164.  
  165.         do {
  166.                 sigrec = Wait( mask );
  167.                 ...
  168.         } while ( ... );
  169.  
  170.         Applicability is (G).
  171.  
  172.     NAME
  173.         COMM_ErrorCode -- ( ULONG )
  174.  
  175.     FUNCTION
  176.         To find out exactly what went wrong when adding a hotkey to the broker
  177.         failed.  Getting  this  attribute  can  result  in the following error
  178.         codes:
  179.  
  180.         CMERR_OK -- OK. No problems.
  181.         CMERR_NO_MEMORY -- Out of memory.
  182.         CMERR_KEYID_IN_USE -- Key ID was already used.
  183.         CMERR_KEY_CREATION -- Key creation failed.
  184.         CMERR_CXOBJERROR -- CxObjError() reported failure.
  185.  
  186.         Applicability is (G).
  187.