BCI NET

home *** CD-ROM | disk | FTP | other *** search

/ BCI NET / BCI NET Dec 94.iso / archives / diskmags / adm121.lzh / ADM1.21 / ADM.DOC < prev next >

Wrap

Text File | 1992-09-02 | 17.7 KB | 445 lines

_______ /////\\\\ //// \\\\ //// === \\\\ //// \\\\ //// \\\\ M I R A G E D I S K M E N U Documentation. =================================== ADM V1.21- A Public Domain Disk-Menu Selector. Written by Ian Goffe (Kryten) of AMIRAGE in 1992, 1993. V1.21 preamble. --------------- For those that are familiar with the original release of the Amirage Disk Menu system (adm v1.1a), please note the following features/ additions present under v1.21:- - ADM v1.21 has been tested on both a 1 meg A500, and an A1200 (ks3.0) - AGA 'n' all! The original release of ADM unfortunately refuses to work with an A1200; I have now tried to make this version much more compatible ON ALL AMIGAS..There SHOULD be no reason that it will not work on an A600/A4000, or infact future Amiga models... but, I haven't been able to test it on these machines. In general, ADM V1.21 SHOULD WORK FINE ON ALL AMIGAS! - The 'star' field mode of v1.1a has been replaced by a much more useful 'Info' button, this allows 'general text' to be read for any menu selection, without leaving the menu system. (See relevant section within this documentation on INFO_TEXT). - A more up to date Protracker replay routine has been incorporated - ADM can be 'iconified', thus allowing it to be used in a true multitasking environment. - Snazzier 'bass-relief' on play/pause buttons when pressed (Just thought that I'd mention it...) For those that have used V1.1a, PLEASE READ THESE DOCS, AS THERE ARE SOME CHANGES IN ORDER TO SET UP A DISK, ETC.......... What is the Amirage Disk Menu? ------------------------------- - The AMIRAGE Disk-Menu was designed to give compilation disks a more professional look. Most compilations are put together relatively quickly with the use of a key-map editor, such as SETKEY; but a 'glossy' display is pretty difficult to show on ye old workbench screen, isn't it? Ok, so other menu-systems have been written, eg. Menu Master (rather old now, I know, but it gives you an idea!), but I think you will like the features of ADM:- - Upto 30 mouse-driven menu selections. The menu titles and associated cli line-calls are defined within a standard ASCII file. - Optional music can be played in the background; the filename/path of the module is given as a parameter to the routine. - The modules can also be in a crunched format with the use of Powerpacker, or a PP-compatible cruncher! The following module-types can be loaded directly, as ADM automatically distinguishes between the re-play routine required:- Soundtracker V2.xx/Noisetracker/Protracker. MED V2.10-V3.xx/Octamed (4 channel!) Modules. Games Music Creator. Soundmon. Jamcracker. Future Composer. - IMPORTANT NOTE:- The music must be in MODULE format, as for eg. MED SONGS are commonly used, but will not work - use MED MODULES! If the module type cannot be determined by the routine, ADM jumps automatically into GMC-replay mode; this is because I cannot find how to distinguish whether a module was written in GMC. (If you know better, please contact me!) - VU-Meter (Level indicator). Well, this is just a nicety, but a pretty one at that! - Info Text, giving general background information, pertaining to a menu selection. - Scroller - Your own scroll text can be incorporated into the menu!!! - PAUSE and PLAY music. - Saving of configured scroll colour/music mode settings, as configuration file. - Possible to force ADM to be iconified for a given menu selection. This is useful if the option attempts to 'run in the background', such as 'Powerpacker' or 'Dirworks'. (Unlike v1.1a of adm, which had to be terminated.. oops!) Instructions. ------------- Follow the guidelines below, to set up a disk in order to use ADM, and all should be hunky-dorey!!! Pre-requisites -------------- - The "run" and "execute" commands are expected in the /c directory of the boot disk. - A file called 'MENU_TEXT' should be kept within the current directory; it contains the names to be displayed within the menu, and also the disk-title, along with the cli-commands, that invoke the selected program. The format of this Ascii file is... Disk Title (Max 20. characters) Selection 1 (Max 18. characters) Selection 2 " Selection 3 " etc... Last Selection name " L E A V E A B L A N K L I N E H E R E ! cli-command line to run selection 1 cli-command line to run selection 2 ...etc. The first title is the main heading for the menu, the next lines of text are the program names, that are displayed within the menu-screen. A blank line should then be inserted, which delimits the menu-text-definitions, and the cli-commands that are used to call a given program. There now should follow - again, on separate lines - the cli-commands to invoke the respective selections, in the order that they are defined within the menu- display definitions. ADM automatically recognises how many selections are possible, and acts accordingly. If ADM cannot find the MENU_TEXT file, it will display a message, stating how naughty you have been, and exit! One final note on setting up the MENU_TEXT file, is that if you execute a program that automatically runs-in-the-background (eg. powerpacker), it may be necessary to force ADM to iconify; This stops a chain-effect occuring if the script file that is handling the menu selections loops back into re-calling the menu-process after every program is called. To force ADM to become iconified, you must insert an asterisk (*) before the said cli-command definition. Note that this differs from v1.1a of ADM, as before a '*' denoted 'exit to cli'; now, a '*' forces ADM to become iconifed.. ie. MUCH BETTER, and allows ADM to be used in a true multitasking environment. To illustrate the information given above, take a look at an example MENU_TEXT file to process 4 selections. Note that each definition must be on a separate line. The main points worth noting, are 1) the blank line after the final menu-display line, and 2) the asterisk prior to calling powerpacker, (ie. ADM becomes iconified after invoking Powerpacker). The example is listed below. <START> of file...MENU_TEXT Main Menu Title Noisetracker MED V3 MED Main Doc. Powerpacker Utils/Noisetrack Utils/MED/MED More df1:documentation/med.doc *utils/powerpacker <END> of file... MENU)TEXT - The file:- "Powerpacker.Library" (which should be on the same disk as this documentation!) is required in the LIBS directory of the boot-disk. - Scroll text file (Optional). To use your own scroll text, copy a standard ASCII file called "SCROLL_TEXT" into the current directory. The first 8K (8192 bytes) is loaded of any scroll-text, which should be more than enough!!! Any text editor can be used to enter the text, as ADM reads over a line feed character, without displaying it! There are some additonal character codes that can be added to your scroll text..... ^ - Loop to start _ (Underscore) - Freeze text \ - Fast scroll | - Slow scroll - NEW FOR V1.21 Information text file (optional). A file called 'INFO_TEXT' can be present within the current directory, and contains text, that is displayed for the selected option. The format of the info-text file is basically the text (upto a display screen in height) for each selection, delimited by a hash character (#). eg. filename:INFO_TEXT:- (text for 4 options) <START> of file...INFO_TEXT Starting here, is the text that is displayed for selection 1 from the menu.... # This is the text for option 2, as the hash character (above) signified the end of the option-text, for option 1... # Now we are on option 3 # # The two hash-chars above meant that no text was declared for option 3, and this text is infact relevant to option 4 <END> of file...INFO_TEXT - Note that the INFO_TEXT is for a lo-res (around 40 characters per screen row) screen image. Program Control --------------- Program selection - This couldn't be simpler; just click on the red marker, adjacent to the required selection. To load the selection, click on the load gadget (as detailed below). On-Screen gadgets - To the left of the display are four gadgets, that are, in order of screen display:- INFO - Displays information-text relevant to the currently selected option, as defined in the optional file:- INFO_TEXT. (Right mouse to exit back to menu). COLOUR SELECTION - Allows selection of one of the pre-set scroll colours ABOUT - Some info about ADM. (Right mouse to exit back to menu). LOAD - Loads the current selection. Redefining the default display - To enter ADM with a different combination of colour or music pause mode, click on the save gadget (top right of display). This quits from ADM, but in the process, saves out a file to the current directory, called ADM.CFG. The file is read from disk, each time the menu is called, and reverts to the previously saved display/audio parameters. If music was requested - Two control "buttons" are available to play, and pause the music, from left to right, respectively.The current mode, as defined by these two gadgets, is saved as part of the menu configuration file. These gadgets will be out of the NTSC display-area, but are not of prime importance for the ADM to operate! Use of iconify option - If a selection is executed, and ADM is iconified (see above section on iconification), the menu can be exited by selecting the 'ADM-ICONIFIED' window, and closing it. Similarly, the menu can be re-launched by clicking on the 'ADM-ICONIFIED' window, and launching with the RIGHT MOUSE BUTTON. Invoking ADM ------------ The ADM routine is generally invoked from the CLI with the following call:- ADM [drive:Name of Music Module] eg. ADM df1:music/modules/mod.sounds_good. If there is not enough chip-memory for a music module, the music will not be loaded, but the menu will still be entered. This is useful if you have a wicked piece of music, but it needs more memory than a humble 512K can afford. Therefore, it would be fine to request the same module from a 512K machine, or an Amiga with >512K chip-mem, the only difference is that it will load into >512K, but not, with no adverse effect into 512K. Note that if you don't require any aural ambience, and a QUIET life is all that you are looking for, then just call ADM with no parameter! (Enough of my author-esque lame comical style...) After calling ADM, the execution routine (ADM_CALL) must be called... See below for how to use these routines:- Control of selections. ---------------------- In order to operate in a multitasking environment, the recommended way to use ADM is to set up a 'loop' within a script, my example below (example_menu_script) uses the AmigaDOS commands LAB, and SKIP. This script basically calls ADM followed by ADM_CALL.. The executable file 'ADM' handles the menu display and selection, and 'ADM_CALL' performs the actual execution of the selected program. The script can then be run in the background for multitasking capabilities by issuing the statement:- RUN EXECUTE EXAMPLE_MENU_SCRIPT This is best used with a combination of the s/startup-sequence file, as shown below:- File: S/STARTUP-SEQUENCE ~~~~~~~~~~~~~~~~~~~~~~~~ run execute s/example_menu_script File: S/EXAMPLE_MENU_SCRIPT ~~~~~~~~~~~~~~~~~~~~~~~~~~~ LAB START adm1.21/adm modules/mod.gregorian3 adm1.21/adm_call SKIP "START" BACK Summary of Requirements. ------------------------ RUN and EXECUTE - Copy from your workbench disk (in C directory), to the C directory of the bootdisk. (nb. LAB/SKIP required if using example menu script) POWERPACKER.LIBRARY - In /LIBS directory of bootdisk MENU_TEXT - In current directory - holds text display for menu, and cli-command calls. ADM - Call to obtain selections ADM_CALL - Call after ADM, to execute progs! Optional files -------------- SCROLL_TEXT - Ascii file in current directory. INFO_TEXT - " ADM.CFG - Configuration file, containing pre-set colours/music/starfield settings, as saved from ADM. Distribution. ------------- This program is Public Domain, and can be freely distributed. However, it is appreciated if ALL of the files are included for distribution, as outlined below:- ADM1.21/ADM - ADM - Main program ADM1.21/ADM_CALL - Execution routine ADM1.21/ADM.DOC - (This .doc file - IMPORTANT!!!) LIBS/POWERPACKER.LIBRARY - A copy of Nico Francois's Powerpacker library. OR just distribute the archive (ADM121.LHA), which contains all the necessary files in a single archive. Thanks/Additional Credits, or Just hello's. ------------------------------------------- Nico Francois for Powerpacker.Library. All the guys ever responsible for the Protracker replay source. Teijo Kinnunen for the MED replay source. M. Gemmel for the Jamcracker replay source. Generally, all original authors of the music-replay routines! Metallion - Kefrens, for the 16x16/8x8 fonts. Mark Dow (Xylyon/Amirage) (for just being an Amirage person) Thanks for the invaluable information given from the 'howtocode' series (tar..Share and Enjoy) Paul Eltan Shaw (Terminator/Banzai Maraunder Productions) for being a sound contact. NBS PD. for giving us a good review (last time) Developed with:- ---------------- * Code - Hisoft's Devpac V3.01 Assembler. * Graphics - Deluxe Paint IV - Kefrens IFF Converter * Packed - Powerpacker Finally.... ----------- I Hope the information given in this documentation is comprehensible, in order to set up a disk for use with ADM.. If all else fails, try to see how the 'release disk' is set up. If you don't have the release disk, check the archive for the basic 'skeleton' for ADM to operate. I don't know how much time I'll have for updates, etc, but if you need to contact me, then try..... Ian Goffe 60 Ravenhill Drive Codsall Staffs WV8 1BL ENGLAND. Preferably, I can be contacted on Internet, until around June 1994. cm4266@scitsc.wlv.ac.uk Wibble, and out. IJG (Kryten), 16th July, 1993.