home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format 31 / af031.adf / Console.Doc / Console.Doc
Text File  |  1991-12-16  |  18KB  |  379 lines
  1.                       Control Console Documentation. V3.5
  2.                             ©1991 By Alexander Kerr.
  3.                       This document produced on 8/7/1991
  4.  
  5. All rights reserved.
  6. DISCLAIMER: No responsibility can be taken on the part of the author for
  7. any consequences that may occur as a result of using this program. Every
  8. part of the program has been thoroughly tested to its specified limits and
  9. any known specific limitations of the program are stated within this
  10. documentation.
  11.  
  12.  
  13. CONTENTS:-
  14.  
  15. 1. ........ Introduction.
  16. 2. ........ Creating a menu.
  17. 3. ........ General use of the program.
  18. 4. ........ Credits, Greetings, Pleas for money, Other things.
  19.  
  20.  
  21.  
  22.  
  23.                           1. INTRODUCTION
  24.  
  25.    Control Console (from here on referred to as Console) is a program for
  26. creating and (mainly) using disk menus. Before you say "c'mon I've already
  27. got one of those!", just let me tell you about this one. Having compared
  28. several (5 or 6) disk menu programs from the grim to the pretty good I
  29. realized that although they each had their useful features, none had
  30. everything I wanted in one, simple to use package. So, I went and created
  31. my own. 18 months in development and 3 revisions (this the first to be
  32. spread in the PD) later and Console's what I've come up with. An all
  33. singing, all dancing disk menu program and so here's a list of the main
  34. features:
  35.              * Each selection can be Executed, Run or Launched
  36.              * Shrink feature to squeeze the menu to the top right of your
  37.                Workbench screen
  38.              * Up to 5 separate menu screens all linked as you like
  39.              * Up to 40 separate selections per menu
  40.              * Each selection can carry out up to 4 CLI commands
  41.              * Command Line Parameters can be specified after selection of
  42.                a gadget
  43.              * Full built in gadget-driven menu editor
  44.              * Menus can be optionally created in a text editor/word pro.
  45.              * Each menu can be optionally titled
  46.              * Gadgets can launch programs or batch files, fade to another
  47.                menu or just contain some descriptive text
  48.              * Menus saved as a short ASCII text file, thereby taking up
  49.                very small disk space
  50.              * PAL and NTSC compatible
  51.  
  52.    Also, although Console is a Shareware release, and therefore you are
  53. expected to pay if you use it, unlike some other programs, with this one
  54. you get the full version immediately. Aside from any preference you may
  55. have over styling on your disk menus (and that's not to imply that Console
  56. doesn't have a modern, good-looking and efficient user interface, 'cause
  57. it does), you're getting the best featured disk menu program available and
  58. all for under 30K of disk space! (so c'mon, pay that Shareware fee!).
  59.    OK, enough of this babble, and on with the main stuff...
  60.  
  61.  
  62.                          2. CREATING A MENU
  63.  
  64.    The concept behind a menu's really rather simple; first a title, then
  65. you just list the selections you want to have available - as many as you
  66. like up to 40, then just run Console specifying the name of your menu at
  67. the command line. Menus are just plain old ASCII text files set out in a
  68. particular way so you can use any Word Processor or text editor to create
  69. them (and no, you don't have a lot of typing to do!). *Much* more sensible
  70. however, is to use Console's own built in mouse driven editor, as it takes
  71. away a lot of the hassle involved and saves you a fair bit of typing
  72. too...
  73.    First: the structure of a menu is as follows; each selection that you
  74. want requires 3 lines describing it:-
  75.  
  76. Title on the first line (or leave a blank line for no title)
  77. Selection Type
  78. Text to go in the selection box (otherwise known as a gadget)
  79. Pathname (Where to find the program or batch file that you want run when the
  80.           user selects this gadget)
  81. Selection Type
  82. Gadget Text
  83. Pathname
  84. Selection Type
  85. .
  86. .
  87. .
  88. etc.
  89. etc.
  90.  
  91.    So, it just goes Title, Type, Text, Pathname, Type, Text, Pathname,
  92. Type, Text, etc. etc. all on separate lines on after the other. That's the
  93. way you'd type it in a text editor but the inbuilt editor handles all that
  94. for you! A description of these separate fields now follows (applicable to
  95. both methods of creating a menu):
  96.  
  97. TITLE:   
  98.       Only specified once at the beginning of the menu. Can be any
  99.       string of up to 70 characters. A blank line MUST be left instead if
  100.       you don't want one.
  101.  
  102. And then for each selection:-
  103.  
  104. SELECTION/GADGET TYPE:  
  105.          Are you going to use this gadget to just display a text message,
  106.       fade to another menu, or call a program or batch file? Specify: P to
  107.       call a program, B to call a batch file (in which case you DON'T
  108.       include the word Execute in the pathname), T to replace the gadget
  109.       box with shadowed text, or GO followed by the number of the menu you
  110.       want to fade to e.g. GO3, GO1 etc. NOTE: If you wanted to fade to
  111.       say, menu 3 you have to specify at least 3 menus at the command line
  112.       when you run Console, obviously. In addition if the type is P or B,
  113.       you can add a C which will cause a command line options prompt to be
  114.       displayed when the user makes this selection. See "Use of the
  115.       inbuilt menu editor" below, for more description of this.
  116. SELECTION/GADGET TEXT:
  117.          This is the text that the user sees displayed in each gadget on
  118.       the menu and can be any string of up to 33 characters. It is optional
  119.       and if you leave this line blank, the pathname will be used instead.
  120. PATHNAME:
  121.          This is simply the pathname of the program, exactly as you would
  122.       type in the program's or batch file's name at the CLI normally.
  123.       There are a couple of exceptions however. If the selection is a
  124.       batch file that would normally be `Execute'd at the CLI and you have
  125.       specified a B for the selection TYPE then you can leave out the word
  126.       `Execute ' (as Console will add it for you) and just specify the
  127.       pathname.
  128.          Secondly there is the case of a selection calling up multiple
  129.       programs/batch files. All this means is that when the user makes a
  130.       selection, instead of just running one program or executing one
  131.       batch file, Console can run or execute up to 4 of them, one after
  132.       the other. In this case you would specify the (up to 4) pathnames
  133.       one after the other on the same line, using the \ character as a
  134.       separator e.g pathname1\pathname2\pathname3\pathname4 . Remember,
  135.       that if you have specified a B for the selection TYPE then EACH
  136.       pathname will be `Execute'd, not just the first.
  137.  
  138.       
  139.             ······  Use of the inbuilt menu editor  ······
  140.  
  141.    Run Console from the CLI *without* specifying any command line options
  142. and you will be taken to the menu editor, ready to edit a new menu.
  143. Existing menus can be edited just as easily; simply select the Edit
  144. gadget at the top of the screen when Console has a menu loaded normally
  145. (See section 3 for more info.).
  146.  
  147.    As you will see, all Control Console activities take place on their own
  148. custom screen, which slides up from the bottom of the display to just the
  149. right height. In this case, you wish to edit a new menu. The display shows
  150. two black boxes labelled "Gadget Text:" and "Pathname:". These are where
  151. you type in the respective text. Following that are a number of gadgets,
  152. labelled "CLI", "<<", ">>", "Save" and "Exit". Above these are the words
  153. "PRG" and "Gadget 1". A quick explanation of these follows:
  154.  
  155. The black boxes:-- These are used to enter the Gadget Text and the
  156.                    Pathname for your gadgets. Activate by clicking the
  157.                    mouse pointer within one of them, then type your text
  158.                    and press <Return> or click the mouse pointer anywhere
  159.                    outside the boxes. A "*" cursor will be shown if either
  160.                    is activated.
  161.  
  162. "CLI" Gadget:-- This acts like a toggle switch (on/off). If it is pressed
  163.                 in it means when the user makes this particular selection
  164.                 a prompt will appear displaying the pathname of the
  165.                 selection and allowing him/her to add command line options
  166.                 to the pathname, if they so wish. In the case of a
  167.                 selection calling up multiple programs or batch files,
  168.                 only the first of the pathnames will be allowed to have
  169.                 command line options added to it.
  170.  
  171. "<<" & ">>":-- These two gadgets allow you to move backwards and forwards
  172.                through your list of selections; only one selection being
  173.                displayed in the editor at a time. You will see a
  174.                corresponding update in the black string gadgets, the CLI
  175.                gadget, the TYPE gadget and the Gadget number. If you move
  176.                backwards from gadget 1 you will be able to edit the Title
  177.                in the "Gadget Text" field and notice that this will be the
  178.                *only* thing you can edit for the Title, obviously.
  179.                NOTE:- To be able to move forwards to edit your next
  180.                selection, the current selection's Pathname field must *not*
  181.                be blank if the TYPE is set to PRG or BAT. This is to avoid
  182.                a user making a selection and that selection not doing
  183.                anything at all. GO<number> and TXT types CAN be completely
  184.                blank however.
  185.  
  186. "Save":-- Press this gadget to Save your menu, and you will be asked to
  187.           enter a filename to save as in the Gadget Text field. If you have
  188.           made textual adjustments to either Gadget Text or Pathname and
  189.           select "Exit" you will be automatically prompted so as not to
  190.           lose your edited menu.
  191.  
  192. "Exit":-- Terminate the editor. If editing a new menu you will be returned
  193.           to the CLI otherwise to the menu you have been editing.
  194.  
  195. Type Gadget:-- Initially marked PRG. This performs the same function as
  196.                you entering P, B, T or GO<number> if you were using a text
  197.                editor to edit your menu, i.e. it changes the TYPE of
  198.                selection. Clicking on this [boxless] gadget cycles through
  199.                PRG (Program), BAT (Batch file), TXT (Just Text) and
  200.                GO<number>. If the type is GO it will initially be followed
  201.                by a 1. Clicking on this number cycles through the numbers
  202.                1-5, allowing you to choose which other menu to fade to
  203.                when the user makes this selection.
  204.  
  205. Current Gadget Number:-- This just displays which particular selection is
  206.                          shown in the editor right now and will be a
  207.                          number 1-40, or it will show "Title" if you're
  208.                          editing the title (backwards from gadget 1).
  209.  
  210.    OK, that's all there is to the editing a menu (a lot? Its much easier
  211. and quicker in use!). Set up each selection, Save your menu then exit.
  212. Easy. A finished menu should look something like this on disk (of course
  213. if you always use the inbuilt editor you need never know...):
  214.  
  215. This is my Title
  216. P
  217. This is my first selection
  218. DF0:c/PowerPacker
  219. B
  220. The 2nd selection - a batch file
  221. ram:T/mybatchfile
  222. PC
  223. 3rd selection with CLI options!
  224. HD0:DPaint4
  225. GO4
  226. Switch to menu four.
  227.  
  228. T
  229. Some amazing shadowed text....
  230.  
  231. BC
  232. Multiple with CLI options!!
  233. ram:mybatchfile\df1:c/My2ndBatch\"df0:My Third Batch File"
  234.  
  235.  
  236.    Final Note: If your editing in a text ed./word pro. don't leave more
  237. than 1 blank line at the end of the menu!
  238.  
  239.  
  240.                    3. GENERAL USE OF THE PROGRAM
  241.  
  242.    Console can be run with several CLI options. The syntax is:
  243.  
  244. Console ?
  245. OR
  246. Console [i] [b] [|Data File] ... [|Data File]
  247.  
  248. Where:
  249.  
  250. ?           Gives a quick run down on CLI options etc.
  251. i           Displays all menus etc. on an Interlace screen (allows you to
  252.             fit on more than 20 selections as a med. res screen would).
  253. b           Each time a selection is made, Console flicks its screen behind
  254.             the Workbench screen so you can see what's going on, and doesn't
  255.             reappear until the selection has run it's course (unless you
  256.             selected Run mode, see below).
  257. |Data File  Is the pathname of a menu file on disk. The | character is
  258.             used as a separator and each Data File *must* have a |
  259.             character before it. This is positioned on ALL countries
  260.             keyboards above the backslash \ character on the key to the
  261.             left of the <BackSpace> key (and was used for that reason).
  262.             NO arbitrary spaces must be left between specified Data Files,
  263.             pathnames which include spaces must be surrounded by quotation
  264.             marks: " (as in normal AmigaDOS use). Up to 5 data files can
  265.             be specified.
  266.  
  267.    A typical CLI calling of Console would look like (ignore the >1 )
  268.  
  269. 1> Console ib|Menu1|df1:Menu2|"ram:Menu Three"|"df1:My Menus/Menu4"
  270.  
  271.    NOTE:- When using GO<number> it refers to that data file specified at
  272. the command line. E.G. GO2 would switch to the 2nd data file you entered
  273. as a command line option.
  274.  
  275. REQUIRED FILES: Console always requires mathieeedoubbas.library in the
  276. LIBS: directory (get it from LIBS on your Workbench disk), and the Execute
  277. and Run commands in the C: directory (taken from the same place on the
  278. Workbench disk). If you have any selections which call multiple programs or
  279. batch files then you require ram-handler in your L: directory (from the L
  280. dir on the Workbench disk).
  281.  
  282.  
  283.                     ······  Loading Errors  ······
  284.  
  285. Menu <data file> truncated: more than 40 selections specified!
  286.  
  287.    You know the limits, don't try to go beyond them!
  288.  
  289. Menu <data file> truncated: too large for specified screen size!
  290.  
  291.    If you want more than about 20 selections you're going to have to
  292. specify the i switch at the CLI when running Console, to get an interlace
  293. screen to fit them all on!
  294.  
  295. Gadget mode not found in line <n> of <data file>
  296.  
  297.    You've probably forgotten to include a line for the gadget mode just
  298. before line <n> in the menu file, left a blank line or typed something
  299. other than P, B, T, or GO<number>.
  300.  
  301. Page value out of range in line <n> of <data file>
  302.  
  303.    Oops! You've used a GO<number> in the named menu file but haven't
  304. specified that many menus at the command line. E.G. You can't switch to
  305. menu 4 if you haven't specified at least 4 menus!
  306.  
  307. Path should be specified in line <n> of <data file>
  308.  
  309.    You've obviously set the type to P or B and left a blank line in the
  310. pathname line of this selection.
  311.  
  312.  
  313.    Once Console's loaded you will see your menu displayed as gadgets going
  314. from left to right across and down the screen. Clicking in a box will
  315. carry out the CLI command that you specified when creating the menu.
  316. At the top will be the title followed by four large gadgets which are
  317. always there. These are the Mode, Shrink, Edit and Quit gadgets. The Mode
  318. gadget will show one of Execute, Run or Launch and refers to the way in
  319. which selections are handled by Console. Clicking on the gadget will cycle
  320. through these three modes, but Console always starts up with Execute mode
  321. on.
  322.    Execute will carry out a selection and not allow you to select anything
  323. else until that selection's finished with, Run will start up the selection
  324. then allow you to make another selection straight away and Launch will
  325. start up the selection then quit Console.
  326.    The Shrink gadget will shrink Console temporarily out of the way to a
  327. small window at the top right of the Workbench screen, reversed by making
  328. sure that the window is active then pressing the right mouse button.
  329.    The Edit gadget allows you to edit the currently displayed menu and
  330. finally the Quit gadget terminates Console.
  331.  
  332.  
  333.         4. CREDITS, GREETINGS, PLEAS FOR MONEY, OTHER THINGS.
  334.  
  335.    Credits:
  336.            Entire concept thought up by me about 20 months ago (when
  337. there was only 1 (!) other menu program out and about). Programming and
  338. docs also all by myself.
  339.  
  340.    Greetings:
  341.              In true Amiga demo style here's who I'd like to say "Hi"
  342. to:-         Lee Jones, Simon Plumbe, Simon Melaniphy, Diablo of Budbrain,
  343. Matthew Harrison-Harvey, Patrick Harrison-Harvey.
  344.  
  345.    Pleas for money:
  346.              Pleeeeeeeeeeeeeeeease send me some money! 18 months!
  347. Literally hundreds of hours! Aching fingers! Throbbing eyeballs! That's
  348. what went into this program and if you've got any conscience at all,
  349. you'll consider a small Shareware fee of £10/$25. A programmer expects
  350. something for his work you know! More or less is also appreciated (more
  351. especially!). Those sending at least that amount can request a disk
  352. containing any or all of:- the source code, any other programs I have
  353. written(at least one), some IBM PC programs and their source in Turbo
  354. Pascal that I produced (no I'm not a traitor, PCs belong on the nearest
  355. scrap heap along with STs). OK? So please bother to send that cash in
  356. now!!!
  357.  
  358.    Other things:
  359.                 Known Limitations of the program: As stated in the
  360. disclaimer, Console's been tested to specified limits. In this case that
  361. means I loaded Console in interlace mode with 5 menus each of which had 40
  362. selections and most of those called 4 programs or batch files. At this
  363. unlikely extreme the inbuilt editor couldn't be used because I limited the
  364. amount of memory available to the program deliberately, but this is hardly
  365. a drawback. It did work when I did the same again but loaded only 3 menus
  366. so you could still use the editor then. Console's limits are there
  367. individually for convenience and weren't actually supposed to be used all
  368. at once, although as I've mentioned it worked fine. All other parts of the
  369. program that I could think of testing checked out as planned.
  370.  
  371.                 I'm Alex Kerr, I've had enough of programming 'cause the
  372. truth is I'm a graphic artist/3D graphic artist, I'm an 18 year old student
  373. who needs his Shareware fees and my address is:-
  374.  
  375.    Pine Lodge, Mesh Pond, Wick Lane, Downton, Wiltshire. SP5 3NQ. ENGLAND.
  376.  
  377.  
  378.                       ««  Live Long and Prosper  »»
  379.