PopUpMenuClass ~~~~~~~~~~~~~~ Release: 1.1 (29.12.1993) Author: Markus Aalto COPYRIGHT ~~~~~~~~~ PopUpMenuClass BOOPSI object for AmigaDOS V37 or greater. Copyright © 1993 Markus Aalto This program is freely distributable software. You may distribute it freely as long as no more than nominal fee is required for copying it. Also it can be included to freely distributable disk collections such as Fred Fish Collection. It may also be reviewed in Amiga specific magazines and added to accompaning disks if the disk doesn't cost any extra to the magazine byers. However you have to mail that specific issue to the Author free of charge. This program is distributed without warranty of any kind. So no responsibility is taken for using this program, its documentation, functionality or damages it may cause. If you want to use part of this package in PD/Freeware/Shareware programs you are free to do so. For commercial applications please contact the author. DUE TO MISUNDERSTANDING OF GNU PUBLIC LICENCE AGREEMENT ON MY PART THIS VERSION AND ALL THE LATER VERSIONS ARE **NOT** DISTRIBUTED UNDER THE GNU PUBLIC LICENCE AS VERSION 1.0 WAS. You can contact the author by writing to Markus Aalto, Muurahaisentie 11a, 01490 VANTAA, FINLAND. Or send EMail to s37732v@vipunen.hut.fi. INTRODUCTION ~~~~~~~~~~~~ This is a documentation for PopUpMenu gadget class. This gadget class is implemented as a subclass of "gadgetclass" BOOPSI class. Therefore it inherits all the qualities of its parent supporting things like disabling, relative positions and relative dimensions. PopUpMenu gadget is based on a idea of Cycle and ListView gadget. Cycle gadgets are nice because they don't take too much space in GUI but are a pain if there are many options to choose from. The ListView gadget is much nicer but it takes a lot of space. The solution which is existed in a many other platforms earlier is a concept of PopUpMenu gadgets which open up a Menu when gadget is pressed and this is exactly what PopUpManuClass now brings to the use of Amiga users. Because there is always room for improvement in any program there is also in this class, but for now it does its job quite nicely. If you feel the need to continue the effort I have started, please feel free to implement it further. I would like to get the changes however because I intend to do further developing of my own too. For those of you who think this is breaking the concept of User Style Guide conforming programming I want to say that I have tried to conserve the look/feel of AmigaOS in a behaviour of this gadget. Because Commodore haven't offered this solution I think that this is a very good substitution until they do cover this area in future OS releases (I hope). Also I don't think that it's necessary to follow exactly all the steps the Style Guide represents. In my opinion they should be used as a guide line, which you should try to follow in those parts of the programming where it's feasible or possible at all. FUNCTION ~~~~~~~~ PopUpMenuClass link-time library consists of 2 public functions user can call. These are explained in detail in PopUpMenuClass.doc. CreatePopUpMenuClass() function is used to create a private subclass of 'gadgetclass'- It returns a pointer to this newly created class so that you can use NewObject() system call to create your own objects. DisposePopUpMenuClass() is the function user have to call to free the resources allocated by CreatePopUpMenuClass(). Call it when you are done using PopUpMenuClass. ATTRIBUTES ~~~~~~~~~~ The tags recognized by the PopUpMenu gadget class are. PUMG_Labels (List *) A Pointer to standard Exec List, where ln_Name fields point to displayed item names. If the item list is empty then empty List structure or NULL pointer can be used. This tag also accepts a tag value of ~0, which means that OM_SET method doesn't return a non-null value, to indicate that gadget shouldn't be refreshed. This is a good way to detach a list while modifying it. Default is NULL. (Create, Set, Get.) PUMG_Active (UWORD) The ordinal number, counting from zero, of the active choice of the gadget. Default is zero. (Create, Set, Get, Update, Notify.) PUMG_TextFont (TextFont *) A Pointer to opened TextFont for Gadget Text/PopUpMenu to use. If this is NULL then default RastPort font returned with GM_RENDER method is used. Default is NULL. (Create, Set, Get.) PUMG_NewLook (BOOL) Under KickStart V39 or greater you can set this flag to TRUE, if you want to get NewLook look-a-like PopUpMenu. Default is FALSE. (Create, Get.) GA_Disabled (BOOL) Set this attribute to TRUE to disable PopUpMenu, to FALSE otherwise. Default is FALSE. Note that Gadget isn't updated automatically. Instead it SetGadgetAttrs() returns you non-NULL value, which means that you should do the refreshing. (Create and Set.) POPUPMENUCLASS GADGET DIMENSIONS ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ There are no predefined dimensions for PopUpMenu gadget. The width should be atleast 28 pixels (PUMG_MinWidth), and height should be atleast 8 pixels (PUMG_MinHeight). This gadget knows how to handle the strings wider than the gadget. However it doesn't try to clip texts higher than the gadget, so use the font height (tf->tf_YSize + INTERHEIGHT) to give a good look for the gadget. (INTERHEIGHT is a predefined system value for GadTools gadgets.) KEYBOARD OPERATION ~~~~~~~~~~~~~~~~~~ You can also use keyboard to control the PopUpMenu gadget. Gadget can be activated from a program by ActivateGadget() intuition call. You can use following keyboard commands to control menu. CURSOR-UP - Move up in a menu. CURSOR-DOWN - Move down in a menu. ALT-CURSOR-UP - Move start of a menu list. ALT-CURSOR-DOWN - Move end of the menu list. RETURN - Select item. ESC - Escape menu. ATTRIBUTE SETTINGS ~~~~~~~~~~~~~~~~~~ If you want to have a automatic update for a gadget, when you call SetGadgetAttrs() you should use following functions instead of SetGadgetAttrs(). void New_SetGadgetAttrsA( struct Gadget *gadget, struct Window *window, struct Requester *req, struct TagItem *tags ) { if( SetGadgetAttrsA( gadget, window, req, tags) ) { RefreshGList( gadget, window, req, 1); } } or void New_SetGadgetAttrs( struct Gadget *gadget, struct Window *window, struct Requester *req, ULONG item, ... ) { New_SetGadgetAttrsA( gadget, window, req, (struct TagItem *)&item); } NOTES ~~~~~ PopUpMenuClass.lib needs following libraries to be open: graphics.library, intuition.library and utility.library. All version 37 or greater of course. If SetGadgetAttrs() returns anything else than 0 (when setting atrributes for PopUpMenu gadget) you should call intuition gadget refresh functions. ********************** WARNING WARNING *********************** If you use gadget's ID value to identify your PopUpMenu gadget then do not let other Boopsi gadgets send GA_ID messages to your gadget. You can prevent this by using Map tags and mapping GA_ID to TAG_IGNORE. This is possibly a bug in 'gadgetclass' BOOPSI class because 'OM_UPDATE' methods should not change GA_ID values - or at least RKM says it shouldn't. ********************** WARNING WARNING *********************** If you want to hear the gadget Active item changes, then you have 2 possibilities. Listen to IDCMP_GADGETUP messages for changes and get the new Active value from Code field of IntuiMessage structure. Remember to set GA_RelVerify for the gadget. Listen to IDCMP_IDCMPUPDATE message for changes. The returned TagList contains GA_ID and PUMG_Active. BUGS ~~~~ Doesn't scroll the list if there is more items than fits to the screen. Is it even necessary? Should work if put to window borders, but the colors won't look right. HISTORY ~~~~~~~ 1.1: 29.12.93 -------------- Added PUMG_NewLook tag so that users of KS39 or greater can get NewLook look-a-like PopUpMenus. Made some code cleaning/optimizations.