Short: Powerful requester package. A *MUST HAVE* for programmers and users. ********************************** reqtools.library The requester toolkit. Release 2.1 (c) 1991/1992 Nico François ********************************** 1. Introduction =============== reqtools.library is a standard Amiga shared, runtime library. The purpose of ReqTools is to make it a lot quicker and easier to build standard requesters into your programs. ReqTools is designed with Commodore's style guidelines in mind, all requesters have the look-and-feel of AmigaDOS Release 2. If you use ReqTools in your programs you do not have to worry about requesters too much. You'll have a lot more time to concentrate on the really important stuff your program does. The library has been inspired by req.library (by Colin Fox & Bruce Dawson) and Commodore's own asl.library. You will find it shares a lot of the features with these two libraries, while it has some additional ones as well. While asl.library was great in look-and-feel I felt it lacked quite a bit in the power department. This power _is_ mostly available in req.library, but this doesn't fit in too well with AmigaDOS Release 2. So the idea for a new requester library was born. I tried to make all requesters in ReqTools very powerful, easy to use and with a very nice new-look 3D interface. Efficiency was also considered very important. The 2.0 version of the library is about 37K large. I'm sure you will agree this is not too much considering what ReqTools offers. ReqTools features the following requesters: a query requester, a string requester, a number requester, a file requester, a font requester, a palette requester and new in release 2.0 of ReqTools a volume requester and a screen mode requester. 2. Features =========== The requesters have following features (features marked with *NEW* are new features for release 2.0, version 38 of ReqTools). All requesters: o have a pixel-perfect Workbench 2.0 3D look, also on Kickstart 1.3. *NEW* o Completely localized! If you are using Workbench 2.1 or higher the text in ReqTools requesters will appear in the language of your Workbench (if the catalog for this language is available). o adjust to interlaced screens and to the screen's font (rtEZRequest, rtGetLong, rtGetString) or to any fixed-width font if the screen's font is proportional (rtPaletteRequest/rtFileRequest/rtFontRequest). *NEW* Requesters can also use any suitable font you specify. o can appear under the mouse pointer, centered on the screen/in a window or at the top left of the screen/a window. o can be used asynchronously. o check pr_WindowPtr of your process is to find the screen they should appear on (can be overridden). o use tags for maximum future extendibility. All standard 2.0 tags are supported (like TAG_SKIP, TAG_MORE, etc.). o bring the screen they appear on to the front. The screen that was in front previously will be put in front again when the requester finishes (if it is still open). *NEW* This behaviour can be switched off. o will always appear in the visible portion of the screen (support of virtual screens). o are extensively tested using enforcer and mungwall debugging tools. *NEW* o have the ability to lock the parent window from all user input and give it a standard wait pointer automatically. *NEW* o can share the IDCMP port of the parent window. *NEW* o supports a callback hook for handling IDCMP messages from a shared IDCMP port. *NEW* o have keyboard shortcuts for gadgets (key underlined in gadget label). Use Right Amiga key with shortcut if a string gadget is active. rtEZRequest, the query requester: o easy keyboard shortcuts: - Left Amiga V and Left Amiga B (like the standard requesters). - Y for positive response. - N, R, Esc for negative response. - Return can also be used as a shortcut and can be associated with any response. The gadget in question will have its text printed bold. Default response for Return is the positive response. - buttons give visual feedback when keyboard shortcuts are used. - keyboard shortcuts can be canceled by pressing Shift before releasing the key. *NEW* - keyboard shortcuts can be defined to be any character in the button's label. The character in question will be underlined. o number of responses only limited by screen width. o allows for multiple lines of text. o text can be centered in requester (great for about requesters). o supports the use of 'printf' formatting codes in text and in responses. o can be terminated by IDCMP events. rtFileRequest, the file requester: o similar in use and look-and-feel as Asl file requester. o buffers directories in memory. o files and directories can be added or removed from the buffer by the calling program. o can be put in save mode, disabling double-clicks and asking you if directories that can't be found (entered manually) should be created. o optional callback hook for verification of files before they are added to the buffer. o supports multiple selection of files and optionally of directories. o when multi-select is on All, Clear and Match.. buttons are available. All selects, and Clear unselects all files. Match.. brings up a requester where the user can enter a pattern to select files. o can be used as a directory requester (showing no files). o optional pattern gadget to match files on. o shows all devices (with volume names) and all assigns made. o supports TABCYCLE under 2.0 o pattern matching supports _ALL_ AmigaDOS 2.0 patterns. *NEW* o can be used as a volume requester to get a device or an assign from the user. *NEW* o can be resized in height to show more files. *NEW* o Shows disk percentage used next to volume names. *NEW* o Allows you to enter paths in the filename string gadget. If the requester finds a path in the filename it will change the directory to that path. So if you e.g. enter 'Devs:mountlist' in the filename gadget the requester will read the 'Devs:' directory and set the filename gadget to 'mountlist'. If you enter 'printers/' it will go into the printers directory. Enter '/' to go to the parent directory. *NEW* o Completely keyboard controlable: use up and down cursor keys to select files or directories. Use Shift-Up and Shift-Down to jump by one window-full. rtFontRequest, the font requester: o buffers all fonts in memory. o shows sample of font you click on. o can be also be used to select the font's style. o supports color fonts, can change the screen's palette. o supports scaled fonts (AmigaOS Release 2 only). o optional callback hook for verification of fonts before they are added to the buffer. o supports TABCYCLE under 2.0 *NEW* o can be resized in height to show more fonts. *NEW* o makes sure selected font is visible in listview when it comes up. *NEW* rtScreenModeRequest, the display mode requester (Kickstart 2.0+ only!): *NEW* o all modes in the DisplayInfo database can be displayed. *NEW* o allows you to pick a standard overscan setting. *NEW* o user may enter prefered size or choose to get the defaults. *NEW* o number of colors selectable. *NEW* o can be put up with the attributes from a given screen. *NEW* o optional callback hook for examining a display mode before it is added to the requester. *NEW* o can be resized in height to show more modes. *NEW* o makes sure selected mode is visible in listview when it comes up. rtPaletteRequest, the palette requester: o features Copy, Swap and Spread functions. o current values of red, green and blue are displayed. o returns the selected color. rtGetLong, the long integer requester: o width of requester can be set by caller. o a minimum and maximum can be supplied and will be displayed in the requester. o a value to show up when the requester appears can be supplied. *NEW* o can display buttons with several possible responses. *NEW* o invisible entry is possible (useful for getting a code number). *NEW* o patterned backfill of requester can be switched on or off. *NEW* o some line(s) of (centered) text may be displayed above the entry gadget to give the user some extra information. rtGetString, the string requester: o width of requester can be set by caller. o a string to show up when the requester appears can be supplied. *NEW* o can display buttons with several possible responses. *NEW* o invisible entry is possible (useful for getting a password). *NEW* o patterned backfill of requester can be switched on or off. *NEW* o some line(s) of (centered) text may be displayed above the entry gadget to give the user some extra information. LIBRARY HISTORY: ***************************************************************************** RELEASE 2.1 (Library version 38.382 [1.3] - 38.961 [2.0]) New major feature: ReqTools preference editor (Kickstart 2.0+ only)! o Switch screen to front popping on/off. o Display drawers before files in file requester. o Mix drawers and files in file requester. o Sort entries in file requester immediately. o Set default position of all requesters. o Set default size of file, font, screenmode and volume requesters. o Set minumum and maximum number of entries visible in file, font, screenmode and volume requesters. Kickstart 2.0 (or higher) version of ReqTools only: o The file requester will keep its top entry up to date with what is typed in the filename string gadget. Pressing the up or down arrow will select the file that most closely matches the contents of the filename string gadget. o Entering of pathnames in the filename string gadget has been improved. The file requester will now check if what you enter is a directory. This allows you to enter directories without a trailing '/' (for example 'SYS:c'). o rtSetWaitPointer() and rtLockWindow() will set the standard Intuition wait pointer on Kickstart 3.0 machines. Note that rtUnlockWindow() will _not_ restore the original pointer if it was a new pointerclass pointer (Kickstart 3.0)! o File requester is an AppWindow now. This means you can drop disk, drawer or file icons on the requester's window to go to a directory or select a file. o All requesters now set an appropriate bitplane write mask in the rastport of their windows. This makes them render and scroll much faster on a screen with lots of bitplanes/colors. Available system fonts will now be buffered for _all_ font requesters. This speeds up font requesters enormously, a font scan is generally needed only once now. The version of ReqTools for Kickstart 2.0 (or higher) has been made intelligent enough to see if the assign has been changed between two requests. ReqTools will free the buffer when memory gets low. Note that to accomplish this ReqTools keeps its library open count 0. A real open count is kept internally. File requester will no longer show deferred (late) assigns. Several bug fixes: o Small bug: was no longer possible to exit volume/assign list by pressing Return in the drawer gadget without changing the directory. o Fixed weird bug with the selection of listview entries. If you selected a non-existing item and dragged the mouse up, an item above all others would be complemented. Thanks to Mathias Korsbäck for reporting this. o No longer goes into an endless loop when LOCALE: could not be found when a catalog had to be loaded. Thanks to Holger Kruse for reporting this. o Resizing a file requester with an inexisting directory and with the volume list displayed resulted in a crash. o Some other miscellaneous bugfixes. Norwegian catalog file included (thanks Mario). Improved and bug fixed Dice C libraries included (by Magnus Holmgren). Includes libs for small code model, large code model and both of these with the arguments passed in registers. M2Amiga interface updated for ReqTools V38 by Frank Lömker. PCQ Pascal interface to the library included, written by Chris Pressey. Version 1.1 of RTPatch included. ***************************************************************************** reqtools.library written by Nico François (Yes, Nico is my first name :-) Thanks to o Kai Bolay for writing the Oberon interface, o Frank Lömker and Michael Griebling for writing the Modula-2 interfaces, o Jan van den Baard and Magnus Holmgren for writing the Dice C libraries, o Martin Steppler for writing the Manx C libraries, o Richard Waspe and Gunter Indenhoek for writing the HighSpeed Pascal interfaces, o Chris Pressey for writing the PCQ Pascal interface, o Federico Giannici for the useful suggestions, o Peter Stuer, Gunter Indenhoek, Jorrit Tyberghein, Ives Aerts, Bert Wynants, Mathias Korsbäck, Christoffer Zettermark and Roger Nordin for beta-testing, o Michele Giorato for the Italian catalog translation, o Patrik Nordvall for the Swedish catalog translation, o Per Jacobsen for the Danish catalog translation, o Mario Gonzalez for the Norwegian catalog translation, o Herman Stevens for being my Fido boss node and having such a great Amiga BBS, o All registered ReqTools users/developers. "What you got buried? In your backyard What secret do you sleep with when the black moon comes?" - The Black Crowes (C) 1991/1992 Nico François // Thanks to \X/ Amiga for being the best computer ever !