RAT
Mouse Menu Driver
(C) Copyright 1989 Ronnie D. Tanner

RAT is a powerful context sensitive mouse driver which enables the user to
take full advantage of any Microsoft-compatible mouse. With RAT, the user
can make any program easier and faster to use without the need for keyboard
templates or memorizing complex key sequences. Not only that, but with RAT a
user can enhance any program by adding 'new' functions that can be performed
with one 'point and click' of the mouse. Functions that used to require
several key strokes can now be reduced to one press of a button.

Tired of using all those templates? One of the unique features of RAT is the
super easy 'pull down' menu. If you've ever tried using some of the menus
provided with your mouse, you've probably noticed that these menus are pretty
awkward to use, especially if you've ever sat down at a Macintosh or another
computer with a really good GUI (graphical user interface). The main problem
is that everything requires a click of one of the buttons. Therefore, if you
want to get to a sub-menu nested three levels down, you have to press the
button three or four times. You might as well use the keyboard! With a good
GUI, all you have to do is 'point' to the sub-menus and they pop up on the
screen. Then you press the button, or in some cases, just release the button
to activate the desired selection. These are 'pull down' menus and they are
much easier and faster to use.

One of the advantages of the text mode that most programs use on the
IBM-compatibles is the speed at which screen updates can be performed. One
of the disadvantages has always been that you can't implement a GUI in text
mode. Now RAT provides the next best thing. With RAT you can provide nested,
context-sensitive 'pull down' menus that will really enhance any text-based
applications program.

Provided with this demonstration program, are some mouse drivers for a few of
the most popular text-based programs. These menus were written using another
program, MKRAT. MKRAT is a mouse driver compiler that will allow a user to
develop custom mouse drivers for use with RAT. MKRAT uses a powerful set of
instructions that will allow anyone to create sophisticated pop-up mouse
menus quickly and easily.

The following source files are provided:

WP50.MNU - This is a menu for Word Perfect 5.0.

WP42.MNU - This is a menu for Word Perfect 4.2.

SYMPH.MNU - This is a menu for Symphony.

EXTENDED.MNU - This is a popup menu that gives the user access to
the extended IBM character set.

123.MNU - This is a menu for Lotus-123.

BEFORE YOU START

Now for some of the special features you need to know about before using RAT.
RAT is of course a memory-resident program, meaning that in order for it to
execute inside your application programs, it must reserve some of your memory
for itself. The amount of memory required is 64K. You probably won't have any
problems unless you have some other memory-resident programs like SideKick,
SuperKey, or ProKey running also. If you do have problems, one of the
resident programs will have to go or you will have to add additional memory.

Before you can use any of the provided menus, you must first compile the
menu source files (*.MNU) using MKRAT. To compile the desired menu driver
type:
MKRAT
where filename is for instance 123 or WP50, and so on.

MKRAT will then produce an output file with a '.BIN' extension which is
required by RAT.

When you want to use RAT, just type in 'RAT ' where 'menu
filename' is a menu file with the extension '.BIN'. You don't need to type
in the file extension. For example, to use 'WP50.BIN' just type 'RAT WP50'.

All of the menu programs except for 'EXTENDED.MNU' use the EXECUTE
instruction in order to autoexecute the particular application software for
which that menu program is written. If you choose not to use EXECUTE, then
you may remove or comment out that line and re-compile. Then, RAT will load
the driver into memory and then you can run, for instance, Word Perfect as
usual. When you exit Word Perfect, the mouse driver will still be loaded.
If you want to remove the mouse driver, simply type 'EXIT' at the DOS command
prompt and the mouse driver will be removed from memory. However, if you
execute RAT using the EXECUTE command, Word Perfect will be loaded and
executed by RAT. Then, when you exit Word Perfect, the mouse driver is also
exited. The only requirement for using EXECUTE is that the Word Perfect
program WP.EXE must either be in the current directory or it must appear in
the PATH environment variable. REMEMBER, this is true for any program that
uses EXECUTE to start your application program.

IF YOU HAVE TROUBLE, COPY RAT.EXE and (whatever).BIN TO THE SAME DIRECTORY
THAT CONTAINS YOUR APPLICATIONS PROGRAM.

Once you have loaded the mouse driver, use the right button of the mouse to
activate the menus. You must hold down the right button while you are making
selections. To activate sub-menus which are denoted by arrows, simply drag
the cursor over the arrow. To execute a command on the menu, simply press
the left button when the desired selection is highlighted while continuing to
hold down the right button. While the right button is released, some of the
drivers use the left button for special functions.

WP50.MNU left button toggles BLOCK on/off (ALT F4)
SYMPH.MNU,123.MNU left button selects a cell for Editing (F2)

You'll also notice that each level of the menu remembers your last selection
so that it is easy to repeat the last command. This is a 'sticky' cursor.
If you have the compiler, MKRAT, everything about the menus is programmable
like the screen colors and the cursor sensitivity. You may want to adjust
these parameters to fit you particular PC and tastes.

RAT will work with either Hercules monochrome video adapters or CGA
compatible adapters. Also, RAT can work with the older video cards that do
not have dual-port RAM. This type of card is indicated by "snow" that
appears on the screen when you activate the popup menus. The default setting
for RAT is to do direct screen access and if that causes "snow" on your
screen, you can add the following line to your AUTOEXEC.BAT file.

SET SNOW=OFF

This will cause RAT to sync up to the video adapter and eliminate the "snow".
This will result in slightly slower screen access. This command must be
executed BEFORE running RAT.

NOTES ON USING RAT WITH WORD PERFECT 5.0

The mouse driver for Word Perfect 5.0 assumes that you are using the Normal
fonts as selected from the Display Setup menu. If you are using any of the
other fonts such as Italic or Underline, the pop-up menus will give you
strange looking characters using the default colors. This is why the
highlight text color for WP50.MNU is LIGHTGRAY instead of the default color
YELLOW. If you decide you prefer to use YELLOW highlighted text instead, you
need to use the NORMAL font, then you can simply change the text colors used
for the pop-up menus using MKRAT. When using any font other than NORMAL
select your text colors from the following set:

Black Blue Green Cyan Red Magenta Brown Lightgray

Please know this! If you are upset at the situation created by using other
than NORMAL fonts, it is not a restriction caused by RAT! In order for Word
Perfect to use two font sets, one of the bits (intensity) in the screen
attribute byte is redefined to select either the NORMAL or the special font.
RAT can do nothing about it!

NOTES ON USING RAT WITH SYMPHONY

The mouse driver for Symphony provides access to all of the F9 and F10
functions and to some of the nested commands. When you are in the worksheet,
pressing the left button will be the same as pressing F2 where you may edit
the current cells contents. When you are in any of the sub-menus the left
button will server as the ENTER key by selecting the high-lighted selection.
In the main pop-up menu you can use CANCEL to return to the worksheet from
wherever you are in any of the sub-menus.

NOTES ON THE EXTENDED CHARACTER MENU

Included are both the source and the compiled files for a mouse driver that
will allow you to easily take advantage of the IBM extended character set
which is normally so hard to use. Use this program with your favorite text
editor and you can use the mouse for moving the cursor and for accessing the
extended character set.
NOW FOR THE BOTTOM LINE

Once you use RAT enough to get used to it, you will probably come to
appreciate the large amount of work that went into creating this program and
it's companion program MKRAT. The reason for my creating RAT in the first
place was that I was not satisfied with any of the existing commercially
available mouse compilers and drivers. In my humble opinion, the programs
that come with any of the mouses that I have seen are very poor products that
really fail to unleash the full potential of the mouse. From my experiences
using other computer systems that make excellent use of the mouse, I have
tried to create a set of programs that gives users the same advantages that I
came to appreciate on systems like the Macintosh and the line of SUN
workstations. The most challenging aspect of creating RAT and MKRAT was the
need to allow RAT to be used with programs that were not designed to use a
mouse. I believe RAT to be very successful at providing this capability.
Enough said.

You are free (and encouraged) to distribute this demonstration program as
long as:
1. You Charge no Fee.
2. You do not modify any of the files in any way.
3. You provide ALL of the files, including this one.

This program will let you get the feel of RAT and if you find it useful for
your application, you may receive a registered copy for $20.

MKRAT will enable you to modify any of the ready-to-run programs to suit your
taste or easily create your own mouse drivers for any application. MKRAT is
easy to use and it uses plain english programming commands, unlike other menu
programs. Take a look at the source file for the extended character menu,
'EXTENDED.MNU'. That's how easy it is to create your own mouse driver.

Please consider that if you were buying this software commercially, you would
be paying at least twice the price. Also, there will be new mouse menus
created for RAT and those will be made available to registered owners FREE of
charge. Also, if the response to RAT warrants the effort, there will be an
even more powerful version of RAT and MKRAT in the near future.

When ordering, please specify either 3" or 5" diskettes. Make check
payable to:

Ronnie D. Tanner
10509 Woodland Drive
Greenville, TX 75401

Please allow 3-4 weeks for delivery. Also feel free to send any comments or
suggestions to the same address. If you have access to Compuserve, please
direct any comments to me at User ID# 73020,2114.


USING MKRAT and RAT

MKRAT will enable you to create your own custom mouse menus using 'plain
english' programming commands. There are a few simple rules to remember.

1. The menu driver only does anything when the mouse changes state by
either moving or by one of the buttons being pressed or released.

2. Every time the mouse changes state, ALL of the conditionals are
tested and if TRUE, executed IN ORDER. Therefore, if you have more
than one conditional block that is TRUE for a given state, each of
those will be executed in the order that they appear in the source
file.

3. When characters are TYPE'd into the keyboard buffer, they are not
seen by the applications program until all of the executionals have
been tested. In other words, you can't TYPE a keystroke into the
keyboard buffer and then execute the next command based on the
applications program reacting to that key until the next time the
mouse changes state.

In order to keep track of where the application program is, MKRAT allows you
to check for the presence of text anywhere on the screen using X,Y
coordinates. In order to facilitate your locating exactly where some text
appears on the screen, RAT has a built in capability that allows you to point
the mouse cursor to any location on the screen and it will display those X,Y
coordinates. Simply press 'ALT RIGHT SHIFT' when you have RAT loaded, and
then move the mouse cursor to the desired text that appears on the screen and
the coordinates for that text will appear in the upper left-hand corner of the
screen. When you are finished, simply press the left mouse button to de-
activate this feature. You can use EXT.MNU for this purpose in any
application program.

MKRAT User's Guide
September 8, 1989

MKRAT and RAT is a set of software tools for developing and using pop-up menu
drivers for Microsoft compatible mouse hardware. MKRAT is a menu compiler
that allows the user to generate a mouse menu driver for specific applications
using a convenient "macro" language. Once a menu definition file has been
created using any standard text editor, MKRAT is used to compile that ASCII
file into a binary file format for use by the program RAT.

The format for invoking MKRAT is:

MKRAT where 'source' is a text file
containing the user menu program.

'source' can be any filename with the extension .MNU such as MYPROG.MNU

The output file MYPROG.BIN will be created which can then be used in
conjunction with the program RAT.EXE.

To install a resident applications mouse menu, type:

RAT

where 'myprog' is the name of a compiled menu file in the form of:

'myprog'.BIN

To install a different menu program, you may repeat the above procedure and
the previous menu program will be replaced with 'myprog'.

The general format for source is as follows:



REM This is a sample mouse menu source file
REM that gives a simple example for creating
REM you own mouse menu application programs.

text1(10,20);
'';
' Load Quit ';
' Save Dir ';
'';
endtext;

define right_button_pressed;
show(text1);
state=(2);
enddef;

define right_button_released;
hide(text1);
state=(1);
enddef;

define right_cursor (state=(1));
type(RARR);
enddef;

define left_cursor (state=(1));
type(LARR);
enddef;

REM --- Load definition ---

define left_button_pressed (state=(2),x=(2),y=(1));
action commands
.......
enddef;

REM --- Save definition ---

define left_button_pressed (state=(2),x=(2),y=(2));
action commands
.......
enddef;

....
......




The following commands are currently defined:

Definition Commands

DEFINE action (,,..);
action commands;
ENDDEF;

where definition command can be selected as any combination of the following:

MENU=(?)
STATE=(?)
X=(?)
Y=(?)
MATCH(x,y,'string')
MATCH_CURSOR('string')
MATCH_ATTRIBUTE(x,y,background_color)

where DEFINE begins the definition for a set of commands to be
executed when the specified action occurs. The optional parameters
STATE=(?),X=(?),Y=(?) can be used to qualify an event according to
the internal state variable 'STATE' and/or according the to starting
position of the hi-lighted menu item (cursor position) where 'X' is
the horizontal displacement from the left-most column of the pop-
up window and 'Y' is the vertical displacement from the top of the
pop-up window. The top left of the pop-up menu is at location
(0,0). Menu refers to the active menu, which is the last pop-up
text window activated using the 'show(textn)' command. If all of
the specified conditions are true, then the specified action
commands are executed.

'action' may be selected from the following:

right_button_pressed left_button_pressed
right_button_released left_button_released
right_cursor left_cursor
up_cursor down_cursor

'MENU' is an internal variable which is initialized to a value of
'0'. The value of this variable is changed whenever the 'show' or
'hide' command is executed (see below). The value of 'MENU' is set
to the current pop-up menu. A value of '1' indicates that TEXT1
is currently active. A value of '2' indicates that TEXT2 is
active, and so on. A value of '0' indicates that no pop-up menu
is currently active. DEFINE statements may be executed using the
value of 'MENU' as a conditional parameter as shown above. If 'MENU'
is omitted in a DEFINE statement, the value of 'MENU' becomes a
"don't care" and the value of 'MENU' will have no effect on whether
or not the DEFINE statement is executed.

'STATE' is an internal variable which is initialized to a value of
'1'. The value of this variable may be changed using the 'STATE='
command (see below). Then, DEFINE statements may be executed using
the value of 'STATE' as a conditional parameter as shown above. If
'STATE' is omitted in a DEFINE statement, the value of 'STATE' becomes
a "don't care" and the value of 'STATE' will have no effect on
whether or not the DEFINE statement is executed.

x and y are the current horizontal and vertical locations of the
selection cursor, respectively. Define statements may be
executed based on the current value of these variables. If x or y
are omitted, then it becomes a "don't care" and it's respective
value does not effect the execution of the DEFINE statement.

If specified, 'MATCH' will qualify event based the presence of
'string' at location x,y on the video display. If the ASCII
string 'string' is found, then event qualifies as TRUE and the
specified action commands are executed. Otherwise, no action is
taken.

If specified, 'MATCH_CURSOR ' will qualify event based the presence of
'string' at the location which is currently highlighted on the video display.
If the ASCII string 'string' is found, then event qualifies as TRUE and the
specified action commands are executed. Otherwise, no action is
taken.

If specified, 'MATCH_ATTRIBUTE' will qualify event based the background color
at the location x,y on the video display. If the background color matches
the color specified, then event qualifies as TRUE and the specified action
commands are executed. Otherwise, no action is taken.



TEXTn (x,y);
' text 1 ';
' text 2 ';
ENDTEXT;

where 'TEXTn' begins the definition for the text to be contained in
a pop-up menu window for menu # n. The parameters x and y, where x is
the horizontal displacement from the left-most column of the screen and
y is the vertical displacement from the top of the screen defines the
location of the pop-up menu. The maximum menu size is 25 lines of 80
characters (full screen). The maximum number of menus is based on the
number of characters used. The maximum number of characters that can be
used for all menus is 3500.


Action Commands

SHOW(textn);

where 'SHOW' will display the previously defined pop-up menu TEXTn
where n may be 1 thru 99. When a pop-up menu is active, the
selection cursor will automatically be positioned to the
appropriate text word in the text definition according to the
movement of the mouse. The cursor will appear in the form of a
high-lighted block of text. Therefore, each menu selection in the
pop-menu should be a single text word such as 'Quit' or 'Load'.
Each must be separated by at least one space and no text may
appear in the first or last line of the menu or in the first or
last column.


EXECUTE(filename);

where 'filename' is an executable file to be executed at load time.
'filename' must either reside in the current directory or in a directory
specified in the PATH environment variable. Upon exiting 'filename', RAT
will automatically be unloaded from memory. Only 1 EXECUTE instruction
may be specified per menu program.

HIDE(textn);

where 'HIDE' will de-activate the pop-up menu TEXTn where TEXTn has
been activated by a previous SHOW(TEXTn). Also, if 'ALL' is substituted
for 'textn', then all active pop-up menus will be de-activated.

STATE=(num);

where 'STATE=(num)' will set the internal state variable 'STATE' to
the value num. DEFINE statements may then execute based on the
value of 'STATE'. Initially, 'STATE' is set to a value of '1';

TYPE(key)

where 'TYPE' will insert the scancode for the key specified by 'key'.
See Table I for a list of keys which are supported. 'key' may also
be a string of up to 10 alpha-numeric characters enclosed in single
quotes.

example:

TYPE('HELLO');

SPEED(x,y);

where 'SPEED' will set the sensitivity of the mouse x and y motion.
The default values are x = 8, y = 16. The lower the number, the
MORE sensitive or FASTER the cursor motion will be. The range of
values for x and y is 1-99;

REM text

where 'REM' will indicate that this line in the source file is to be
ignored by the compiler. Use this for comment lines.

Some special characters to be aware of when defining the main text for a
menu.

'<' - this character will be translated to the IBM special
character left arrow (ASCII 27).

'>' - this character will be translated to the IBM special
character right arrow (ASCII 26).

'_' - the underscore character will be translated to ASCII 255 and
will be displayed as a space on the screen. This is to allow
menu selections to have more than one word per highlighted
selection. Remember! Normally, spaces indicate the seperation
of highlighted selections.

For example:

'Save File' would be interrpreted as 2 seperate selections.

'Save_File' on the other hand, will be treated as one selection
and both words will be highlighted.


TABLE I - Keys recognized by TYPE


F1 SHFTF1 ALTF1 CTLF1
F2 SHFTF2 ALTF2 CTLF2
F3 SHFTF3 ALTF3 CTLF3
F4 SHFTF4 ALTF4 CTLF4
F5 SHFTF5 ALTF5 CTLF5
F6 SHFTF6 ALTF6 CTLF6
F7 SHFTF7 ALTF7 CTLF7
F8 SHFTF8 ALTF8 CTLF8
F9 SHFTF9 ALTF9 CTLF9
F10 SHFTF10 ALTF10 CTLF10

CTLA ALTA DARR
CTLB ALTB UARR
CTLC ALTC RARR
CTLD ALTD LARR
CTLE ALTE HOME
CTLF ALTF END
CTLG ALTG PGUP
CTLH ALTH PGDN
CTLI ALTI INSERT
CTLJ ALTJ DELETE
CTLK ALTK CR
CTLL ALTL ESC
CTLM ALTM TAB
CTLN ALTN SHFTAB
CTLO ALTO CTLDARR
CTLP ALTP CTLUARR
CTLQ ALTQ CTLRARR
CTLR ALTR CTLLARR
CTLS ALTS CTLEND
CTLT ALTT CTLPGUP
CTLU ALTU CTLPGDN
CTLV ALTV CTLINSERT
CTLW ALTW CTLDELETE
CTLX ALTX ALTINSERT
CTLY ALTY ALTDELETE
CTLZ ALTZ