QASQADE						     -*-indented-text-*-
=======

Introduction
------------

Qascade is a pop-up menu program, offering similar facilities to those
customarily available on Unix/X Window (RMB popups) and, more
recently, from the 'Start' button/menu in Windows 95 and NT.

Qascade allows the user to define cascaded menus to any depth, limited
only by memory, screen real estate and, less plausibly, common
sense. The menus displayed may then invoke any of the following
actions:

	o Executable programs, with optional parameters

	o Executable Things, with optional parameters

	o For Minerva users, Multibasic sessions, with an optional
	  BASIC program that may be run, and with user defined device
	  / files.

	o For SMSQ?? users, SBASIC sessions, with an optional BASIC
	  program that may be run, and with user defined device /
	  files.

	o Action any existing HOT KEYS.

        o Execute non-executable files where FileInfo2 is installed
  	  and a FI2 action is defined for the file extension.

In extremis, a single Qascade button might replace or augment a myriad
of other buttons.

Requirements
------------

	o Environment variables (env_bin)
	o Pointer Environment (ptr_gen, wman or SMSQ/E)
 	o Minerva or SMSQ?? to invoke uncompiled BASIC programs
	o Thing system to invoke executable Things
	o Some other QJump software (qpac2 maybe) if you want the
	  button to appear in the button frame; otherwise is appears
	  at the pointer and can be moved following a LMB click.
	  ** YOU DO NOT NEED QPAC2 TO USE qascade **.
	o FileInfo2 to use the FI2 method.

env_bin is available from the customary freeware sources (internet,
BBS, 'PD' libraries). It is available with full documentation from,
inter alia, http://www.daria.co.uk. Problems with env_bin
should be addressed to the env_bin maintainers, not to the qascade
author.

FileInfo2 is available from http://www.imaginet.fr/~godefroy/english
and other well known freeware sources. Thanks to Thierry for a well
documented interface, pity some allegedly 'commercial' software can't
do the same.

qascade has been tested with JS and Minerva ROMS, versions of the PE
ranging from 1.35 (ancient) to 1.68 (recent), and, courtesty of some
beta testers, fairly recent versions of SMSQ/E on QPC and Atari.

Usage
-----

Define your menus via QASCADE_RC (see below) file and then

       ex qascade
       ert hot_wake('/', 'Qasqade') : rem if you wish

       This will give a button named 'Qasqade', if you'd like your
       button to be called something else, 'Start' for example, then
       give this as a parameter.

       ex qascade;'Start'
       ert hot_wake('/', 'Qasqade') : rem if you wish

       Note 0: The hot_wake commands are examples only. If it doesn't
               work for you, rtfm or call the qpac2 vendor ... not the
               qascade author.

       Note 1: You may wonder why the file name is qascade and the job
               name is qasqade. So do I. Use the source, Luke
	       .... maybe next time it will be different.


Pressing ESC with the pointer in the 'qascade' button will cause it to
re-read the QASCADE_RC file.

On a floppy based system, you could have a QASCADE_RC file on each
disk; just pressing ESC with pointer in the 'qascade' button will
cause it to re-read the rc file on the new disk. As noted below, you
can also redefine the name of the QASCADE_RC file at any time.

Menu Definition
---------------

The menus used by 'Qascade' are defined by a simple text file. This
file is defined by the environment variable QASCADE_RC; for example to
use the definition file 'win1_casqade_rc'.

    setenv "QASCADE_RC=win1_casqade_rc"

The environment variable may be changed _at any time_, and by pressing
ESC with the pointer in the 'qascade' button, the new menu file will
be read.  Note: This is non-standard environment variable usage.

For qascade v1.10 and later, it is possible to supply the RC file on
the command line. In this instance, the QASCADE_RC environment
variable is ignored, pressing ESC will re-read the initially supplied
file, possibly permitting easy execution of multiple copies of
'qascade'.

To supply the QASCADE_RC file on the command line, you _must_ supply a
button title as well as the file name. The file name is delimited by a
'<'. 

     examples:

     ex qascade					
     ex qascade;'Click on me'
     ex qascade;'Start me up <win1_qascade1_rc'
     ex qascade;'Wind me up < win1_qascade2_rc'

Each item in the QASCADE_RC file is defined as:

    Key<TAB>Menu_text<TAB>Action<TAB>parameters

<TAB> represents the TAB character, ASCII 9. Make sure you use a
sensible editor that knows what a TAB is. Not all items require all
parameters.

For the tabularly challenged, a semi-colon, ';' may also be used as a
separator.

The keys define a method by which qascade can do magic for you; the
keys and associated methods are:

EXEC	 - Starts an executable program
ETHG	 - Starts an executable Thing
MBAS	 - Starts an MultiBASIC session
SBAS	 - Starts an SBASIC session
HKEY	 - Invoke a Hotkey
FI2	 - Invoke a non-executable file via FileInfo2 (assuming you
	   have FI2 and defined the action for the file type).
TITLE	 - Defines a new cascade menu Title
MENU	 - Starts a sub-menu section
MEND	 - End a sub-menu section
SEP	 - Draws a separator line (with optional text)
COL	 - Defines the colours for the menus
JUMP	 - Causes qascade to be (possibly) repositioned in button
	   frame after menus have been used. Normally (no JUMP),
	   qascade tries to return to the same position each time.
AUTOKEY	 - Adds keystroke selection to each menu action, as qpac2.
	   The AUTOKEY key must occur before any menu definition. 

The menu file definition does not require either a TITLE or MENU/MEND
directive for the 'main menu'; and is best illustrated by example:

	  # This is an example menu
	  # Comments and blank lines are just fine.

	  # First define our two sub-menus

	  TITLE	     SubMenu1
	  TITLE	     SubMenu2

	  # Add a separator line, with a subtitle
	  SEP	Apps

	  # This option invokes qed without parameters
	  EXEC	Qed	qed

	  # Menu names MUST match a _previous_ TITLE line
	  MENU	 SubMenu1
	  ETHG	 Jobs	Jobs

	  #	 menu option	Thing	Parameters
	  #---------------------------------------
	  ETHG	 Files win3_	Files	\Dwin3_
	  MEND

	  MENU	SubMenu2
	  EXEC	View Fax	qfv	-l
	  # This separator has no subtitle
	  SEP
	  # We can mix TABS and semi-colons (but no spaces to
	  # separate executable/thing and any parameters). 
	  EXEC	Voice Mail;qvm;-v
	  MEND
	  
	  # Now back at the top level menu
	  EXEC	QTPI qtpi
	  # I have wstat as ALT-W
	  #       Menu Option		Hotkey
	  HKEY	   wstat (Alt-W)	W
	  # I also have FI2 set up to run slspv as a PIC viewer, this
	  # is just to test the FI2 method.
	  # key	menu text	File to pass to FI2
	  #------------------------------------------
	  FI2	FI2 test	win3_qlsoft_tiger.pic


From this definition, the main menu invoked from the 'Qascade' button
will look like:

	  +================+
	  | Qascade	ESC| 
	  +================+
	  | SubMenu1 ...   | -----+   
	  | SubMenu2 ...   | --+  |
	  |-Apps-----------|   |  |
	  | Qed		   |   |  |
	  | QTPI	   |   |  |
          | wstat (Alt-W)  |   |  |
	  | FI2 test	   |   |  |
	  +----------------+   |  |
			       |  |	+================+
			       |  +---> | SubMenu1    ESC| 
			       |	+================+
			       |	| Jobs		 |
			       |	| Files		 |
			       |	+----------------+
			       |
			       |	+================+
			       +------> | SubMenu2   ESC |
					+================+
					| View Fax	 |
					|----------------|
					| Voice Mail	 |
					+----------------+

Selecting the 'SubMenu1 ...' or 'SubMenu2 ...' options off the main
menu will invoke the sub-menus as shown. (Note, qascade adds the
ellipsis (...) automatically to indicate that these items lead to
another menu.

Pressing the 'Qed' option invokes the qed program, pressing 'Files'
invokes the Files Thing with the win3_ directory loaded. Pressing
'Voice Mail' invokes the 'qvm' application.

'Qascade' searches the PROG_USE and DATA_USE (in that order) for
excutable files that do not include the full path.

The invocation of BASIC files follows a similar syntax, however device
or file names may follow the name of the required BASIC program,
separated by commas. There should be no white space between the file
name and any file/device names.

For example:

# Minerva MultiBasic in a console window (note no BASIC program)
MBAS	MultiBasic ,con
# Minerva MultiBasic in a sized console window, run prog with CMD$
MBAS	MB Test	     win2_tmp_demo_bas,con_200x100a100x40	This is a test
MBAS	Minny Rules OK!	win2_tmp_mtest_bas,pipet,con_200x100a100x40	So is this

The Menu text defined in the above example is displayed as:

	+-----------------+
	| MultiBasic	  |
	| MB Test	  |
	| Minny Rules OK! |
	+-----------------+

The first example opens a MultiBASIC window with a cursor. 

The second example opens a MultiBASIC window and runs the demo_bas
program, passing CMD$="This is a test". When the program finishes, a
cursor is displayed in the window.

The third example opens a MultiBASIC window and runs the mtest_bas
program, when the program finishes, the MultiBASIC session terminates
as input from 'pipet' (or 'nul') returns 'End of File'. CMD$ is set to
"So is this".

SBASIC (using the SBAS key) works in a similar manner (see below).

Experiment with the supplied files as a basis for your own setup.

A command invoked by 'qascade' may also prompt the user for
parameters; prefix the command name with a question mark. Any default
parameters are presented for editing. For example:

EXEC	View Fax	?qfv	-l

Would present a dialogue box, preset with '-l', asking for parameters
for the qfv program. If you terminate the dialogue box with ESC, then
the command is not run. Use ENTER to terminate the edit (regardless of
whether the parameter has changed) to then invoke the program.

Here are some SBAS(ic) examples, courtesy of Phil Borman.

SBAS	Run backup program	win1_backup_bas
SBAS	Backup which drive	?win1_backup_bas	win1_
ETHG	Run a command	SBASIC	dir win1_:pause -1


Note: The author has no access to SMSQ/E and SBASIC. If you have a
problem, try asking in news://maus.computer.ql.intl --- please don't
call the author. Actually, if you don't understand the Minerva
examples, don't call me either, please. Try reading the Minerva manual
instead -- you might learn something. Then you can explain it to me.

The FI2 method relies on two things, firstly that you've installed
FileInfo2, and secondly, you've configured it correctly. Failure to
observe either of these will mean that the FI2 method fails. Note that
'qascade' is unlikely to be able to put up a FileSelect window if
asked by FI2, as its button is a little small. FI2 problems should be
sent to the FI2 author; or to Roy Wood --- it's his fault that it is
supported here.

Colours
-------

The COLS key defines the colours used by the menus. While the method
used is somewhat obscure, it has the advantages (over config for
example) of being memory efficient and changable 'on the fly', at run
time. So if you don't like the colours, just change the QASCADE_RC
file and press ESC with the pointer in the 'Qascade' button.

The COLS key is followed by a twelve character array defining the
following colour items:

	  array	 QPTR	Description
	  index	 abbrev
	  -------------------------------
	  0	  borc	 (border colour)
	  1	  papr	 (paper colour)
	  2	  ypsac	 (scroll arrow colour)
	  3	  ypsbc	 (border to scroll bar)
	  4	  ypssc	 (scroll bar centre bit)
	  5	  curc	 (current item outline)
	  6	  uback	 (unavailable background (i.e. separators))
	  7	  uink	 (unavailable foreground (i.e. separators))
	  8	  aback	 (available background (i.e. items))
	  9	  aink	 (available foreground (i.e. items))
	  a	  sback	 (selected background (i.e. selected item))
	  b	  sink	 (selected foreground (i.e. selected item))

The colours are defined as:

	  Abbrev  Colour	QDOS code
	  -------------------------------
	  b	  black		0
	  r	  red		2
	  g	  green		4
	  w	  white		6
	  y	  grey		255

Some examples:

#	default colours
#	0123456789ab
COLS	gwrgybwgwbrb

#	Traditional QPAC2 colours
#	0123456789ab
COLS	gbggwwbrbwgb	
	    
Bugs
----

This is a beta release (even v1.xx), it may contain significant
bugs. In particular, the menu file parsing code may not be robust. The
most likely affect of ill defined menus is that 'qascade' will not
run, and a dialogue will be displayed, explaining why.

Please Don't Even Ask About ....
--------------------------------

A number of users have asked about menus that either popup or popdown
or do something after a certain timeout, just like Unix/X or
Windows. Don't expect that in qascade, to do it easily requires a real
operating system and window manager, plus, of course, some decent
documentation.  

So not this week .... or any other time soon.


mclock
------

mclock is a ... er ... simple little clock and free memory
button. Just 

	ex mclock

Actually, it can be a bit less simple than that, because you can
define some programs to be run when you click on the button, using two
environment variables, MCLICK_1 (left button) and MCLICK_2 (right
button). The programs defined must be executable programs and you must
define the full path name, and any parameters, space separated.

       setenv "MCLICK_1=win1_exe_mclock" : REM stupid, incestuous example
       setenv "MCLICK_2=win1_exe_qfax -R -v" : REM marginally useful
       ex mclock

Again, and in a non-standard usage, you may change the above
environment variable 'on the fly'.

License
-------

'qascade' is (c) Jonathan R Hudson (support@daria.co.uk).
So is mclock.

Bugs (and preferably patches) should be reported to the above address
or maus.computer.ql.intl (or FidoNet equivalent).

qascade and mclock may be freely distributed; however the original ZIP
file must be distributed unchanged (which means no file name munging,
no packing with obsolete, illegal zippers).

Please see the files README and Artistic for license information.

v0.00	27/09/97	Initial version
v0.01	28/09/97	Added '?' option, fixed some small bugs
v0.02	29/09/97	Added button title 
v0.03   01/09/97	Fixed some pointer bugs (jh bugs, not TT),
			improved rcfile parsing.
v0.04	01/10/97	Added re-read RC file on ESC
v0.05	02/10/97	Happy Birthday Daria (nice sail wasn't it), oh
			yes, also found time to add some sanity checks
			for incorrect RC files. Wonder if this one
			will run on those funny Atari-SMSQ/E things.
v0.06	02/10/97	Added comments to the source code and tidied
			it up a bit.
v1.00	05/10/97	Gosh, works on those Ataris too. Must be time
			for a full release. This version may be freely
			distributed. The SBAS code is _still_
			untested. Any volunteers ?
v1.01	11/10/97	For Klaus-Peter Greiner, adopts priority 126
			in the button frame (for versions of qpac2
			that don't button_pick priority 1).
v1.02	12/10/97	For Phil Borman, allow text in separators.
			Thanks for testing SBAS, Phil !
v1.03	14/10/97	Added definable colours
v1.04	16/10/97	Added OS checking (for Dilwyn Jones)
v1.05	14/11/97	What, almost a month and no qascade changes! 
			Now cascades to the left if necessary, also
			added JUMP option to reposition in Button
			Frame (for Wolfgang Uhlig).
v1.06	30/11/97	Added HOTKEYS (for Roy Wood, at the Bristol QL
			show) must have taken all of thirty minutes
			from being asked to the new version being
			available :-).
v1.06a  06/12/97	Alas, took a week to get the documentation to
                        match though. (No code changed).
v1.07   06/12/97	Added the FI2 method, for Roy Wood. Is there
                        no limit to this man's imagination ? [Trust the
			manual's not to complex, Roy ?]
v1.08	05/01/98	Changed separators slightly to accomodate
			executable things with spaces in the name.
			(for Stephen Papierowski and his 'Alarm Clock')
v1.09	17/02/98	Menus can grow upwards from the bottom of the
			screen (just like W95) -- for Jochen
			Merz. Didn't know you are such a Windows fan,
			Jochen --- don't worry, I won't tell :-).
v1.10	15/03/98	Must be time for the monthly qascade
			update. How about QASCADE_RC on the command
			line ?
v1.11	02/04/98	Added mclock. Changed the name again, just for fun.
v1.12   14/04/98	Updated mclock to be slighly useful. For Roy
			Wood, who has not only read the fine manual,
			but has explained it to loads of QLtoadies.
			Damn ! missed the collective noun competition.
v1.13	01/05/98	Added AUTOKEY (for Christopher Cave)
	05/01/99	Evidently the manual is confusing, so its
			changed, although I don't know why, as the
			whinger doesn't appear to have read it anyway.
			No code changed.
	13/03/99	Changed the manual slightly, mainly to reflect 
			the usenet changes in the maus hierarchy.
			No code changed.
	07/05/99	Thought about ading some new features ... then 
			tried to read the hotkey manual. Abandoned
			attempt and went to the pub. Note to Mr Tebby
			and chums "no point in writing an operating
			system and window manager if the documentation
			is so gratuituously, unintelligibly, crap that
			no one can write any programs for it". 
                        Corrected some typos since I'd checked out the 
			manual.
