@database ScreenMenu.guide

@wordwrap

@node Main "ScreenMenu Documentation"
@{b}ScreenMenu Version 39.1:@{ub}

    @{b}ScreenMenu - The best screen selector currently available.@{ub}

    @{" Introduction " link Introduction }
    @{" Installation " link Installation }
    @{" About Author " link Author }
    @{" Usage        " link Usage }
    @{" Future       " link ToDo }
    @{" Known Bugs   " link KnownBugs }
    @{" Warnings     " link Warnings }
    @{" History      " link History }
@endnode

@node Introduction "Introduction to ScreenMenu"
@{b}Introduction:@{ub}

    This is a program that patches into the screen depth gadget. Given a certain qualifier, clicking on the screen front to back gadget will produce a menu giving a list of all currently opened screens. The menu is drawn using NewLookMenu colours. The menu is limited to a maximum width of 200 pixels, so if screen names are longer than that, then you won't see the full name.
    This can be useful if for example you have lots of screens, and you want the one at the back to the front. Or if you have a few screens, one of them with a different scanning frequency. If you cycle through them in the usual manner then the monitor may have to resync. This way you can go straight to the screen you want, which may avoid unnecessary monitor blanking/resyncing.

    @{b}ScreenMenu@{ub} requires AmigaDOS 3.0 (version 39) or greater. Apart from that, there are no other requirements.

    This product is giftware. If you like it you could send me money, programs, books, CDs, AVI files (I have written my own AVI player for the Retina graphics card), or anything else you care to send me. Here is my @{"address" link Author }.
@endnode

@node Installation "How to Install ScreenMenu"
@{b}Installation:@{ub}

    Installation is easy!!
    There are to ways to install @{b}ScreenMenu@{ub}:
    * You can drag (or copy) @{b}ScreenMenu@{ub} (and its icon) to your WBStartup drawer.
    * You could copy it somewhere and place an entry in your user-startup like:
        "Run >NIL: <NIL: ScreenMenu >NIL: <NIL:"
@endnode

@node Author "About the Author"
@{b}About Author:@{ub}

    @{b}ScreenMenu@{ub} was written over a period of three (3) days by myself, Stuart MacKinnon.
    If anyone has an idea for a program and they don't know how to do it themselves (as they may not be a programmer), I would be glad to help.
    I can be contacted via Internet (e-mail):
        stuartm@zip.com.au
    Or by snail-mail:
        6/5 Abbey Street
        Randwick NSW
        Australia 2031

@endnode

@node Usage "How to use ScreenMenu"
@{b}Usage:@{ub}

    Firstly @{"install" link Installation } @{b}ScreenMenu@{ub}. Technically you don't have to install it just to test it out. You could just double click on @{b}ScreenMenu@{ub} to start it.
    Once @{b}ScreenMenu@{ub} is running, it is active. You can enable, disable and remove @{b}ScreenMenu@{ub} using the Commodities Exchange. You can also quit @{b}ScreenMenu@{ub} by sending it a Control-C. You can also quit @{b}ScreenMenu@{ub} by running it again.

    @{b}ScreenMenu@{ub} currently has only one option:
        For icon tooltypes, this option is "QUALIFIERS". If it is "NO" then it does not require that the shift key be pressed to activate the menu. The default is "YES".
        For command line options, this option is "NOQUALIFIERS/S". If this option is specified then it does not require that the shift key be pressed to activate the menu.

    If the QUALIFIERS tooltype is "NO", then click on the screen depth gadget as you would normally for the menu to appear.
    If the QUALIFIERS tooltype is "YES" or missing, then to pop down the menu, hold down either shift key while you click on the screen depth gadget. A menu will then appear.
    If you let go the mouse button on the depth gadget it will exhibit its usual behaviour.
    By letting the mouse button go on a selected entry in the menu, that screen will be brought to the front, and its first window will be made active.
    You can use the right mouse button at any time to cancel the menu.
    If you hold down either alt key (as well as either shift key) when selecting the depth gadget, the screen that you select from the menu will be brought to the front AND it will be positioned wholly on screen. Therefore if the screen you select is dragged down, it will be dragged back up for you.
@endnode

@node ToDo "What might ScreenMenu do in the future?"
@{b}Things to do:@{ub}

    There are no things to do to @{b}ScreenMenu@{ub} as it stands at the moment, however there are a few things that may be implemented should there be interest in it. Those features are:
    * Option to specify the CX_PRIORITY. At the moment it has a priority of 0.
    * Options like CycleToMenu to produce a MagicMenu like menu.
    * Option to use SwapBitsRastPortClipRect() for the menu, or a full window. Currently it opens a full window, which means that other programs can still draw to the screen while the menu is down. Using SwapBitsRastPortClipRect (with all the screen's layers locked) would mean that no other applications could write to the screen - just like normal Intuition menus - however given lots of windows on screen around that area, it would be much faster. Because @{b}ScreenMenu@{ub} uses a window, Intuition has to calculate all the ClipRects etc. required to refresh the area behind the menu. Using SwapBitsRastPortClipRect() avoids this behaviour.
    * Option to use a specific font instead of the screen's font.
    * Options to change the qualifier(s) required to activate the menu.
    * Perhaps do the same thing for the window depth gadget to give a menu of windows on the screen.
    * Perhaps give the menu scrolling ability if the list is taller than the screen's height. Currently the menu is limited to the screen's height. At the moment this is not much of a limitation, however if a menu of windows was possible then it is more likely to become a limitation.
@endnode

@node KnownBugs "Known problems with ScreenMenu"
@{b}Known Bugs:@{ub}

    There is one known bug - but it shouldn't affect anybody. To see the bug - which will probably crash your machine - have two menus pulled down a once (virtually impossible), let one go and remove @{b}ScreenMenu@{ub} while the other is menu still pulled down. This will be pretty hard cause the mouse (and your attention) is occupied by using one menu, so you can't pull down the other!
    Other than that, there are no known bugs. If anyone finds any tell me as soon as possible so that I can fix them.
@endnode

@node Warnings "Things to watch out for with ScreenMenu"
@{b}Warnings:@{ub}

    There is only one thing to watch out for. @{b}ScreenMenu@{ub} patches a BOOPSI gadget. This is done by replacing the pointer to the object's dispatcher with a pointer to my function. This is done directly as there is no BOOPSI object patching mechanism like SetFunction(). Therefore SetFunction() managers will NOT manage this patch. If when you attempt to remove @{b}ScreenMenu@{ub}, another program has patched the same gadget, @{b}ScreenMenu@{ub} will inform you. It will still let you remove the patch (for those people who know it is OK to do so). However, if you remove the patch when you shouldn't have, the next time you use a screen or window depth gadget, or a close gadget, or a zoom gadget, or a size gadget or a window title bar the machine WILL crash.

    You have been warned!

    I will not be responsible for any damages caused directly or indirectly by the use of @{b}ScreenMenu@{ub} and any related products (should there be any).
@endnode

@node History "ScreenMenu release history"
@{b}History:@{ub}

    ScreenMenu 39.3 (9.11.95)
        - Can now turn off the qualifier requirement (with tooltype and CLI option). In this case the menu always pops up when you click on the depth gadget. Let the mouse button go on the depth gadget for normal behaviour.
        Third AMINET release.

    ScreenMenu 39.2 (7.11.95):
        - Stupid, stupid, stupid bug! I was holding a lock on the default public screen (which I was using to find a screen depth gadget BOOPSI dispatcher to patch) and would only release the lock when @{b}ScreenMenu@{ub} was quit. This would mean that while @{b}ScreenMenu@{ub} is running you can't change Workbench prefs. This is fixed. It now lets go of the screen lock once it finds the gadget to patch.
        Second AMINET release.

    ScreenMenu 39.1 (1.11.95):
        Initial AMINET release.
@endnode