home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 570.lha / PopUpMenu_v4.2 / PopUpMenu.doc.pp / PopUpMenu.doc
Encoding:
Text File  |  1991-11-05  |  15.8 KB  |  460 lines
  1.  
  2.  
  3.     PopUpMenu V4.2 by Martin Adrian           24/10 -91
  4.     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  5.  
  6.     Introduction
  7.     ~~~~~~~~~~~~
  8.     Are you using QMouse, DMouse, or HeliosMouse and "always" get the wrong
  9.      menues when you press the mousebutton?
  10.     Have you ever needed pop-up menues for your Amiga?
  11.  
  12.     The solution: PopUpMenu
  13.  
  14.     What is it ?
  15.     ~~~~~~~~~~~~
  16.     This small program makes it possible for You to use popupmenues with
  17.      every program that are using standard intuition menues.
  18.      ~~~~~
  19.     The popup-menues works just like the standard pull-down menues for both
  20.      the user (multiple selections, checkmarks, commandkeys) and the
  21.      programmer (MENUPICK and MENUVERIFY).
  22.      All intuition menu-flags (COMMSEQ, HIGHBOX, MENUTOGGLE ...)
  23.      are fully supported.
  24.  
  25.     Features:
  26.     ~~~~~~~~~
  27.     * The menues will not pop-up if any of the following conditions are true.
  28.  
  29.        1) No window is active.                  \
  30.        2) The active window has no menues.          |
  31.        3) The active window has the flag RMBTRAP set. |-  Same as Intuition
  32.        4) The active window has a requester open.     /
  33.  
  34.        5) The mousepointer is in the screens menubar.
  35.       (standard pull-down menues will appear)
  36.  
  37.        6) You are pressing any other mousebutton (left or middle).
  38.  
  39.        7) A stringgadget is active. (Only intuition knows how to deselect them).
  40.       You will have to use pull-down menues.
  41.  
  42.     * You may select if the menues should pop-up when you are pressing
  43.       any qualifier key on Your keyboard or not.
  44.  
  45.     * Click-menues: You make Your selection with the select-button instead of
  46.             holding down the menubutton (works like I*M PC menues).
  47.             Excellent for programs with many menues (e.g. RSDemo).
  48.  
  49.     * PopUpMenu can show a small arrow if a menuitem has subitems.
  50.  
  51.     * MenuItems can be centered around the menu (To minimize mouse movements).
  52.  
  53.     * The program remembers the last menu selected.
  54.     (Works only with items selected with PopUpMenues and does not remember
  55.     different windows).
  56.  
  57.     * PopUpMenu has an intuition interface for setting options.
  58.  
  59.  
  60.    Options
  61.    ~~~~~~~
  62.    In PopUpMenu version 4.0 You may set the following options.
  63.  
  64.    -C Click-menues  If a program has a lot of menues it may be difficult
  65.             to select the one You want.  Click-menues lets You
  66.             slow and easy select it.
  67.  
  68.               1. Press and release the menubutton.
  69.               2. The menues will show up.
  70.               3. Select the menu You want with the selectbutton.
  71.               4. Select the menuitem or subitem in the same way.
  72.               5. You may cancel the menu selection by pressing
  73.              the menubutton again.
  74.  
  75.    -P sub-item Pointer     PopUpMenu will show a small arrow if a menuitem
  76.              has any sub-items.
  77.  
  78.    -S Show single menu     If a window has only one menu, PopUpMenu shows it
  79.              together with the menuitems.  To disable this feature
  80.              turn this option on.
  81.  
  82.                   Show single    Don't
  83.                    +-----+          +------+
  84.              +-----|Items|          |Menu  |
  85.              |Menu |     |          |Items |
  86.              +-----|     |          |      |
  87.                    |     |          |      |
  88.                    +-----+          |      |
  89.                           +------+
  90.  
  91.    -I centered menuItems   When PopUpMenu displays the menu-items it usually
  92.                places the top item next to the menu.  With this
  93.                option on, the items are centered around the menu.
  94.  
  95.                Standard        Centered
  96.                +------+        +------+
  97.                |      |        |     +-----+
  98.                |      |        |     |Items|
  99.                |     +-----+    |     |     |
  100.                |Menu |Items|    |Menu |     |
  101.                +-----|     |    +-----|     |
  102.                  |     |          |     |
  103.                  |     |          +-----+
  104.                  |     |
  105.                  +-----+
  106.  
  107.    -N -Q     These options controls when the menues should pop-up.
  108.          -N means pop-up when No qualifier is pressed.
  109.          -Q means pop-up when a Qualifier is pressed.
  110.  
  111.          (Qualifier = SHIFT, ALT, AMIGA, CTRL)
  112.  
  113.          You may set both (menues will always pop-up) or none (menues
  114.          will never pop-up).
  115.  
  116.    -O         Open the PopUpMenu option window (see below).
  117.  
  118.    -K##      Use this option to set the hot-Key.  If the hot-key is pressed
  119.          together with CTRL + left ALT the PopUpMenu option window will
  120.          show up on the Workbench screen.
  121.          ## means the hex code for the key.  (default = 'P')
  122.  
  123.    -X         This option will remove PopUpMenu from memory.
  124.  
  125.    -H         Display a help message. (The help message will also appear if
  126.          PopUpMenu can't understand Your options)
  127.  
  128.    If You want to disable an option just type a '-' after it (e.g. -O-).
  129.  
  130.    PopUpMenu option window
  131.    ~~~~~~~~~~~~~~~~~~~~~~~
  132.    When You select the -O option, press the hot-key or starts the program
  133.      from workbench a second time, the PopUpMenu option window will show up on
  134.      Your workbench screen.
  135.      In this window You can enable or disable any option (except the hot-key)
  136.      with a mouse-click.
  137.  
  138.    There are four more gadgets in the window:
  139.    Use             - Closes the window and uses the currently selected
  140.                options.
  141.    Reset         - Resets any changes made.
  142.    Cancel         - Closes the  window but doesn't change any options.
  143.                (Same as Reset + Use)
  144.    Remove PopUpMenu  - Closes window and removes PopUpMenu from memory.
  145.                (No "Are You sure" requester will show up)
  146.  
  147.  
  148.    Differences from Intuition:
  149.    ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  150.    Bad:
  151.      Drag-select is not supported (i never use it), Use Multiple selcet.
  152.  
  153.      Menu flag MENUTOGGLED is not supported.
  154.  
  155.      Intuition draws the menues off-screen and then swaps them to the screen.
  156.      PopUpMenu draws the menues on screen.  (I don't want to create a rastport
  157.      just to draw them)
  158.  
  159.    Good:
  160.      The mousepointer don't stop while menuwindows are opened or closed.
  161.      (Makes it easier to select items when your amiga has much to do)
  162.  
  163.    Good or bad ?
  164.      PopUpMenu does not remove any inputevents (RAWKEY, MOUSEMOVE ...)
  165.      while the menues are shown.  (Intuition needs these to move the
  166.      mousepointer etc.)
  167.  
  168.      If a menu does not have menuitems, intuition shows a small empty
  169.      itemwindow.  PopUpMenu does not show anything at all.
  170.  
  171.  
  172.    Same as Intuition:
  173.    ~~~~~~~~~~~~~~~~~~
  174.  
  175.    * PopUpMenu handles multiple selection as silly as intuition.
  176.        Don't select a menuitem more than once or the checkmarks may be moved
  177.        to the wrong item.
  178.  
  179.  
  180.    Installation:
  181.    ~~~~~~~~~~~~
  182.    To use the program put the file `PopUpMenu' and 'PopUpMenu.info'
  183.      in your current directory.
  184.  
  185.    To turn on the pop-up menues just type:
  186.  
  187.      1> Run PopUpMenu  [options]
  188.  
  189.    Default options are     -O -N -P -K19
  190.  
  191.    I don't know how much stack exec and intuition needs.
  192.      PopUpMenu is using less than 800 bytes. Setting stack to 2000 doesn't
  193.      work but 2500 does.
  194.  
  195.    >>>>>> Warning! PopUpMenu is not self-detaching any more. <<<<<<
  196.  
  197.    Arp users can type:
  198.  
  199.      1> ARun PopUpMenu [Options] NOIO STACK 2500
  200.  
  201.      (I suppose RunBack can do the same thing)
  202.  
  203.    If PopUpMenu is already installed you can change or look at the
  204.      current options by starting PopUpMenu again.
  205.  
  206.      1> PopUpMenu  [options]
  207.      PopUpMenu     Current options = -N -P -K19
  208.  
  209.      (Use "-O" option to open the options window)
  210.  
  211.    To turn off PopUpMenu use option "-X" from the CLI or use the
  212.      "Remove PopUpMenu" gadget in the option window.
  213.  
  214.      1> PopUpMenu -X
  215.  
  216.  
  217.    Workbench support
  218.    ~~~~~~~~~~~~~~~~~
  219.    Workbench users may set their options in the "TOOL TYPES" field.
  220.      The options must be proceeded with the keyword "ARG=".
  221.  
  222.      Example:  ARG=-C -P- -O-
  223.  
  224.    (If you enter an illegal line the option window will show up with the default
  225.     options set when You start PopUpMenu)
  226.  
  227.    You can't change the options if popupmenu is already running by changing
  228.    the "TOOL TYPES" line.
  229.    To change the options from workbench use any of the following ways.
  230.  
  231.    1) Use the hotkey to open the option window.
  232.    2) Start the program from workbench again. (The option window will show up)
  233.  
  234.    You may use all options from the workbench but the "-X" and "-H" options
  235.    is not very useful. ("-X -O-" will do nothing at all)
  236.  
  237.  
  238.   Program size
  239.   ~~~~~~~~~~~~
  240.   The program size is much bigger than before but don't worry the memory
  241.     usage is almost the same (~10K).  The code for option parsing and the
  242.     option window are overlayd.  The code and data for them will only be
  243.     loaded only when needed. (Non Hard-Disk users may found the disk
  244.     reads annoying, try to make the PopUpMenu program resident.  I Haven't
  245.     tried it myself, but it should work if You turn any checksum checking off
  246.     (some global data is changed))
  247.  
  248.    Distribution
  249.    ~~~~~~~~~~~~
  250.  
  251.    This version of the PopUpMenu program is released as Public Domain.
  252.                             ~~~~~~~~~~~~~~
  253.      This program can be used, copied, included in a library or commercial
  254.      product as long as You don't do it for profit.
  255.      (Please include PopUpMenu.doc in the copy)
  256.  
  257.      You may also use the source in your own programs (if You can read it),
  258.      If You intend to do a similar popupmenu-program with it please let me
  259.      know so we can cooperate instead of compete.
  260.  
  261.  
  262.    Warnings:
  263.    ~~~~~~~~~
  264.  
  265.    * If a string gadget is active when You press the menu button,
  266.      You will get pull-down menues.  (Only intition or You can deselect
  267.      a string gadget)
  268.      A strange effect shows up if You double click the menu button in the
  269.      req.library file requester.  The first click will deselect the string
  270.      gadget and activate the pull-down menues.    The second click will give You
  271.      popup-menues.  But after a short time (1 second or so) the string gadget
  272.      will be activated again and Your menu selection will be neglected until
  273.      You deselects the gadget.
  274.  
  275.    * QMouse has an inputhandler that sends messages (i think) to its task
  276.       when the mouse are moved over window borders.  When the screen is locked
  277.       QMouse can't activate the window under the mouse but the messages will
  278.       continue to come.  When You are done with the menu selection Qmouse
  279.       will handle all the messages and activate the windows one by one (The
  280.       window titles will flash).  The problem is most annying if You are using
  281.       Click-menues.  I think the problem is the same with Dmouse, HeliosMouse,
  282.       SumMouse etc. (Don't know how about the new commodities)
  283.  
  284.    * Some people have reported that PopUpMenu 3.X does not work with PageSetter
  285.       (both version 1 and 2).  I have tested PS1.2 (a french version) but it
  286.       crashes always on my Amiga (with or without PopUpMenu).  I think PS
  287.       corrupts the FreeMemList when I enter the texteditor.
  288.  
  289.    * Yves Benoit in France, who is the lucky (?!) owner of a A3000, told me
  290.       he had some problems when putting PopUpMenu in the startup-sequence.
  291.       I don't know anything about KS 2.0 so i don't know what the problem is.
  292.  
  293.    * Don't use PopUpMenu with version number 2.XX since they may end up with
  294.       a spectacular crash and a visit to the guru.
  295.  
  296.    * Intuition is a very big inputhandler (i think), this means that intuition
  297.       will lockup the input.device if it tries to draw something (i.e activate
  298.       a window) on a locked screen.  This will lead to a deadlock since my
  299.       program is waiting for mouse-events from the input.device.
  300.       To walk around this I have installed a timer to go off every 0.2s, if
  301.       no inputevents has arrived in this time my program does the following:
  302.  
  303.       1. Remove all displayed menues.
  304.       2. Unlock the screen.
  305.       3. Wait for the input.device to start.
  306.       4. Lock the screen again.
  307.       5. Draw all menues again.
  308.  
  309.       This will make the menues flash once.
  310.  
  311.       (Let's hope intuition works better in kickstart 2.0)
  312.  
  313.    * It is not possible to remove older versions (before 4.0) with
  314.       this program.
  315.  
  316.    * Some programs draw directly into the screen without using the
  317.       layers.library.  Using PopUpMenu on these screens may produce strange
  318.       results.    Only the data on the screen is affected.
  319.       Programs found:  RSDemo, Imploder (4.0)
  320.  
  321.  
  322.    FUTURE:
  323.    ~~~~~~~
  324.  
  325.     User configurable qualifiers for the hot-key (CTRL+LALT is hard-coded now).
  326.  
  327.     Multiple select with Click-menues.    (Don't know how yet)
  328.  
  329.     AREXX port (?!)
  330.  
  331.     The program only remembers the last menu (not menuitem or subitem) selected.
  332.  
  333.     Many people want's the item and subitems to all show up on the same side.
  334.     In the standard case this shouldn't be any problem but I have to think
  335.     about every case.
  336.       - What if it's impossible to open a big menu on any side ?
  337.       - Sub-items are positioned by the application program not PopUpMenu.
  338.     (Maybe I do it one day)
  339.  
  340.    Author:
  341.    ~~~~~~~
  342.      Martin Adrian
  343.      Rullharvsgatan 3A           (New addres from 1-jun-91)            ..
  344.      S-431 47  Mölndal           (the ö is an 'o' with to dots above -> o )
  345.      SWEDEN
  346.  
  347. USENET:  d5adria@dtek.chalmers.se  ( Until June 1992 )
  348.  
  349.    Thanks to:
  350.     Derek Zahn          for the PopUpMenu program on FishDisk 96
  351.     Commodore          for the Amiga
  352.     Arp - people          for Arp 1.3 & AShell
  353.     Lattice           for the C compiler (5.0)
  354.     My English teatcher
  355.     Anna              my girlfriend
  356.     You              for using this program.
  357.  
  358.  
  359.    New in version 4.2
  360.    ~~~~~~~~~~~~~~~~~~
  361.    For safety:
  362.    * Checks that no one has changed SetMenuStrip, ClearMenuStrip, OnMenu, OffMenu
  363.      before they are restored. (If someone has, PopUpMenu waits ~5 seconds
  364.      and then tries again. The PopUpMenu task will not be removed until it is safe
  365.      to do so.    You may start PopUpMenu again)
  366.  
  367.    * My inputhandler now checks if a string gadget is active and if so You will
  368.      get standard pull-down menues.
  369.  
  370.    For Speed:
  371.    * Moved SysBase pointer to the stack. ( = FAST RAM if present)
  372.  
  373.    Bugs fixed:
  374.    * Forgot to change parameters to "HighLight" -> Guru if HIGHIMAGE was used.  (oops!)
  375.  
  376.    New in version 4.1
  377.    ~~~~~~~~~~~~~~~~~~
  378.    For comapbility:
  379.    * MIDRAWN, ISDRAWN, HIGHITEM now supported.
  380.    * MENUSTATE flag supported.
  381.  
  382.    For use:
  383.    * Possible to set options from workbench.
  384.    * Menues no longer flashes when You multiple select a subitem.
  385.    * RMBTRAP is set in the option window.
  386.       (My compiler removed it when compiling with 16-bit ints).
  387.  
  388.    Bugs fixed:
  389.    * Fixed bug that caused a guru if You multiple-selected a disabled item.
  390.    * Fixed bug that always opened the option window. (even with -O- option)
  391.  
  392.    New in version 4.0
  393.    ~~~~~~~~~~~~~~~~~~
  394.    * Command line options.
  395.    * Click menues.
  396.    * + Much more.  Many bugs fixed ( and some new one introduced 8-( ).
  397.  
  398.    New in version 3.7
  399.    ~~~~~~~~~~~~~~~~~~
  400.    For compability:
  401.    * Fixed bug with the checkmark position.
  402.      (Thanks Mark Knibbs)
  403.  
  404.    New in version 3.6
  405.    ~~~~~~~~~~~~~~~~~~
  406.    For compability:
  407.    * PopUpMenu now works when a menu does not have any items.
  408.      (Thanks to Mark Knibbs for finding the bug)
  409.  
  410.    For use:
  411.    * Itemwindow is now positioned in a different way to minimize mousemoves.
  412.      (Thanks to Gael Marziou, France)
  413.  
  414.    New in version 3.5
  415.    ~~~~~~~~~~~~~~~~~~
  416.    For compability:
  417.    * Disabled menues items are now shown.
  418.    * Menues are sorted after their LeftEdge value.
  419.  
  420.    New in version 3.4
  421.    ~~~~~~~~~~~~~~~~~~
  422.    For safety:
  423.    * Now checks to see if screen and window is still present after the
  424.       input.device lockup fix.
  425.    * Rearranged the files so all PopUpMenu hunks shows in Xoper.
  426.       (It should be 3 of them)
  427.  
  428.    For compability:
  429.    * Fixed a small bugs that sometimes made itemwindows to small.
  430.  
  431.    * The program no longer clears the menuitemfield before drawing
  432.       the highimage. (Intuition doesn't)
  433.  
  434.    For Distribution:
  435.    * Now the PopUpMenu.run works (Ver 3.2 didn't  OOPS!).
  436.  
  437.    * Size is now < 7K.
  438.  
  439.    New in version 3.2
  440.    ~~~~~~~~~~~~~~~~~~
  441.    For speed:
  442.    * Some code optimizations (C -> Assembler).
  443.  
  444.    For safety:
  445.    * MENUVERIFY is now fully supported.
  446.    * Forbid() and LockIBase() are now used where needed. (I hope.)
  447.    * Made my own SwapBitsRastPortClipRect.   (No more guru #81000005)
  448.  
  449.    For use:
  450.    * Shows if an item has subitems.
  451.    * Now always shows items & subitems (even if they cover other menuwindows).
  452.    * Now resumes after the input.device lock-up.
  453.  
  454.    For compability:
  455.    * Fixed Fontbug.
  456.  
  457.    New Distrbution:
  458.    * Public Domain.  (i'm not a poor student anymore 8-) )
  459.  
  460.