SECTION SIXTEEN
USING A MACRO PROCESSOR WITH VOCAL-EYES

16.1:  INTRODUCTION

We've avoided any mention of macros thus far in this, your Vocal-Eyes
user's guide.  As a matter of fact, back in SECTION 1 we actively
discouraged you from using macros with Vocal-Eyes-- at least for the time
being.  We did this for the simple reason that we wanted you to see how
complete and easy-to-use Vocal-Eyes' voice features are with no macro
enhancement at all.

Macros are not for the beginner.  If you have not worked with macros
before, it is strongly suggested that you wait until you feel completely
comfortable with Vocal-Eyes before tackling the concept of macros.  If
you try to learn both Vocal-Eyes and your macro processor at the same
time, you're sure to become overwhelmed.  Take it slow.  We went to
great pains to make Vocal-Eyes work as well as it could without macros. 
Of course those of you who feel perfectly at home with macros can
proceed as you wish.  You will find Vocal-Eyes is very hospitable to many
of the well known macro processors including ProKey, Newkey and
Superkey.

Of course no matter how well Vocal-Eyes works with an application
program, you may still desire the power of macros.  Perhaps you'd like to
integrate Vocal-Eyes' hot keys or numerous other voice features into
entire strings of applications program commands.  Do you currently own a
macro processor?  Well, you can use any commercially-available macro
processor with Vocal-Eyes.  Indeed, when using macros with Vocal-Eyes,
there are really only two things you need to remember.  The
MACRO.COM program and the Macro Toggle hot key.

16.2:  THE MACRO.COM PROGRAM

There is a small program file on your Vocal-Eyes master diskette called
MACRO.COM.  You will need to run this program before loading in your
macro processing program files.  If you're using ProKey and the Sounding
Board, for example, your macro processing loading order would be as
follows:

MACRO
PKLOAD
SBLOAD
SB
VE

If you are using a different macro program, substitute it for the PKLOAD
line.  If you are using a synthesizer other than the Sounding Board,
substitute the appropriate driver for the two lines SBLOAD and SB.  Refer
to Appendix F for a complete list of possible synthesizers and their
drivers.

MACRO.COM is a simple program with a single function:  it turns off all
macro activity whenever you use your fast review key-- ALT, CTRL,
SHIFT, or Scroll-Lock-- to enter Review Mode.  This is to prevent any
macros you may have in place from interfering with normal Review Mode
commands.  You wouldn't, to take a single example, want your F1 macro
to interfere with your Review help.

The MACRO.COM program will only block macro playback if you've used
your fast review hot key to enter Review Mode.  Your second Review
Mode hot key, which you will recall was given a default key assignment
of CTRL-ENTER, will not be affected by the MACRO.COM program.  This
is also true if you are using the Sounding Board hot keys.  If you enter
Review Mode with the fast Review entry key, you will not be able to use
the Sounding Board hot keys.  This is not true if you use the standard
Review Mode hot key.

16.3:  THE MACRO TOGGLE

Vocal-Eyes tries very hard not to interfere with your macro playback.  Do
you have a macro that combines a series of program and Vocal-Eyes hot
key commands?  Well, you'll get no complaints from Vocal-Eyes.  Vocal-
Eyes will accept macro generated keystrokes exactly the same as if you'd
typed them in at the keyboard yourself--hot key responses, Review Mode
command prompts and all.

As you can imagine, if Vocal-Eyes is to accept your macro-generated
keystrokes the same as if you'd typed them in yourself, this is going to
lead to a lot of unnecessary and unwanted chatter at times--especially
when your macro slips into Review Mode, where almost every command
includes at least one voice prompt.  Fortunately, there is an easy way to
inform Vocal-Eyes when to stop and start voicing by means of the macro
toggle hot key.

The macro toggle hot key is option sixty-one on your Hot Keys submenu. 
Go ahead and assign an appropriate key to this function.  It's not one you
will use often, so something in a quiet, out-of-the-way corner of your
keyboard should suffice.  

Use the macro toggle hot key whenever you want to create a macro in
which too much voice response will get in the way.  Place it once at the
beginning of your macro to turn all voice response off, then again at the
end to turn voice response back on again.

Say, for example, that you have assigned the ALT-F12 key as your macro
toggle hot key.  You want to create a CTRL-0 macro that will make
Window zero the active window.  Below are two examples of the steps
required to perform this function.

Example 1:

1) Press your macro program's begin definition hot key.  (If you're using
     ProKey, this would be ALT-=)
2) Press CTRL-0.  This is the key you wish the macro assigned to.
3) Press ALT-F12.  This will toggle Vocal-Eyes' macro voice off.
4) Press CTRL-ENTER.  This will enter Review Mode.
5) Press F3.  This will cause Vocal-Eyes to prompt for the window to
     make active.
6) Press zero.  This is the window number you want active.
7) Press ESCAPE.  This will exit Review Mode.
8) Press ALT-F12.  This will toggle Vocal-Eyes' macro voice back on.
9) Press your macro program's end definition hot key.  (If you're using
     ProKey, this would be ALT--)

Example 2:

1) Press your macro program's begin definition hot key.  
2) Press CTRL-0.  This is the key you wish the macro assigned to.
3) Press ALT-F12.  This will toggle Vocal-Eyes' macro voice off.
4) Press your Select Window Hot Key.  This defaults to being undefined.
     Therefore, if you have not already assigned this feature a keystroke,
     you will need to stop your macro, define the key, and begin the
     macro over again. 
5) Press zero.  This is the window number you want active.
6) Press ALT-F12.  This will toggle Vocal-Eyes' macro voice back on.
7) Press your macro program's end definition hot key.  

Notice what we did.  In both examples, we started the macro with a press
of the Macro Toggle hot key.  This is so Vocal-Eyes will not voice all the
normal verbiage it would if we were to execute each keystroke directly
from the keyboard.  We then issued the commands necessary to make
window zero active.  Finally right before we ended the macro, we once
again pressed the Macro Toggle hot key.  This is so Vocal-Eyes' voice
would return to normal operation.

Had we wanted our macro not only to make Window zero the active
window, but also to voice it for us, we could have pressed F9
immediately after the zero which selected our window in the first example
or pressed the hot key to read window zero in either example.  The macro
toggle would not have interfered with the voicing of the window, or any
other read hot key we might have placed within our macro.  The macro
toggle hot key is intelligent:  it knows which voice features we are likely
to want suppressed and which we are not.

An easy way to remember what will be voiced and what will not is as
follows.  If you press a key and its main function is to read something,
Vocal-Eyes will read it.  The read window hot key or read sentence or
light bar are examples.  If you enter a command in which its main function
is not to speak something, Vocal-Eyes will not speak anything.  Examples
of this would be the select window hot key.  Even pressing the arrow
keys in Review mode will not speak if the macro voice toggle is off.

Try creating either of these macros and leave off the two Macro Toggle
hot keys.  Then execute the macro.  We are sure you will appreciate the
ability to shut off unnecessary speech.

16.4:  A FEW THINGS TO REMEMBER

Here are a few things you should keep in mind when using a macro
processor with Vocal-Eyes.

Whenever you wish to enter Review Mode from within a macro, you
MUST enter using the hot key, not the fast review key such as the ALT
key.  Remember if you enter using the ALT key, ProKey is blocked out
completely.  It would not be able to tell that you had gone into Review
mode at all.  This, of course, would cause your macro not to function
correctly.  Therefore, always use the Review Mode hot key.  Also, when
you exit Review, use either the ESCAPE key or the Review Mode hot key
again.  If you wish to exit and route the cursor, use the ALT-X or ALT-
ESCAPE keys.  In any case, do not exit Review by pressing the fast
review key.

WARNING!  Be careful when working inside the Voice Control Panel. 
Avoid pressing a key with a macro assigned to it.  You may inadvertently
"pour" your macro keystrokes into a submenu, reassigning hot keys all
the way down.  Be sure, when working with the Voice Control Panel, to
either use your macro bypass key or actually go in and suspend macro
playback for the duration.

In SECTION 9, in our discussion of the Review Mode "F" find command,
we mentioned that you could enter control or extended ASCII characters
in the search string by holding down the ALT key and then using your
numeric key pad.  Macro processors will most likely have to take this one
step further, however, and hold down both the ALT and the LEFT SHIFT
keys to accomplish this task.  This is because of your macro program. 
Refer to your macro program documentation if you have any problems.

Also in SECTION 9 we demonstrated how you could use the grave accent
(`) key as a bypass to next key hot key when working within the Voice
Control Panel, in Review Mode, or when attempting to enter a question
mark into the search string.  If your macro processor also uses this key as
a bypass key, you will need to press it twice, first to bypass your macro
processor and then again to invoke the Vocal-Eyes bypass function.

If you wish to look at what your macro program is doing, feel free to
enter Review mode using the ALT key.  For example, in ProKey you can
pop up its menu by pressing ALT-/.  However, it does not speak
automatically.  If you wish to read the options, simply enter Review mode
and read to your heart's content.  Then simply exit Review mode.  ProKey
will not even realize you entered Review.  Notice if you pop up ProKey for
example, you will not be able to use Vocal-Eyes' hot keys including the
Review mode hot key.  This is why you will have to enter Review by
pressing the fast review key.  Then your hot keys will work as expected.

Remember, if you toggle the Macro Toggle off within a macro, you should
toggle it back on before you exit the macro.  If you do not, Vocal-Eyes
will still think a macro is playing back.  This will cause many things not to
be spoken.  If this is the case, simply press the macro toggle hot key from
the keyboard.  No matter what state the toggle is in, pressing the macro
toggle hot key directly from the keyboard will ALWAYS turn it on.  This
means if, while you are creating your macro, you press the macro toggle
hot key, Vocal-Eyes will always turn it on.  Only while the macro is
playing back will Vocal-Eyes toggle it off and on.  This is why Vocal-Eyes
still voices normally while you are creating the macro but silences much
of the speech when it is played back.  Again, the best of both worlds.  It
speaks everything while creating the macro and only what you want
when you play it back!

Also, if you request a function from within a macro which requires Vocal-
Eyes to load information from the overlay file (VE.OVL),  you need to
make sure DOS will be available.  Normally from within applications
programs, DOS will always be available.  If you feel this will be a problem
however, your only option is to load the overlay file into extended
memory.  Once loaded in this type of memory, the overlay file will always
be available whether DOS is busy or not.

Remember the discussion we had about how the Voice Control Panel
waits until DOS is not busy before popping up?  Well, this could cause a
problem if a macro were playing back.  If the Voice Control Panel does
not pop up immediately when it is requested, the next keys in the macro
could play back outside of the menus.  This could cause all sorts of
problems.  Because Vocal-Eyes knows that the Voice Control Panel was
requested from a macro (since the Macro Toggle is off) it pops up the
menus immediately.  This is all well and good unless DOS is busy.  What
if it is busy and you request Vocal-Eyes to load a .SET file from disk? 
Well, you will get the error message indicating DOS is busy and the
function will be aborted.  Therefore, unless you are absolutely sure DOS
will never be busy, you should only load and save to the RAM locations. 
These locations will always be available even if DOS is busy.

Don't forget, if you pop up the menus from within a macro, you could be
starting from any of the menu's choices.  Therefore, if you wish to move
around the menus, you should always jump to the requested option
directly by pressing its number and pressing ENTER.  This way, regardless
of where you currently are, you will end up where you want to be.  Also,
if you want to set a toggle to a known state, you must start by pressing
the DELETE key and then the SPACE BAR or BACKSPACE key to get the
option where you want it.  If you did not start by pressing the DELETE
key, you would not know what option is currently selected and thereby
not know how many times to press the SPACE BAR or BACKSPACE key.

16.5:  AN EXAMPLE

Below is a sample macro that will help give you some idea of how
effectively you can combine program commands and Vocal-Eyes voice
features using macros.  We've been using WordPerfect for many of our
examples up till now, so we'll use it here, too.  Keep in mind, however,
that since by now you have undoubtedly changed the key assignments of
many of your hot keys, we cannot hope to make this macro exactly the
way you would create it.  

16.5.1:  BACKING UP YOUR WORK

From time to time you will want to back up your WordPerfect text using
the F10 "Document to be saved" command.  If you've used this
command you know that if the file already exists, WordPerfect will verify
that you want to overwrite the file before proceeding.  The process thus
entails three keystrokes:  F10, ENTER and Y to verify.  You could create a
macro, ALT-B, for example, to do it all in one keystroke, but why not add
a little voice prompting while you're at it?  

1) Press your macro program's begin definition hot key.  (If you're using
     ProKey, this would be ALT-=)
2) Press ALT-B.  This is the key you wish the macro assigned to.
3) Press the Macro Toggle hot key.  This will toggle Vocal-Eyes' macro
     voice off.
4) Press F10.  This is WordPerfect's Save key.
5) Press ENTER.  This will accept the default file name.
6) Press Y.  This will verify you wish to replace the existing file on disk.
7) Press the Review Mode hot key.  Remember, this must be the hot key
     and not the fast Review key.
8) Press C.  This will enter the direct channel feature to your synthesizer.
9) Type "READY."  This will send the characters R, E, A, D and Y to your
     synthesizer causing the word "ready" to be spoken.
10) Press ENTER.  This will cancel the direct channel feature.
11) Press ESCAPE.  This will exit Review Mode.
12) Press the Macro Toggle hot key.  This will toggle Vocal-Eyes' macro
     voice back on.
13) Press your macro program's end definition hot key.  (If you're using
     ProKey, this would be ALT--)

Now, not only will ALT-B automatically back up your work (assuming, of
course, that you have saved the file at least once previously to give it a
name), but it will also say "READY" when disk activity has been
completed and you're ready to go on.
