home *** CD-ROM | disk | FTP | other *** search
/ Amiga MA Magazine 1998 #6 / amigamamagazinepolishissue1998.iso / coders / boopsi / popupmenuclass / docs / popupmenuclass.notes < prev    next >
Text File  |  1995-10-09  |  9KB  |  256 lines
  1.  
  2.                              PopUpMenuClass
  3.                              ~~~~~~~~~~~~~~
  4.  
  5.                      Release:       1.1   (29.12.1993)
  6.                       Author:       Markus Aalto
  7.  
  8.  
  9. COPYRIGHT
  10. ~~~~~~~~~
  11.  
  12.     PopUpMenuClass BOOPSI object for AmigaDOS V37 or greater.
  13.     Copyright © 1993 Markus Aalto
  14.  
  15.     This program is freely distributable software. You may distribute
  16.     it freely as long as no more than nominal fee is required for
  17.     copying it. Also it can be included to freely distributable disk
  18.     collections such as Fred Fish Collection.
  19.  
  20.     It may also be reviewed in Amiga specific magazines and added to
  21.     accompaning disks if the disk doesn't cost any extra to the magazine
  22.     byers. However you have to mail that specific issue to the Author
  23.     free of charge.
  24.  
  25.     This program is distributed without warranty of any kind. So no
  26.     responsibility is taken for using this program, its documentation,
  27.     functionality or damages it may cause.
  28.  
  29.     If you want to use part of this package in PD/Freeware/Shareware
  30.     programs you are free to do so. For commercial applications please
  31.     contact the author.
  32.  
  33.  
  34.     DUE TO MISUNDERSTANDING OF GNU PUBLIC LICENCE AGREEMENT ON MY PART
  35.     THIS VERSION AND ALL THE LATER VERSIONS ARE **NOT** DISTRIBUTED UNDER
  36.     THE GNU PUBLIC LICENCE AS VERSION 1.0 WAS.
  37.  
  38.     You can contact the author by writing to Markus Aalto,
  39.     Muurahaisentie 11a, 01490 VANTAA, FINLAND. Or send EMail to
  40.     s37732v@vipunen.hut.fi.
  41.  
  42.  
  43. INTRODUCTION
  44. ~~~~~~~~~~~~
  45.  
  46.     This is a documentation for PopUpMenu gadget class. This gadget
  47.     class is implemented as a subclass of "gadgetclass" BOOPSI class.
  48.     Therefore it inherits all the qualities of its parent supporting
  49.     things like disabling, relative positions and relative dimensions.
  50.  
  51.     PopUpMenu gadget is based on a idea of Cycle and ListView gadget.
  52.     Cycle gadgets are nice because they don't take too much space
  53.     in GUI but are a pain if there are many options to choose from.
  54.     The ListView gadget is much nicer but it takes a lot of space.
  55.     The solution which is existed in a many other platforms earlier
  56.     is a concept of PopUpMenu gadgets which open up a Menu when
  57.     gadget is pressed and this is exactly what PopUpManuClass now
  58.     brings to the use of Amiga users.
  59.  
  60.     Because there is always room for improvement in any program there
  61.     is also in this class, but for now it does its job quite nicely.
  62.     If you feel the need to continue the effort I have started, please
  63.     feel free to implement it further. I would like to get the changes
  64.     however because I intend to do further developing of my own too.
  65.  
  66.     For those of you who think this is breaking the concept of User
  67.     Style Guide conforming programming I want to say that I have tried
  68.     to conserve the look/feel of AmigaOS in a behaviour of this gadget.
  69.     Because Commodore haven't offered this solution I think that this
  70.     is a very good substitution until they do cover this area in future
  71.     OS releases (I hope). Also I don't think that it's necessary to
  72.     follow exactly all the steps the Style Guide represents. In my
  73.     opinion they should be used as a guide line, which you should try
  74.     to follow in those parts of the programming where it's feasible
  75.     or possible at all.
  76.  
  77.  
  78.  
  79. FUNCTION
  80. ~~~~~~~~
  81.  
  82.     PopUpMenuClass link-time library consists of 2 public functions
  83.     user can call. These are explained in detail in PopUpMenuClass.doc.
  84.  
  85.     CreatePopUpMenuClass() function is used to create a private subclass
  86.     of 'gadgetclass'- It returns a pointer to this newly created class
  87.     so that you can use NewObject() system call to create your own objects.
  88.  
  89.     DisposePopUpMenuClass() is the function user have to call to free the
  90.     resources allocated by CreatePopUpMenuClass(). Call it when you are
  91.     done using PopUpMenuClass.
  92.  
  93.  
  94.  
  95. ATTRIBUTES
  96. ~~~~~~~~~~
  97.  
  98.     The tags recognized by the PopUpMenu gadget class are.
  99.  
  100.     PUMG_Labels (List *)
  101.         A Pointer to standard Exec List, where ln_Name fields point to
  102.         displayed item names. If the item list is empty then empty List
  103.         structure or NULL pointer can be used. This tag also accepts
  104.         a tag value of ~0, which means that OM_SET method doesn't
  105.         return a non-null value, to indicate that gadget shouldn't
  106.         be refreshed. This is a good way to detach a list while modifying
  107.         it. Default is NULL.
  108.         (Create, Set, Get.)
  109.  
  110.     PUMG_Active (UWORD)
  111.         The ordinal number, counting from zero, of the active choice
  112.         of the gadget. Default is zero.
  113.         (Create, Set, Get, Update, Notify.)
  114.  
  115.  
  116.     PUMG_TextFont (TextFont *)
  117.         A Pointer to opened TextFont for Gadget Text/PopUpMenu to
  118.         use. If this is NULL then default RastPort font returned
  119.         with GM_RENDER method is used. Default is NULL.
  120.         (Create, Set, Get.)
  121.  
  122.     PUMG_NewLook (BOOL)
  123.         Under KickStart V39 or greater you can set this flag to TRUE,
  124.         if you want to get NewLook look-a-like PopUpMenu.
  125.         Default is FALSE.
  126.         (Create, Get.)
  127.  
  128.     GA_Disabled (BOOL)
  129.         Set this attribute to TRUE to disable PopUpMenu, to FALSE
  130.         otherwise. Default is FALSE. Note that Gadget isn't updated
  131.         automatically. Instead it SetGadgetAttrs() returns you
  132.         non-NULL value, which means that you should do the refreshing.
  133.         (Create and Set.)
  134.  
  135.  
  136.  
  137. POPUPMENUCLASS GADGET DIMENSIONS
  138. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  139.  
  140.     There are no predefined dimensions for PopUpMenu gadget. The
  141.     width should be atleast 28 pixels (PUMG_MinWidth), and height
  142.     should be atleast 8 pixels (PUMG_MinHeight). This gadget knows
  143.     how to handle the strings wider than the gadget. However it
  144.     doesn't try to clip texts higher than the gadget, so use
  145.     the font height (tf->tf_YSize + INTERHEIGHT) to give a good look
  146.     for the gadget. (INTERHEIGHT is a predefined system value for
  147.     GadTools gadgets.)
  148.  
  149.  
  150.  
  151. KEYBOARD OPERATION
  152. ~~~~~~~~~~~~~~~~~~
  153.  
  154.     You can also use keyboard to control the PopUpMenu gadget. Gadget
  155.     can be activated from a program by ActivateGadget() intuition
  156.     call. You can use following keyboard commands to control menu.
  157.  
  158.         CURSOR-UP           - Move up in a menu.
  159.         CURSOR-DOWN         - Move down in a menu.
  160.         ALT-CURSOR-UP       - Move start of a menu list.
  161.         ALT-CURSOR-DOWN     - Move end of the menu list.
  162.         RETURN              - Select item.
  163.         ESC                 - Escape menu.
  164.  
  165.  
  166.  
  167. ATTRIBUTE SETTINGS
  168. ~~~~~~~~~~~~~~~~~~
  169.  
  170.     If you want to have a automatic update for a gadget, when you
  171.     call SetGadgetAttrs() you should use following functions
  172.     instead of SetGadgetAttrs().
  173.  
  174.     void New_SetGadgetAttrsA( struct Gadget *gadget,
  175.                               struct Window *window,
  176.                               struct Requester *req,
  177.                               struct TagItem *tags )
  178.     {
  179.         if( SetGadgetAttrsA( gadget, window, req, tags) ) {
  180.             RefreshGList( gadget, window, req, 1);
  181.         }
  182.     }
  183.  
  184.     or
  185.  
  186.     void New_SetGadgetAttrs( struct Gadget *gadget,
  187.                              struct Window *window,
  188.                              struct Requester *req,
  189.                              ULONG item, ... )
  190.     {
  191.         New_SetGadgetAttrsA( gadget, window, req, (struct TagItem *)&item);
  192.     }
  193.  
  194.  
  195.  
  196.  
  197. NOTES
  198. ~~~~~
  199.  
  200.     PopUpMenuClass.lib needs following libraries to be open:
  201.     graphics.library, intuition.library and utility.library. All
  202.     version 37 or greater of course.
  203.  
  204.     If SetGadgetAttrs() returns anything else than 0 (when setting
  205.     atrributes for PopUpMenu gadget) you should call intuition
  206.     gadget refresh functions.
  207.  
  208.  
  209.     ********************** WARNING WARNING ***********************
  210.  
  211.     If you use gadget's ID value to identify your PopUpMenu gadget
  212.     then do not let other Boopsi gadgets send GA_ID messages to
  213.     your gadget. You can prevent this by using Map tags and mapping
  214.     GA_ID to TAG_IGNORE. This is possibly a bug in 'gadgetclass'
  215.     BOOPSI class because 'OM_UPDATE' methods should not change GA_ID
  216.     values - or at least RKM says it shouldn't.
  217.  
  218.     ********************** WARNING WARNING ***********************
  219.  
  220.  
  221.     If you want to hear the gadget Active item changes, then you have
  222.     2 possibilities.
  223.  
  224.         Listen to IDCMP_GADGETUP messages for changes and get the new
  225.         Active value from Code field of IntuiMessage structure.
  226.         Remember to set GA_RelVerify for the gadget.
  227.  
  228.         Listen to IDCMP_IDCMPUPDATE message for changes. The returned
  229.         TagList contains GA_ID and PUMG_Active.
  230.  
  231.  
  232.  
  233.  
  234. BUGS
  235. ~~~~
  236.  
  237.     Doesn't scroll the list if there is more items than fits to the
  238.     screen. Is it even necessary?
  239.  
  240.     Should work if put to window borders, but the colors won't look
  241.     right.
  242.  
  243.  
  244.  
  245. HISTORY
  246. ~~~~~~~
  247.  
  248. 1.1:  29.12.93
  249. --------------
  250.  
  251.     Added PUMG_NewLook tag so that users of KS39 or greater can get
  252.     NewLook look-a-like PopUpMenus.
  253.  
  254.     Made some code cleaning/optimizations.
  255.  
  256.