Amiga Format 15

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

/ Amiga Format 15 / af015.adf / Documentation < prev next >

Wrap

Text File | 1978-01-08 | 20.6 KB | 381 lines

"GET SET GO!" V1.0 RELEASE DOCUMENTATION Written June 1990 by Mark Everingham. INTRODUCTION When producing compilation disks of programs for friends, a public domain disk, or even a magazine coverdisk, one of the key problems is finding a good way to create a menu for the disk. The usual way it seems to be done is to use a string of "echo" or a "type" command in the startup-sequence of the disk, and to set up the Amiga function keys to call the options in the menu using a program such as FuncKey. This is the method used by Amiga Format, and a number of the PD libraries. It does have its advantages, primarily that it requires relatively little disk- space to implement, but it is also in my opinion a rather messy, unprofessional, and not to say tricky way of doing things! "Get Set Go!" is my proposed solution to the problem of easily creating professional looking disk menus. The program will create from a simple text file a complete menu system for your disks, supporting a total of 25 operational and cosmetic features to give your disk menus that professional look. The program is extremely easy to use, and is not too greedy on disk-space, requiring about 15k in all. It is also guaranteed to save you hours of time spent compiling the menu. THE GET SET GO! MENU SCREEN If you double-click on the Get Set Go! icon from the workbench, the program will display its default menu which illustrates the basic features the program offers:- At the top of the screen is the "Banner Text". This is a piece of text which can be used to describe the disk, for example "PD Classics No. 101". The text is printed in double-height, and the color, text and style are all user-definable. In the centre of the screen are the actual menu-options. These are displayed in normal-height and accompanied by a metal-effect function key button. The items are selected either by pushing the relevant function key or clicking on the button graphic with the mouse. The user can define the text, style, color, highlighting style and function of each button. To exit the program without selecting a function you just hit the <ESC> key. At the base of the screen is the "Scroll Text". This is just a piece of text up to around 500 characters which continually scrolls past the screen to tell the user of the menu what to do, or to display all the usual tedious greetings found in disk menus (Hi to Rod, Jane, Freddy etc. etc. etc.). The scroll-text is always displayed double-height, and the color, text, style, speed and direction of scrolling can all be defined. Behind the menu text and graphics are a series of "copper bars" - color bar effects achieved using the copper coprocessor, and a favourite of all Amiga hackers and demo-writers. The user can define the number, style, coloring and direction of the copper bars, or if they are a bit flash for your taste, just turn them off. Across the top and bottom of the screen are two grey lines, the "bar lines", just used to separate the banner and scroll-text from the menu. These may be switched on or off at will. As well as the general appearance of the menu screen, Get Set Go! includes a host of features for defining such essentials as the function a menu option performs in terms of CLI commands, the exit mode of the program, a delay before executing a function, the "Please Wait" text displayed when running a function, and several others. The beauty of Get Set Go! is that even with its many powerful facilities, it is extremely easy to use, and anyone should be able to create an impressive menu display in a matter of minutes, not hours! All you need is the Get Set Go! program, and "your favourite text editor". CREATING GET SET GO! MENU FILES To create a menu using Get Set Go! all you need to do is load up your favourite text editor and start typing. Microemacs or ED which came with your Amiga, or any PD text-editor will do the job fine, or you can use a word-processor capable of ascii output, such as KindWords, Protext or WordPerfect. I used the TextEd+ text-editor when developing the program. All of Get Set Go!'s functions are operated using "pseudo-variable assignments". Put in English, all this means is that, for example if you want to change the banner color, you type "bannercolor=<color>" or if you want to change the scroll text you just type "scrolltext=<scrolltext>". What could be simpler? All variable assignments in your text file must start at the very beginning of the line, and there must not be spaces between the variable name (eg scrolltext) and the equate (=) sign. You can put comments in your text file by preceding them with a semicolon (;) and any invalid lines are just ignored. There is no need to enclose text in quotes as in Basic, and the end of the text is taken to be the end of the current line. Numeric arguments eg colors can be entered either in decimal, or in hex by preceding with a string ($) sign. Some values eg copper steps can be either positive or negative, and can be made negative by placing a minus (-) sign before the number. Note that if you use hex notation ($HHH) to enter color values, this is equivalent to using RGB values, for example $123 = 1 red, 2 green and 3 blue. This makes specifying colors very easy, although you can use decimal if you prefer. You give Get Set Go! its commands just by entering a number of assignments, one per line, into your text-editor and then saving them as a text file. When you have done this, to run Get Set Go! you just type from the CLI:- RUN "GET SET GO!" <name of your menu file> If none of your menu options needs a CLI window to operate, you can use "RUN >NIL: ...." to get the CLI to close. If you don't specify a file- name of a menu file, Get Set Go! will display its default menu screen. If the file you have specified cannot be found, an error is generated. Listed here are all the variables or commands you can use in your menu text file, along with descriptions of their use. All commands may be entered either upper or lower-case. You can use the functions in any order in your file, and can even specify them more than once. If you specify a function several times, the last valid occurence is used. Variable Function -------- -------- BACKCOLOR=<rgb> This variable specifies the RGB values of the background color. Note that if the copper is on, this will have little effect. BANNERCOLOR=<rgb> This variable specifies the RGB values of the banner-text color. MENUCOLOR=<rgb> This variable specifies the RGB values of the menu-text color. SCROLLCOLOR=<rgb> This variable specifies the RGB values of the scroll-text color. SCROLLSPEED=<speed> This variable specifies the speed at which the scrolltext moves. The value must be either 1, 2, 4, or 8. If you specify a negative value -1, -2, -4 or- 8, the scroll-text moves backwards! BARLINES=<ON/OFF> This variable simply specifies if the bar-lines are switched on or off. MENUPOSITION=<TOP/CENTRE> This variable specifies whether the menu options will appear at the top or in the centre of the screen. Note that this variable only works when the menu mode is "flush". MENUMODE=<FLUSH/ALIGNED> This variable specifies whether menu items appear flush, with no spaces between lines, or aligned according to the number of the function key. For example, if flush, options F1, F3 and F6 would appear immediately one after another. If the mode is aligned, there would be a blank line between F1 and F3, and two between F3 and F6, to account for the missing menu options. HILITEMODE=<OFF/BUTTON/BOX> This variable specifies the way in which the menu button graphics are highlighted. If Off, there is no highlighting. If Button, the "Fn" text on the button graphic is highlighted in the banner color. If Box, a box is drawn round the button in the banner color. COPPERMODE=<OFF/SINGLE/DOUBLE> This variable selects whether the copper display is Off, or consists of Single or Double bars. Single bars go from the Start color to the End then jump back to the Start again. Double bars go from Start to End and back again. COPPERLINES=<lines> This variable specifies the number of lines of color in the copper display, from 1 to 256. If 1, the copper color never changes. If 256, it changes every scanline. COPPERSTART=<rgb> This variable specifies the starting color the copper uses for its bars, as an RGB value. COPPEREND=<rgb> This variable specifies the ending color for the copper, as an RGB value. COPPERSTEP=<rgb step> This variable specifies the value the copper adds to its current color each time it draws a new band of color on the display. This can be either positive or negative, for example if the end color is less than the start color. BANNERTEXT=<text> This variable specifies the text displayed at the top of the Get Set Go! screen, up to 40 characters in length. SCROLLTEXT=<text> This variable specifies the text scrolled across the base of the Get Set Go! screen, up to around 500 characters long. SCRIPTTEXT=<text> This variable specifies the text which is displayed at the base of the screen while Get Set Go! is running a menu function. MENUTEXT<number>=<text> This variable specifies the text displayed for menu option <number> on the screen, for example MENUTEXT5=Menu Text 5. If you specify null text (MENUTEXT<n>=) then the menu option and its button are not displayed at all. If you specify a caret (^) character, a blank line with no button is displayed. BANNERSTYLE=<style> This variable specifies the style of text used for the banner-text. For all the style variables, you specify the style as a number by adding up the values below:- 1 = Underline 2 = Bold 4 = Italics SCROLLSTYLE=<style> This variable specifies the style of text used for the scroll-text. MENUSTYLE<number>=<style> This variable specifies the style used for menu text <number>. You can specify a different style for each menu option. MENUFUNCTION<number>={} This variable specifies the actual work that a menu option carries out. You specify this as a number of CLI commands. These must be enclosed within opening and closing braces ({ and }) and these braces must each be at the start of a new line. For example, to get menu option F1 to print a directory to the CLI window, then run your latest shoot'em'up you use:- menufunction1= { DIR RUN MYLATESTSHOOTEMUP } EXITMODE=<ON/OFF> This variable specifies if when a menu option has been executed Get Set Go! exits immediately or gives you the chance to execute another function. If On, Get Set Go! exits imnmediately. SCRIPTDELAY=<delay> This variable specifies a delay for which Get Set Go! pauses before executing a menu function. You specify the delay in 10ths of seconds, for example SCRIPTDELAY=100 gives a delay of ten seconds. SCREENTOBACK=<ON/OFF> This variable specifies if while executing a menu function the Get Set Go! screen is pushed to the back to become invisible, or not. For example, if you want to do a disk directory you can force the screen to the back so that you can see the directory listing. When finished, the screen will pop back to the front again. This only works when the exitmode is Off. THE GET SET GO! ERROR MESSAGES In order to keep Get Set Go! as compact as possible, the program does not generate actual text error messages, but instead uses error numbers like AmigaDOS. When RUNning the program, if an error occurs a message will be displayed such as "GET SET GO! failed returncode <n>" where <n> is the error number. These error numbers are explained here. Error Meaning ----- ------- 101 This error is generated by the intuition library failing to open. You should never see this error unless (a) the Get Set Go! program has been corrupted, or (b) you've have been doing some pretty wierd things to your Amiga. 102 This error is the same as the above, but signals the graphics library failing to open. 103 This error is caused by Get Set Go! being unable to open its screen. The most common cause for this is just lack of chip memory. Free some and try again. 104 This error is caused by a failure opening Get Set Go!'s backdrop window. Again, this is usually caused by lack of memory. 105 This error is caused by an error while creating the user's copperlist for the Get Set Go! screen. As ever, lack of memory is probably the cause. 106 This error signals that Get Set Go! could not open the menu file you specified in the command line. This is usually caused by a typing mistake in the file or pathname. 107 This error is generated when an error occurs while reading the user's menu file. This is generally caused by a corrupted disk. 108 This error is flagged when Get Set Go! cannot open its temporary script file needed to execute a menu function. The program needs to be able to create a file "ram:get_set_go_script_file" to work, so this may be caused by a write-protected file of this name already existing, or a lack of the RAM: device - You must have the "Ram-Handler" file in the L directory of your system disk. 109 This error is caused by an error while writing to the temporary script file mentioned above. The most likely cause is shortage of memory or a crashed Ram-Handler. THE GET SET GO! DEFAULT MENU FORMAT Below is a listing of the equivalent text file which Get Set Go! uses as its default. This shows how the various variables are initially set up if you don't explicitly specify them in your menu file, and serves as an example on setting up your own menu files. As in any program, the best way to learn is to look at an example, then experiment. BACKCOLOR=$000 MENUTEXT1=CORRESPONDENCE TO:- BANNERCOLOR=$F00 MENUTEXT2=^ MENUCOLOR=$FFF MENUTEXT3=MARK EVERINGHAM SCROLLCOLOR=$0F0 MENUTEXT4=17 COLLINGWOOD ROAD SCROLLSPEED=1 MENUTEXT5=REDLAND BARLINES=ON MENUTEXT6=BRISTOL MENUPOSITION=CENTRE MENUTEXT7=BS6 6PD MENUMODE=FLUSH MENUTEXT8=ENGLAND HILITEMODE=BUTTON MENUTEXT9=^ COPPERMODE=DOUBLE MENUTEXT10= 1990 BY FREUDIAN COPPERLINES=64 SLIPZ COPPERSTART=$000 BANNERSTYLE=0 COPPEREND=$00F SCROLLSTYLE=0 COPPERSTEP=$001 MENUSTYLE<1-10>=0 BANNERTEXT=GET SET GO! MENUFUNCTION<1-10>= SCROLLTEXT=`GET SET GO!'... EXITMODE=ON SCRIPTTEXT=*** PLEASE WAIT *** SCRIPTDELAY=10 SCREENTOBACK=ON TECHNICAL DETAILS, UPDATES ETC.. Get Set Go! v1.0 was written on an Amiga A500 V1.2 with twin drives and 1Mb ram. The software used was Manx Aztec C v3.6a, the Manx SDB, and Hisoft Monam v1.2. This documentation was prepared using WordPerfect v4.19. The Get Set Go! system requires about 15k of disk space, and needs the Ram-Handler, Run and Execute commands to be available on the system disk. The program is completely legal, using only approved methods for such things as keyboard and mouse reading, and screen control. If any reader would like a copy of the source, or has any suggestions for improvements to the system for a later version, I would be very please to hear from them. The program has been written in such a way as to make enhancements very easy to implement. For the source-code, please send a disk (and some PD software will guarantee you a friend for life!). An SAE would also be greatly appreciated. Write to:- Mark Everingham 17 Collingwood Road Redland Bristol BS6 6PD ENGLAND