@database PopupMenu.guide @node main "PopupMenu Library V10.x" @{" About" LINK is} What's this?? @{" Required" LINK rq} Requirements = an Amiga with OS3.0 @{" Authors" LINK me} How to contact the authors @{" Legal" LINK di} License agreement @{" History" LINK hi} What's new? @{" Future" LINK fu} A glimpse of the future @{" Credits" LINK tx} Acknowledgements @{" Developer" LINK de} Developer documentation For more information, visit the homepage: @{" www.boing.nu/pm " SYSTEM "OpenURL http://www.boing.nu/pm/"} @{" popupmenu.amiga.tm " SYSTEM "OpenURL http://popupmenu.amiga.tm/"} (mirror) @endnode @node is "What is this??" @{u}Introduction@{uu} This is a library that provides programmers with a set of functions which makes it easy to build menus (popup and pulldown menus) for their programs. Currently there are development packages for C/C++, E and HBasic available. There are also some tools for use of PopupMenus in AmigaDOS scripts available from the home page. @{" www.boing.nu/pm " SYSTEM "OpenURL http://www.boing.nu/pm/"} A list of programs that use this library can be found on: @{" www.boing.nu/pm/apps.html " SYSTEM "OpenURL http://www.boing.nu/pm/apps.html"} @{u}Features@{uu} * User configurable look and feel. * Items can be laid out both vertically and horizontally. * Virtually unlimited number of submenus. * Virtually unlimited number of mutually excluded items. * Supports pulldown menus in a much more flexible way than Intuition. * Supports multiple selection. * Supports images and icons. * Bold, italic, underlined and shadowed text. * Configurable options include borders, colours and menu shadows. * Innovative window bar pulldown mode. * MagicMenu images by Mario Cattaneo. @endnode @node rq "Requirements" PopupMenu.library requires the following: * AmigaOS 3.0 or higher. Recommended: * AmigaOS 3.9 * Picasso96 or CyberGfx For the web links in this guide, you need: * OpenURL @endnode @node me "Authors" Author of popupmenu.library, C developement files and examples: Henrik Isaksson Author of E developement files and examples: Daniel Kasmeroglu Author of HBasic developement files and examples: Dámaso D. Estévez @endnode @node di "DISCLAIMER" This software is subject to the "Standard Amiga FD-Software Copyright Note". It is Freeware as defined in paragraph 4a. For more information please read "AFD-COPYRIGHT" (Version 1.4 or higher). @endnode @node st "Important things to think about when you're using popupmenu.library!" * When you use mutual exclude items, use the PM_Toggle tag turn off toggling of these items. If you don't, your code must handle the case when the user deselects all of the items. * If you want to use keyboard shortcuts in your application, you have to use the PM_FilterIMsg() function. (Unless you plan to handle the keyboard events yourself.) * If you want the menus to be able to handle multiple selections, you have to use the PM_MenuHandler tag. NOTE: If your menu is opened with the left mouse button, you will not be able to select multiple items by clicking the right button, while you're holding down the left. To get around this problem, you must use the PM_UseLMB tag. * If you want to follow Mario 'padrino' Cattaneo's MagicMenu style conventions, here are his rules: All contextual menus should have a title describing it's context. ("Trashcan" for a trashcan icon in a WB replacement software) The title should be printed using shadowed, centered text, and it should be white. (use the tags PM_Centered, PM_Shadowed and PM_ShinePen) The simplest way to do this is to use the PMMenuTitle macro. @endnode @node hi "History" The history of popupmenu.library: --- 10.7 --- - Changed the version numbering to include a build number. - Changed the license to use the "standard AFD copyright note". - Fixed a bug in the shadow code. - Text shadow/outline now uses SHADOWPEN in DrawInfo mode. - Changed the position of submenus to 2/3 of the active item's width instead of 2/3 of the menu width, so it should work with horizontal groups now. - Fixed a bug in the pen allocation. --- 10.6 --- - Text styles are now preserved when an item is active. - The InputHandler now uses maximum priority to prevent programs from stealing the input. --- 10.5 --- - Added support for keyboard control: Cursor down/up - select next/previous item. Cursor right - open sub menu. Cursor left - close sub menu. Enter/Return - select item and close menu OR open sub menu. Space - select an item OR open sub menu. ESC - close menu. - Selecting a checkmark item does no longer redraw the entire menu, unless the item affects other items (ie. if the item is an MX item). - Bug fix: MultiSelect did not highlight items immediately when they were selected. - Implemented the PM_Insert_Before insert method for PM_InsertMenuItem(). --- 10.4 --- - Bug fix: MultiSelect highlight should now work correctly with mutual exclude menus. - Bug fix: The new input handler from v 10.03 didn't work as expected. --- 10.3 --- - Bug fix: A possible problem with MultiSelect menus has been removed. - The library code has been rewritten so it can be recompiled with other compilers and possibly other OSes like AROS or Phoenix OS. - The Input Handler has been rewritten and should now be a bit faster and hopefully the kind of dead locks that have been reported in conjunction with some commodities should be resolved quickly. --- 10.2 --- - Bug fix: MultiSelect now works in "Sticky mode". - Bug fix: A really ugly bug had found its way into the GetPopupMenuAttrs function, all boolean attributes were returned as TRUE all the time regardless of their actual value. This has been fixed now. - Bug fix: Now it is possible to disable toggling of checkmark items, including mutual exclude items. Use the tag PM_Toggle to turn this feature off. This is recommended for all normal mutual exclude items! - Introduced new shadow code to avoid overlapping of shadows, and also code for faster rendering of the shadows. I get nearly 1 million pixels/second (on my overclocked PicassoIV, on CV64 it should operate at even greater speed, visit the popupmenu homepage for a benchmarking utility.) This new code also fixes the problems in 16 bit RGB mode. - Image drawing now uses CyberGraphics functions when available, which speeds up the drawing significantly on graphics board screens. - An "intermediate space" is now inserted between AmigaKey icons and text. - Recursive calls now checks the stack, and aborts if the stack is too small. - New tag: PM_ExcludeShared enables sharing of the Exclude list between several items. - New function: PM_FreeIDList() is used to free an Exclude list. When PM_ExcludeShared is used, it will not be freed automatically. --- 10.1 --- - Bug fix: MultiSelect now works in "Sticky mode". - Bug fix: A really ugly bug had found its way into the GetPopupMenuAttrs function, all boolean attributes were returned as TRUE all the time regardless of their actual value. This has been fixed now. - Bug fix: Now it is possible to disable toggling of checkmark items, including mutual exclude items. Use the tag PM_Toggle to turn this feature off. This is recommended for all normal mutual exclude items! - Introduced new shadow code to avoid overlapping of shadows, and also code for faster rendering of the shadows. I get nearly 1 million pixels/second (on my overclocked PicassoIV, on CV64 it should operate at even greater speed, visit the popupmenu homepage for a benchmarking utility.) This new code also fixes the problems in 16 bit RGB mode. - Image drawing now uses CyberGraphics functions when available, which speeds up the drawing significantly on graphics board screens. - An "intermediate space" is now inserted between AmigaKey icons and text. - Recursive calls now checks the stack, and aborts if the stack is too small. - New tag: PM_ExcludeShared enables sharing of the Exclude list between several items. - New function: PM_FreeIDList() is used to free an Exclude list. When PM_ExcludeShared is used, it will not be freed automatically. --- 9.7 --- - Faster image rendering on machines with OS3.1 and gfx board through use of WriteChunkyPixels(). - Bug fix: sometimes the widest item was incorrectly laid out when some other items in the menu had icons. - Bug fix: a pulldown menu is now moved to the screen bar if its parent window is a backdrop window (or has a narrow title bar). --- 9.4 --- - Text style settings does not override PM_Bold, PM_Underlined and PM_Italic. --- 9.3 --- - Removed a bug which was causing Enforcer hits and which made the text settings useless. --- 9.2 --- - PM_Right and PM_Bottom did not work correctly. Fixed. - Icons are now centered horizontally in the icon column. - If BOOPSI image objects are used as icons or images, they are now drawn in the correct state. (IDS_SELECTED/IDS_NORMAL) This will make the transparency option in the Reaction image classes work with PopupMenu. --- 9.0 --- - Added PM_AbortHook(), a function that should be called periodically from within submenu constructor/destructor hooks, to find out if the user does not want to wait for the menu to complete. - Added PM_LocaleHook and PM_StringID which simplifies localization of the menus. - Added PM_GetVersion(), which simply returns the version number of popupmenu.library. This function is intended for use by the prefs editor. - Added PM_ReloadPrefs(), which forces the library to load the prefs file. This function is intended for use by the prefs editor. - Added new tags for advanced layout. (PM_Members, PM_LayoutMode) - Submenus now 'walk' across the screen in a different way. When you reach the right side of the screen, they will start popping up to the left of the parent menu, until you reach the left side again. - Added maximum depth for the shadows. - Changed the PopupMenu structure. It is now sized dynamically, simple items (eg. text-only items) require less than half as much memory as before. - "Old Style" separator bars used to be drawn with the wrong pen, now they're drawn with shadowpen. - "Old Style/Intuition" borders where incorrectly laid out as being 1 pixel wide, while their actual with is 2 pixels. This caused them to be overwritten sometimes. - Fixed bug with ColourBoxes appearing under AmigaKey images in check items. - Fixed keyboard shortcuts that didn't work with check items. - Added PM_HintBox, which makes the menu disappear when the mouse is moved. Intended for showing short hints when the mousepointer stops over a GUI element. Also known as "ToolTips". --- 8.20 --- - Adjusted the MagicMenu style borders a little bit. - Added "Raised" mode for selected items. - Added E modules and examples by Daniel Kasmeroglu to the distribution. - Added "Intermediate spacing" settings for the space between images and text. - Added two new text modes, "Outlined" and "Embossed". - Added colour settings for text outline and shadow. - Submenus now behave a little better. They used to close at the same point as they opened on, now they close two pixels above this point. - Added settings for shadow intensity. - Added ability to adjust the vertical position of the item's text. - Fixed a bug which caused the non-window mode to trash the screen sometimes. - Fixed problems caused by omitting the PM_Menu tag. - Rewrote the menu list scanning routines in assembler. This saved 72 bytes, and hopefully made things a little bit faster. - Items with sub menus are now also selectable, if PM_NoSelect is set to FALSE. (not reversable) - Added support for $POO by Gareth Murfin. --- 8.0 --- - Fixed a crash in the BigMenu demo. - Reworked the layout code and added settings for spacing between borders and text. - Fixed the 'dropbox' border style mode. - Added text style settings. - Added intuition style menu borders. - Corrected the wide (title) separators in button border mode. - Added an option to turn off 'real' shadows. - Added pulldown menu 'windowbar' mode. (Menus show up at the top of the window instead of the screen bar.) - Replaced the icons with new NewIcons by Brian Gilbert. - Added two new functions, PM_InsertMenuItemA and PM_RemoveMenuItem. - Added a new tag, PM_Hidden. - Ghosted items now has MagicMenu-like ghosting, when MM2 borders and images are selected. Currently only the text will be affected. - Done a few minor visual adjustments. --- 7.50 --- - Improved user input routines. The menus used to flicker sometimes when the mouse was moved. - New remap routine. Optimized by Ralph Wermke. - Added a submenu destructor hook, PM_SubDestruct. --- 7.40 --- - Added a callback hook for dynamic allocation of menus: PM_SubConstruct - Translated the remapping code to assembler. --- 7.35 --- - Bugfix. BYTE read from $0 when a NULL pointer was passed to PM_Title. --- 7.3 --- - Added a few new tags: PM_Right, PM_Bottom, PM_MinWidth, PM_MinHeight, PM_CenterScreen, PM_UseLMB. - Removed a few Enforcer hits. - Made a few changes to the non-window mode. It should work better with CGFX now. --- 7.2 --- - Added "Sticky mouse button" mode. - Removed the "Open menu when button is pressed/released" setting. (it wasn't supported by any applications) Therefore the PM_Code tag is no longer needed. - Fixed one possible enforcer hit. --- 7.1 --- - Bugfix. Sometimes the menu could show up on the wrong place. --- 7.0 --- - The PM_FilterIMsg() function has been moved to a new library offset. This was done because the argument passing used the wrong registers. To provide backwards compatibillity, the old function is still left. - The Image system is entirely rewritten. All used images are now stored in the configuration file. This saves some memory and will, in future releases, let the user load his/her own images. Image drawing should also be much faster, especially on chunky screens and on machines with chunky-to-planar converter. There may be some problems with prefsfiles from release 6.0. - Fixed a bug in the separator bars. (The MM2 style was used even without MagicMenu2 borders selected.) - Added the @{"PM_ColourBox" LINK PM_MakeItemA} tag. --- 6.0 --- - Made some changes to the API, for keyboard shortcuts and multiselect support. The library should still be 99% backwards compatible. Hacks like the previous version of the BigMenu demo will crash. - Added keyboard shortcut support through PM_FilterIMsgA. - PM_ExLstA() added for easier listing of mutually exclusive item ID's. - Added support for multiselect. - Added menu border settings. - Fixed the "standard 2d images". - Fixed a problem with pulldown menus when "compact" was not selected. - Moved some of the images out of the library, and in to the prefs editor. The needed images will then be stored in the prefsfile. (wich means that only the needed images will be in memory) --- 5.4 --- - Moved the submenus 5 pixels up. - Improved the deadlock detection. - Improved the look of separator bars. --- 5.35 --- - Optimized the pen allocation a bit. --- 5.3 --- - Moved the submenus a bit to the left. Now it looks more like the other menus, and it's easier to open the submenus. - Fixed a bug in pen allocation/freeing. - Made a few adjustments to the separator bars. - Fixed bug in "Submenu Delay" code. - Fixed an enforcer hit in window mode. - Got rid of a few unnecessary bytes again. (about 1k smaller) --- 5.2 --- - Fixed delay bug in non-window mode. - Improved the remapping of magic images. Right look and a few hundred percent faster. :) - Pulldown menus should now work in non-window mode too. - Fixed the shadows. They were 1 pixel to wide before. - Added a new tag, PM_Shadowed, to make the text shadowed. - Changed the PMMenu macro so the titles will use shadowed text. - Fixed refresh problem in window-mode. - Made the separator bars look more like MM2. - And this time the library is actually 1272 bytes smaller! --- 5.1 --- - Fixed the deadlock bug in non-window mode. - Added MagicMenu2 Images, and it's special remapping. (relative color values) - Added support for pulldown menus. (works only in window-mode at the moment) --- 5.0 --- - Opening the menu does no longer deactivate the active window. - The menus can now use the blitter instead of windows, wich is much faster. (this has to be activated in the prefs-editor.) - The menu font is now fetched from the DrawInfo, and not the menu's parent window. - There is now a space between the bottom of the text and the bottom of the select bar. - Clicking the mousebutton very fast should no longer result in a menu that doesn't dissapear. (as it should, when you release the button) - Some of the tags send to OpenPopupMenu() has become obsolete. (The preferences has taken over) - The input method has changed, so the library now requires commodities.library (wich is a disk library). - The menu shadows now look like MagicMenu2 shadows. (the size increases for each submenu opened) - Starting with this version, kickstart 3.0 is required. At least for the non-window mode. In window mode it _may_ still work with 2.0, but it's not tested. So if you have ks 2.0, I would appreciate if you could try it out. - Fixed a bug. Submenus could appear at the bottom of the screen when the mouse was moved quickly over an item. - Added a new function, PM_AlterState(). --- 4.3 --- - Fixed a bug. (read from adress 0) --- 4.2 --- - Now the menus can have shadows. --- 4.1 --- - Images are now remapped correctly. - Small changes for colour and image prefs. --- 4.0 --- - More bugs fixed. - A new demo, MenuVerify, shows how to use popupmenu.library with IDCMP_MENUVERIFY. --- 3.6 --- - Bug fix. (never released, i got more bug reports...) --- 3.5 --- - Now checks for the file ENV:PopupMenu.cfg, and if it exists, loads it, and replaces the default settings. - Bug in PM_SubMenuTimer fixed. - PM_Code added. --- 3.0 --- - Added PM_GetItemAttrs(), PM_SetItemAttrs(), PM_IsChecked and PM_FindItem. - Added the tags PM_Left and PM_Top. - Added a few more demos. - Changed the naming of functions and macros to avoid interfering with other libraries. --- 2.0 --- - Entirely rewritten and is now a shared library! --- 1.3 --- - Added submenu support --- 1.2 --- - Lots of new flags, and checkable menuitems --- 1.1 --- - OpenPopupMenuPos() --- 1.0 --- - First release @endnode @node fu "Future" The future: - Asynchronous rendering into the menu through a user defined process under control of the popupmenu.library. This will provide support for cool things such as animations and icons that show up as they are loaded. - Even more control over the layout of items through tables. - Handling of menus that are too large to fit on the screen. - Setting to open submenus only if the mousepointer touches an area close to where the submenu will open. (i.e. somwhere close to the submenu arrow.) - Make all the graphics functions available in the library. (border drawing, 'blitter windows' etc.) - BOOPSI menu item class. - Datatype loading of images. - Font settings. (maybe) - Mail me if you have any ideas! @endnode @node tx "" Special thanks goes to: (in order of apperance) * Stefan Sommerfeld for his nice bugreports, help with the non-window mode, and the remapping code (too bad I coudn't use it :( ). * Trond Werner Hansen for his shadow-drawing code! (Which no longer is in use, since it was slow and buggy... ;)) ) * Mario 'padrino' Cattaneo for all the MagicMenu2 images and the other MM2 specs. BTW, if you don't want to upset him, remember to spell padrino with a small p... ;) * Olaf 'Olsen' Barthel for his useful hint about deadlock detection. * Mattias P. Eriksson for his Enforcer hits * Alfred P. Schwarz for his Enforcer hits * Sebastian Bauer for even more Enforcer hits ;) * Ralph Wermke for the optimized remap code * Brian Gilbert for the icons * Georges Goncalves for being an "endless suggestion list generator" :) * Daniel Kasmeroglu for the E modules and sources * Martin McKenzie for information about MenuVerify * Ian Kumlien, Jerome Chesnot, Burkhard Breuer, Alexander Niven-Jenkins, Stefan Rupprecht and Luca Longone for all their bug reports. * Pavel Narozny for being an extremely devoted beta tester. If there is bug, he'll find it. If not, he'll find it anyway... * Massimo Tantignone for testing of the new shadow code, and for his great VisualPrefs program. * Rafal Kaczmarczyk for information about MenuVerify * Dámaso D. Estévez for the Basic SDK. @endnode @node de "Developer documentation" Some of the links in this section assumes that you have downloaded the developer package. If you haven't, you can get it from www.boing.nu/pm. @{" Run demo" SYSTEM "Demos/Demo"} Run the demo. @{" Important" LINK st} Things you want to know before you start @{" AutoDocs" SYSTEM "multiview popupmenu.doc"} AutoDocs in AutoDoc format @{" AutoGuide" SYSTEM "multiview popupmenu_doc.guide"} AutoDocs as an AmigaGuide document @{" Header" SYSTEM "multiview c/include/libraries/pm.h"} The C header file. @{" Macros" LINK macros} How to use the C macros @{" E-Users" SYSTEM "multiview e/eusers.txt"} Message to E programmers @{" RMBTRAP" LINK menuverify} An alternative to using IDCMP_MENUVERIFY @endnode @node macros "Macros Example" struct PopupMenu *menu; /* Creating a menu with the macros... */ menu = PMMenu("The title of the menu"), End; /* Creating a menu like the one above, but with items... */ menu = PMMenu("The menu title"), PMItem("The item text"), /* Tags for the item */ End, PMItem("The item text (2)"), /* Tags for the item */ End, End; /* Creating a sub-menu for an item... */ menu = PMMenu("The menu title"), PMItem("Item with submenu"), PMSimpleSub, /* Here are the items... */ End, End, End; /* Creating an exclude ID list for PMExclude can be done in two ways. This is the first: */ PM_Exclude, PMExl ExID(1), ExID(2), End, /* This is the second way: */ PM_Exclude, PM_ExLst(1, 2, 3, 0), End, @endnode @node menuverify "MenyVerify alternative" A safer alternative to using IDCMP_MENUVERIFY According to an article on the Developer CD, using MENUCANCEL to abort an intuition menu operation is dangerous. Another way way to block the intuition pulldown menu for certain areas of the screen is to monitor the mouse coordinates and set or clear the WFLG_RMBTRAP flag. When the WFLG_RMBTRAP flag is set, you will receive IDCMP_MOUSEBUTTON messages with MENUDOWN as usual. When the WFLG_RMBTRAP flag is cleared, the pulldown menu will be active and no IDCMP message is sent for RMB. Then when you receive an IDCMP_MOUSEBUTTON with Code set to MENUDOWN, open the popup menu as usual. When the menu closes, you may have to adjust the WFLG_RMBTRAP flag again, since the mouse pointer may have moved while the menu was open. Ofcourse, if you use the pulldown menu feature of popupmenu.library, you don't have to deal with these things at all... The idea of using WFLG_RMBTRAP instead of IDCMP_MENUVERIFY was submitted by Rafal Kaczmarczyk. @endnode