home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
The World of Computer Software
/
World_Of_Computer_Software-02-385-Vol-1of3.iso
/
s
/
saveloa2.zip
/
GETKEY.DOC
next >
Wrap
Text File
|
1992-12-19
|
19KB
|
393 lines
GetKey ver 2.5a
(C) 1991/92, Bill Dykstra
-------------------------
-------------------------------------------------------------------------------
Notice: This program was previously called SELECT. It has been renamed, as
new versions of DOS now have a program called SELECT, and I did not want people
to accidentally run the DOS SELECT when they were trying to run this program!
(Thanks Pete for pointing that out to me!)
-------------------------------------------------------------------------------
GetKey is a small program designed to help enhance your batch files. The
program will wait for a user to press a key, and will then pass an errorlevel
to DOS. You may then use this errorlevel to find out which key was pressed, and
act accordingly.
Usage:
GETKEY "Prompt",Letters /NC /NE /NH /C(fg,bg) /L(line,col) /ANY...
.../TIMEOUT=x /DEFAULT=x /EU /EL /ASCII /BEEP...
.../BOX(line,col,h,w,fg,bg,border)
Parameters may be entered in any order, BUT PLEASE NOTE that you may
NOT leave a space between any parts of a single parameter (with the
exception of the prompt parameter). In other words, you cannot
separate /L(line, col) with a space between the comma and the col
value. The correct usage would be /L(line,col)... no spaces.
The same holds for all parameters.. NO spaces. You MAY put spaces
between the different parameters, and you may include spaces in your
prompt message.
If you notice strange things appearing where your prompt should be,
you may have placed a space somewhere where you should not have.
"Prompt" is any text you wish to have displayed. For example, if you
wanted your batch file to wait for a selection to be made, you might
have the text: "Make a Choice: "
Letters: any letters (keys) that are valid. Ie. If you wanted someone
to choose from three choices, (1, 2 and 3) then the letters
would be: ,123
Or to choose from A, B, C, or D you would have:
,AaBbCcDd or if you specify /NC, which means that
the case of the text is not important, then you would
only need: ,abcd
This list of letters is also referred to as a "keylist".
If you do NOT include a keylist, the program will display any
prompt (and boxes) that you specify, and will then exit.
/NC simply tells the program not to be case sensitive. In other words,
it doesn't matter if the user presses 'A' or 'a'.
If you do NOT specify the /NC option, then 'A' and 'a' will be
two different keys!
(/NC = No Case Check)
/NH this option will disable 'hotkeys'. When hotkeys is on, which is
the default, then the user simply needs to press a valid key, and
the program will continue. When the /NH option is specified, the
user must press ENTER before the program will resume. If the user
types several letters at the prompt before pressing ENTER, only
the first letter will be recognized. All others will be ignored.
eg: if the user types HELLO only the H will be recognized.
(/NH = No Hotkey)
/C(fg,bg): If this option is specified, the prompt (if any) will
be displayed in the color specified, where fg is the
forground color and bg is the background color.
Valid ranges are: fg: 0-15 (add 16 for blinking)
bg: 0-9
/L(line,col): This allows you to specify where on the screen the
prompt (if any) is to be displayed.
Line: 1-24, column: 1-80. (depending on screen mode!)
/NE This is the "No Echo" option. If this option is
specified, then the letter chosen by the user will
NOT be displayed. By default the letter chosen is
displayed on the screen. (/NE = No Echo)
/EU This option will cause the letter that you select to
be displayed in UPPER CASE. (/EU = Echo Upper)
/EL This option will cause the letter that you select to
be displayed in LOWER CASE. (/EL = Echo Lower)
/TIMEOUT=x This is the timeout option. You may specify /T=x
if you prefer. This option will tell the program to
time out after x number of seconds if no input is
received from the keyboard. NOTE that if you do NOT
specify a default key (see /DEFAULT=x later in the
documentation) then NO action will be taken when the
time limit has expired...ie, it will continue waiting!
/ANY This option allows you to wait for ANY key to be
pressed, rather than waiting for a specific key.
The character of the key you press will NOT be
displayed when it is pressed.
Note that the possible selections you give in the
LETTERS section (following the comma) will be ignored.
** NOTE: If the ESC key is pressed the program will exit
** with an errorlevel of 10. If any other key is pressed,
** the program will exit with no errorlevel.(0)
/ASCII This options will COMPLETELY change the ERRORLEVEL
system. Normally, when an option is selected, the
errorlevel returned is based on its position in the
list of available keys (the keylist). For example, if
the third letter in the keylist was chosen, then
errorlevel 3 would be returned. If the /ASCII option
(/ASC for short) is used, THE ASCII VALUE OF THE
KEY PRESSED will be returned as the errorlevel!
Eg: GETKEY "Choose Y or N: ",yn /ASCII
If y is pressed, errorlevel 121 is returned.
Some similar programs that wait for keypresses work
entirely on this method, and you may find it useful.
PLEASE NOTE THESE EXCEPTIONS:
- When the /ANY option is used AND the /ASCII option
is used, the program will return the ASCII value
of the key pressed. It will NOT return an
ERRORLEVEL 10 when the ESC key is pressed, as it
normally would. (Instead, ESC would return
ERRORLEVEL 27!)
- When the /NC (ignore case) option is used, the
ASCII value returned will be based on how the
character is displayed. By default, when the
/NC option is used, all letters are converted to
UPPER CASE. Thus, the ASCII value of a letter
pressed would be the ASCII value of the UPPER CASE
of that letter. (ie, if you press 'a', the value of
'A' will be returned). If you have the /EL option
in use (echo lower case), then the value of the
letter in LOWER CASE will be returned.
/BEEP When you specify the /BEEP option, the computer will
sound a beep whenever an invalid key is pressed.
/DEFAULT=x This will allow you to use a default key. If ENTER is
pressed, this default key will be used. For example
if you have two choices, 1 and 2, and choice 2 is
almost always chosen, you could make this the default.
By pressing ENTER, choice 2 would be selected!
/BOX(line,col,h,w,fg,bg,border)
This feature was added to GetKey when version 2.5a was
created. This will draw a box on the screen, with the
box's upper left corner at the line and column numbers
specified. There height will be 'h' lines, and the
width will be 'w' columns. The box will be in colour
FG on BG, with a border style of 'border', which can be
from 0 - 8. Be sure you leave NO spaces anywhere when
passing the box's parameters. Separate each number
with a comma only.. NO spaces! You may have up
to five (5) boxes specified on the command line. If
you want to draw only a box, without waiting for a key,
just specify the /BOX parameter, without providing a
keylist. If no keylist is found, the box will be drawn
and the program will exit.
The line and column parameters must be in the 1-25 and
1-80 range respectively. The FG (foreground) colour
must be from 0-15, and the BG (background) colour must
be from 0-7. The border must be from 0-8. If you use
values out of these ranges, odds are the box simply
will not be displayed.
Border Styles:
0 = no border.
1 = single line all around.
2 = double line all around.
3 = double line on top & bottom, single on sides
4 = single line on top & bottom, double on sides
5 = box made with the ░ char
6 = box made with the ▒ char
7 = box made with the ▓ char
8 = box made with the █ char
Special Keys:
Sometimes it is handy to be able to use the Spacebar or ESC
key as an option, rather than for their normal use. If you want to use
one of these as an option, the following characters may be placed in
your keylist.
~ :Use the spacebar as an option.
^ :Use the ESCape key as an option.
************************** ERRORLEVELS
When the program terminates, an errorlevel is passed to the operating system.
This errorlevel can be used in your batch files to determine what will happen
next.
The best way to show how this works is with an example. Please note that you
MUST start at the highest errorlevel and count BACKWARDS to 1!
The first letter in your list of selections will have a value of errorlevel 1.
The second of 2, and so on...
SAMPLE BATCH FILE:
@ECHO OFF
:TOP
CLS
ECHO ** Menu **
ECHO A. Run WordPerfect
ECHO B. Run MS Works
ECHO C. Run Pacman
ECHO X. Exit to DOS
GETKEY "Please make your choice: ",abcx /C(14,0) /NC /DEFAULT=b /t=120
if errorlevel 4 goto exit
if errorlevel 3 goto pacman
if errorlevel 2 goto works
if errorlevel 1 goto wp
goto top
:wp
CD C:\WP51
WP
goto top
:pacman
CD C:\PACMAN
PACMAN
goto top
:works
CD C:\WORKS
WORKS
goto top
:exit
=========================END OF FILE
In the above example, you will notice four GOTO commands, followed by
the name (or LABEL) of where they will branch. These labels can be
found furthur on in the batch file. Notice that they are preceded by
a colon (:). The commands following each label may be any commands
you need to execute the program you want to run. Note that the LAST
command in each section is GOTO TOP. This will re-run this menu
batch file when you exit the program you have run. (:TOP is at the top
of the file)
Note that the /NC option is used, so it doesn't matter whether the
user presses 'a' or SHIFT 'A'. If you do not use /NC then, in this
example, only small a, b, c, and x would have an effect!
Also note that you could press ENTER to select choice 'b', as
'b' was selected as the default. NOTE YOU CANNOT LEAVE A SPACE
BETWEEN THE WORD 'DEFAULT' and the '=' sign and the default letter!
ie: DEFAULT = a is unacceptable!
DEFAULT=a is fine!!!!!!!!!!!!
If NO input is received from the keyboard after 120 seconds (/t=120),
then the default choice will automatically be made!
For more information regarding the GOTO command, ERRORLEVELS, and other
DOS batch file commands, please refer to your DOS reference manual. If
you have a PIRATED copy of DOS, and have no manual, too bad! I feel no
pity!! <GRIN>
SOME MORE EXAMPLES:
==================
I have added some more examples, as some of the option combinations have
become quite complicated to explain clearly.
(1) GETKEY "Press any key... " /ANY
Errorlevel 0 will be returned for all actions, unless ESC is pressed.
IF ESC is pressed, Errorlevel 10 is returned.
(2) GETKEY "Press any key... " /ANY /ASCII
The errorlevel of the key pressed will be returned, REGARDLESS of what
key is pressed.
If 'a' is pressed, 97 is returned
If 'A' is pressed, 65 is returned
If ESC is pressed, 27 is returned
If SPACE is pressed, 32 is returned
(3) GETKEY "Press any key... " /ANY /ASCII /EU
This is the same as the second example, except pressing 'a' and
pressing 'A' will both return errorlevel 65. ALL letters are
converted to UPPER CASE values.
If /EL was used, all letters would be converted to lower case values.
(4) GETKEY "Choose A,B,C,D or SPACEBAR: ",abcd~ /NC /EL /C(14,0) /DEF=B /T=30
In this case, the prompt is displayed in yellow (on black).
Case checking is OFF. Ie, 'A' or 'a' will work.
All letters will be echoed in LOWER case.
'~' will return errorlevel 5 (space bar)
'D' will return errorlevel 4
'C' will return errorlevel 3
'B' will return errorlevel 2
'A' will return errorlevel 1
If no choice is made in 30 seconds, 'B' is chosen
automatically. If ENTER is pressed, 'B' is also chosen.
(/DEF=B means B is the default)
(5) Another Sample Batch file... TRY THIS ONE OUT!
--------------top of file-------------
@echo off
cls
getkey "Isn't This Great!?" /l(9,32) /c(15,4) /box(5,5,10,70,15,1,2) /box(7,10,6,60,14,4,7)
getkey "[ Press ESC to Exit ]" ,^ /ne /l(14,30) /c(15,1)
echo"
echo"
--------------end of file-------------
******************************************************************************
Revision history:
ver 1.00beta - 1.2 : The first releases of GetKey. The program was
called SELECT at this time, and was written in Turbo Pascal 6.0.
ver 2.0 - totally rewrote the program with Turbo C++ 3.0, thus fixing
bugs, speeding it up, and adding options.
ver 2.4a - added the /ASCII option
ver 2.4b - added the /BEEP option
ver 2.4c - fixed a little bug.. (AAAAAAARG!)
When using the SPACEBAR as a valid key in the keylist,
(ie, using the '~' character), if the SPACEBAR (~) was
set as the default key (/DEF=~) then the program would
get stuck in a loop.. minor logic error. Sorry!
I found this one myself.. locked up my BBS batch file the
other day...
ver 2.5a - Added the /BOX option and also allowed the program to
display the prompt even if a keylist was not specified (this
is handy for echoing colour text on screen in batch files).
Special thanks to Ray (of Montclair, New Jersey) for this
/BOX suggestion! I hope it accomplishes what you were
looking for...
******************************************************************************
This program is freeware. Go ahead and copy it, give it away or even lose it.
You may NOT sell it! This program MAY be distributed as part of a FREE
"add-on" package with other software in packages such as computer systems, etc,
but ONLY if the program and unmodified documentation are distributed together.
PLEASE notify me if you do this. (just because I would like to know!).
Please distribute the documentation (as poor as it may be!) with the program!
If you use this program on a regular basis, I would appreciate if you let me
know that you like it. This is the only form of 'registration' for which
I ask. I just want to know if further developement is worthwhile. Thanks.
Other software by the author, such as PhoneIt 6.0, EasyMenu 3.0, and a few
other wierd and small utilities may be found on the author's BBS.
The BillBoard BBS: (416) 898-2443
Newmarket, Ontario
1200-14,400 baud, v.32bis/v.42bis MNP 2-5. N,8,1
800MB ONLINE! Over 2.5 gigs total!
Feel free to leave me a note if you have any suggestions, complaints (which
I'll just delete... ) questions, or just want to leave mail so I'll have
something to read! Address mail to BILL DYKSTRA.
Thanks!
The Pascal (GetKey version 1.2, also known as SELECT) and Turbo C (GetKey 2.x)
source code files may be available upon request.
--Bill