home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
World of Graphics
/
WOGRAPH.BIN
/
509.MANUAL.DOC
< prev
next >
Wrap
Text File
|
1992-10-15
|
208KB
|
5,317 lines
DOCUMENTATION FOR
VERSION 7.32 (October 15th, 1992)
OF
P11
A GRAPHICS PROGRAM WRITTEN BY:
RUSSELL D. HOFFMAN
P.O. Box 188006
CARLSBAD, CA 92009
(800) 551-2726
(619) 720-7261
America Online:RUSSELL DH
CompuServe:70743,1226
THE AUTHOR ASSUMES NO RESPONSIBILITIES AS TO THE
APPLICABILITY OF THIS PROGRAM TO YOUR NEEDS OR THE
ACCURACY OF ITS FUNCTIONS. PLEASE NOTIFY THE AUTHOR OF
ANY INACCURACIES FOUND AND OF ANY DESIRED NEW FEATURES.
CONCEIVED, DESIGNED, WRITTEN AND PRODUCED
BY RUSSELL D. HOFFMAN IN THE UNITED STATES OF AMERICA.
PROGRAM COPYRIGHT (c) 1984 to 1992,
DOCUMENTATION COPYRIGHT (c) 1985 to 1992 by RUSSELL D.
HOFFMAN.
ALL WORLDWIDE RIGHTS RESERVED.
This document is copyrighted. No portion may be reproduced,
copied, duplicated or stored in an electronic access system
for retrieval by persons other than the rightful owner
and/or user of this product without prior written permission
of the author, except small portions may be taken for
purposes of review or training. This version supersedes all
previous releases of this document and the P11 family of
graphics products. This version is SHAREWARE and is
dedicated to the thousands of users who have contributed to
this product over the years, in so many ways. Thanks to all
of you, past, present,... and future!
Proudly manufactured in the United States of America.
First printing: Version 3.00.00, October, 1987. (Some prior
limited distribution. (Program versions 3.20 & 3.21, 3.50 &
3.51)
Second printing: Version 4.80.00, March, 1989.
Third Printing: Version 6.00.00, May, 1990. (Main program
release was 6.40 (editor) and 6.41 (runtime)
Fourth "Printing": Version 7.22.00, Aug. 4th, 1992
(Shareware)
Fifth "Printing": Version 7.24.00, Aug. 9th, 1992
(Shareware)
Sixth "Printing": Version 7.26.00, Aug. 14th, 1992
(Shareware)
Seventh "Printing": Version 7.30.00, Oct. 9th, 1992
(Shareware)
This technical reference and it's accompanying tutorial and
addenda have been completely revised and updated for use
with the current version of P11 and P11RUN. Additional
addenda to this document may be included for subsequent
releases of P11 and/or P11RUN. The manufacturer reserves
the right to make changes to the programs and/or
documentation without prior notice or obligation.
Numerous companies produce products that are important to
the satisfactory use of this product. Throughout this
manual these products are mentioned. Many of these
product's names are trademarked and we have attempted to
list the owners of these trademarks below.
I.B.M., PC, PC/XT, PC/AT, PS/2, and PC-DOS are all
registered trademarks of International Business Machines
Corporation.
Softgraf is a registered trademark of AutoScribe Corp.,
Rockville, MD
Compaq is a registered trademark of Compaq Computer
Corporation.
Summagraphics is a registered trademark of Summagraphics
Corp.
MS-DOS is a registered trademark of Microsoft Corporation.
Manager Mouse is a registered trademark of The Numonics
Company.
HP Laserjet is a registered trademark of the Hewlett-Packard
Company.
RADIO SHACK and TANDY are registered trademarks of Radio
Shack, Inc.
ATI WONDER CARD and WONDER MOUSE are trademarks of ATI,
Canada
QEMM is a trademark of Quarterdeck Office Systems, Santa
Monica, CA
GRAPHICS MASTER is a registered trademark of TECMAR.
Additional trademarks belong to the companies listed herein.
TABLE OF CONTENTS
COMMANDS AND SYNTAX ................... 1
Alphabetical Listing Of All Commands
ACTIVATE ............. 2
ADD .................. 3
APPEND ............... 4
AUTHORITY ............ 5
BEEP ................. 6
BLANK ................ 7
BREAK ................ 8
BUILD ................ 9
BUTTON ............... 10
CALL ................. 11
CALLM ................ 12
CIRCLE ............... 13
CLEAR ................ 14
CLOCK ................ 15
CLOSE ................ 16
CONNECT .............. 17
CONVERT .............. 18
CRAWL ................ 19
CURSOR ............... 20
DATA ................. 21
DELETE ............... 22
DIGITIZER ............ 23
DISPLAY .............. 24
DIVIDE ............... 25
DOT .................. 26
DRAW ................. 27
ELIMINATE ............ 28
ELSE ................. 29
END .................. 30
ENDIF ................ 31
ERROR ................ 32
EXCHANGE ............. 33
EXECUTE .............. 34
FRAME ................ 36
HEIGHT ............... 37
HUE .................. 38
IF ................... 39
IN ................... 40
JOYSTICK ............. 41
JRCOLOR .............. 42
JUMP ................. 43
KEY .................. 44
LENGTH ............... 45
LINE ................. 46
LOCATE ............... 47
LOAD ................. 48
MARQUE ............... 49
MEMORY ............... 50
MOUSE ................ 51
MOVE ................. 52
MULTIPLY ............. 53
NAME ................. 54
ON ERROR ............. 55
ON KEY ............... 56
OPEN ................. 57
OUT .................. 58
OVERLAY .............. 59
PAINT ................ 60
PASSWORD ............. 61
PEN .................. 62
PRINT ................ 63
QUESTION ............. 64
READ ................. 65
RESTORE .............. 66
RETURN ............... 67
ROTATE ............... 68
ROUNDS ............... 69
RUN .................. 70
SAVE ................. 71
SCREEN ............... 72
SCROLL ............... 73
SET .................. 74
SHOW ................. 75
SOUND ................ 76
SPRINT ............... 77
SPRITE ............... 78
SUBTRACT ............. 79
TEXT ................. 80
THEN ................. 81
WAIT ................. 82
WIDTH ................ 83
WRITE ................ 84
X .................... 85
ZING ................. 86
* .................... 87
" .................... 88
+ .................... 89
\RUN Information Displays....... 90
Picture and Font File Formats... 91
Format for the Auxiliary File... 92
Format for the Hue File......... 93
Space Considerations............ 94
Tips On Making Your Program Faster 95
Uses of the "escape" key........ 96
F10-"Instant" commands & DOS functions 97
Future Enhancements............. 98
Of Mice and Joysticks and Digitizers 99
Timing Considerations........... 100
Converting Images Between Screen Modes 101
Executing DOS from within the program 102
About the Author................ 103
COMMANDS AND SYNTAX
Commands in this language are based on ENGLISH words.
All commands have a backslash in column one and then the
command. You may have one or more spaces between the
backslash and the command word. If the command has
parameters these should follow AT LEAST ONE SPACE after the
command word.
You may have multiple commands on a single line, but
the first character of each command must be a backslash.
The \", \+, and \* commands if used must be the last command
on the line.
\ON KEY commands, which allow the user to move around
within the text file, are only checked between lines (except
during \", \X, \MARQUE, \SHOW and \RUN). \ON KEY checking
will not occur between lines if the last command on the
previous line is \+ (see that command for more information).
Temporary suspension of key checking (except for the ESCAPE
key) enhances the usefulness of the \ON KEY command and is
explained in more detail in the command description.
Usually only the first 1, 2, 3 or (sometimes) more
letters are evaluated when the program decides what word
(command) you have specified. Some commands must be coded
exactly as they appear in this manual, particularly \END,
\ELSE, and \ENDIF. All commands must have enough of them
coded to distinguish them from all other commands. Since
future releases will include additional commands, the use of
abbreviations is NOT AN APPROVED TECHNIQUE. It is mentioned
here "for documentation purposes only."
PARAMETERS
Some commands can have a varying number of parameters
following them. Some may or may not have any parameters at
all. Most expect commas to separate a series of values.
Parameters may be positional or keywords, depending on
the command. As an example of positional parameters, assume
you have issued a command to draw a MARQUE (such as they
have on Broadway) on the screen. This program has such a
command. Here is an example:
\MARQUE 20,24,40,50
This will display a moving rectangular marque with
opposite corners at dot 20,24 and dot 40,50. The syntax of
this command (so far) is \MARQUE #,#,#,#.
KEYWORDS
Some commands have "KEYWORD=" parameters. \MOUSE and
\SPRITE are good examples. A typical \MOUSE command might
look like this:
\MOUSE LOCATION=180,100 WINDOW=33,53,188,130
ROUNDS=30
This will display a mouse cursor at location 180,100
(near the middle of the screen), in a window with opposite
corners at 33,53 and 188,130. It will display for 30 rounds
(see \MOUSE for an explanation of the ROUNDS option).
Parameters, whether positional or keyword, may be
specified with numeric literals, auxboxes, variables, or
mathematical expressions.
MATHEMATICAL EXPRESSIONS
Let's say you don't want to say dot 20,24 as the upper
left corner of the MARQUE, but rather, dot (10 + 10),(8 +
16). This is actually the SAME DOT! 10 plus 10 is twenty,
and 8 plus 16 is twenty-four. You may use parenthesis and
variables just as you would in high-school algebra. You can
use operators for addition, subtraction, multiplication and
division (+,-,/,*) with or without using parenthesis. The
order of evaluation, as with algebra, is parenthesis first,
then multiplication and division equally (left to right),
and then addition and subtraction equally (left to right.)
AUXBOXES
Suppose you don't want to specify an exact place for
the MARQUE, but rather, you want to use values contained in
your auxboxes. The \MARQUE command, using auxboxes, (short
for "AUXilliary storage BOXES" and we pronounce it "OX
BOXES") 1, 2, 3 and 4, would look like this:
\MARQUE #1,#2,#3,#4
If auxbox #1 contained the value 20, #2 contained 24,
#3 contained 40, and #4 contained 50, then this would do
the EXACT SAME THING as in the previous examples.
Syntax requires that auxboxes be described with a pound
sign (#) in front of them, unless you had previously named
the auxbox, in which case you could specify the name instead
of the number. There cannot be any signs (+,-) between the
pound sign (#) and the auxbox number. If the pound sign is
not present, the program thinks it is seeing a numeric
literal if the first character is a number (0 through 9) or
the plus (+) and minus (-) signs. If the first character is
a letter, it assumes you are using a named auxbox, unless
the name is ONE AND ONLY ONE character long. In this case
the program assumes you are referring to one of 26 special
numeric variables (see below).
The auxboxes don't have to contain numbers. They can
also contain "literals" (alphanumerics). For example,
TIME&DATE is an alphanumeric literal, not a number.
Alphanumeric auxboxes can be up to 80 characters long. If
you try to use an auxbox that has non-numeric data in it
when you need a numeric value...it's an error. Also, if you
have not set an auxbox to a value before trying to use it,
that's an error too (auxboxes don't actually exist until you
put something in them.) Auxboxes can be switched back and
forth from numeric to alphanumeric values or removed
entirely to make room for new ones.
VARIABLES
When the program encounters a solitary letter where a
value is expected it is interpreted as a variable, which is
always numeric, and the value in that variable is used in
the command. These are very much like algebraic variables
except for variables A through F. The program AUTOMATICALLY
puts values in those six, so don't try to use them to store
anything! Some other commands will put values in additional
variables (for example \SET.)
Here are some more examples of valid command syntax:
\ADD (8 + 16) TO Q
\LINE (M*3),(N+80),(O-160),(P+ #434),#23
\READ GREETING.PIC
\BUILD #23="Today is ",TIME&DATE[1,8]
\"
SYNTAX
Wherever a pound sign (#) appears in the following
command listing it can mean several things. If it is where
a numeric value should be, it can be an auxbox, variable,
number or mathematical expression containing any of these
elements. If it is where an alphanumeric value should be it
must be an auxbox (not a variable), or in most cases can be
an alphanumeric literal inside quote marks.
Start alphanumeric literals with a single or a double
quote and end them with whichever (single or double) you
started them with. To specify a numeric literal just type
the number. To specify an auxbox type the number of the
auxbox with a pound sign (#) in front of it, such as #123.
If the auxbox is named you may use the name. A number of
commands (such as \DISPLAY) allow either numeric or
alphanumeric values in each position.
Braces ({,}) are used in this manual to indicate that
several different things can be put there, or that optional
parameters may be included. Do not code the braces.
Brackets ([,]) on the other hand should be coded when
indicated. They refer to characters within alphanumeric
auxboxes.
A mathematical expression must be constructed entirely
of mathematical parts. You may use any combination of
parenthesis ( ( ) ), operators (+-*/) and operands
(auxboxes, numbers or variables). Evaluation is standard:
things inside of parenthesis are evaluated first, then
multiplication and division operators are evaluated with
equal precedence, then addition and subtraction equally.
Aside from these rules, evaluation is left-to-right.
Internal calculations are handled as signed double-word
values. This means the intermediate results can be signed
values up to 31 bits long. The final total should be
between -32K and +32K to be handled properly. The following
statement would be valid if auxbox #323 contained a numeric
value and variable R was not 0:
\MOVE (M*N)+O+#323-P+(Q/R) TO S
**** ACTIVATE ****
FORMAT: \ACTIVATE {SCREEN #}
Screen 0 is the actual screen while screen 1 is the
normal background screen. By activating screen 1,
all \SHOW, \RUN, \LINE, \CIRCLE, \DOT and other
pixel-writing commands write to the background
screen. Also all text displayed with the current
font is written to the activated screen. The only
things that are NOT written to the activated frame
are text which uses the DOS font (including numeric
display, lines displayed and entered by the user
with the \QUESTION command, and text displayed for
the \WAIT RETURN command and when the ESCAPE key is
pressed.)
This function is especially useful for designing
complex images which you will want to display all at
once. You can create them while the user is reading
something else on the screen.
The background frame is also used for MASK
operations. The image that is brought forward during
the \SHOW of a masked frame is taken from the
background screen and then the merged frame and
background are moved to the screen. Therefore
although most image display commands can write to
any screen (0,1...), masked frame should only be
written to screen 0. Otherwise unexpected results
may appear.
Any error, even if trapped, will activate screen 0.
**** ADD ****
FORMAT: \ADD # TO #
Must be numeric. The first # can be a mathematical
expression. The second # must be a variable or
auxbox. The result will overlay the second value.
EXAMPLES:
\ADD #24 TO #8
\ADD #24*#43 TO #12
(The second example multiplies the contents of auxbox
24 by the contents of auxbox 43 and adds the product to
the contents of auxbox 12, putting the result in auxbox
12.)
**** APPEND ****
FORMAT: \APPEND NNNNNNNN.PIC #,#
The specified frames from the named picture file on
disk are appended to the current file in RAM or EMM.
This means they are tacked on to the end of the
file. The frames can all be shown in one animated
sequence. It is a good idea to \APPEND as many
frames as possible at once. It is faster, and
whenever you add single frames DOS has to give the
program smaller, more wasteful chunks of RAM. This
can fragment the use of your computer's memory if
you continually are \APPENDing and \DELETEing
frames. Instead, \READ in a new picture file when
possible so the program will return all the previous
allocations of RAM or EMM to DOS and start fresh.
After your \APPEND frames you will need to refer to
the frame #'s as they exist in RAM or EMM--not by
their numbers in the original file.
If the second value is -1 the program will read the
entire picture file.
The # of frames that were actually read will be in
variable "A".
When creating/testing a text file this command will
execute each time it is encountered. Therefore,
your picture file can get very big very quickly.
You will have to get around this, perhaps by
commenting out the line temporarily by inserting an
asterisk (*) in the second column while you test
your text file. Don't forget to remove the asterisk
when you save the text file!
\APPEND can be used to salvage damaged files. If a
picture file is invalid for any reason it cannot be
\READ but it may be possible to \APPEND some or even
all of the frames. Dust particles on a diskette or
"head crashes" could all create invalid file
conditions. Do not expect \APPEND to solve
anything! Maintain multiple backups!
**** AUTHORITY ****
FORMAT: \AUTHORITY {HIGH}
In order to use the \OUT command you need to set the
AUTHORITY LEVEL to high. This merely allows the
\OUT command to execute. OUT is very powerful--you
should KNOW WHAT YOU ARE DOING BEFORE USING THE \OUT
COMMAND. IT IS NOT REPEAT NOT TO BE PLAYED WITH.
It will write directly to the hardware. You can
crash the system or even BREAK THE MONITOR and other
parts if you \OUT garbage. I'm SERIOUS. DON'T USE
\OUT UNLESS YOU UNDERSTAND WHAT IT WILL DO.
That's why you have to enable \OUT with \AUTHORITY.
**** BEEP ****
FORMAT: \BEEP #{,#}
Beeps the speaker for the duration specified in the
first number. The first number represents a unit of
time equal to that used with the SPEED option of the
\ROUNDS command and other commands. A value of 584
will be about one second. A value of zero clicks the
speaker. Maximum value is 10,000. Duration is
preset to 23.
If the \CLOCK speed has been set differently from
the default, the length of the beep will be
proportionately changed.
The optional second number is the tone in cycles-
per-second. If present it must be greater than 20
or it will be ignored. Tone is preset to 988
cycles/second.
\SOUND OFF will override this command.
**** BLANK ****
FORMAT: \BLANK #,#,#,#
Will blank a rectangle on the screen from the first
two values (X-low, Y-low) to the second two values
(X-high, Y-high).
**** BREAK ****
FORMAT: \BREAK {ON} or \BREAK OFF
This command is a debugging tool and is not expected
to ever be used in a finished tutorial. It turns
"single-step" mode on and off. You can also begin
single-step operation by pressing ESCAPE and
following the prompts. To turn single-step mode off
again, press ESCAPE and don't turn the option on.
In single-step mode the next line to be executed
will appear at the bottom of the screen. If
multiple commands appear on the same line they will
all be shown and THEY WILL ALL BE EXECUTED in the
next cycle. After displaying the line the program
waits for you to press a key. That key goes into
the program as if you had pressed it in the normal
course of running the tutorial--it is NOT absorbed
by the "single-step" operation. Macros are NOT
single-stepped.
During single-step mode all \ON KEY jumps and calls
will be taken except the "global" option. However,
the \X NNNNN (paragraph) that the command jumps to
will NOT be shown, nor will any commands on that
line or connected by \+. This is because lines are
only displayed when user keypresses would be checked
for. This is also true for \CALL's and \JUMP's--the
paragraph name lines (\X NNNNN) will not be shown.
**** BUILD ****
FORMAT: \BUILD #=#{,#,# etc.}
This command creates an alphanumeric auxbox out of
other auxboxes, or even pieces of other auxboxes, or
numbers, or literals (in quotes). The maximum total
length is 80 characters. Separate each element with
commas.
EXAMPLE:
\MOVE "HELLO " to #4
\BUILD #3=#4,"THERE!"
\DISPLAY #3 ;(HELLO THERE! is displayed)
**** BUTTON ****
FORMAT: \BUTTON 1=# 2=# 3=#...7=# or 0
Gives an alternate key value for any of seven button
codes used by the mouse, joystick, or digitizer.
The normal (default) key value for all buttons is
7181, the return key. Values do NOT have to
correspond to actual key values.
If the input device supplies a button value greater
than seven it is automatically assigned the keycode
7181.
\BUTTON 0 (zero) will ask the user to enter button
presses and press a key. This gives them an
opportunity to adjust the buttons to what is most
convenient for them. The button presses that the
user responds with will be remapped to the first 3
button values and to no (0) buttons pressed.
NOTE: For codes corresponding to multiple button
presses, the program will "probably" respond to the
first button first, as it is almost impossible to
press the buttons at the exact same time. Similarly
when releasing multiple buttons, an indication of
other combinations is likely to occur. Thus single-
button functions are most reliably reported.
**** CALL ****
FORMAT: \CALL NNNNN
NNNNN is a name of a place in your text file (see
the \X command). The name can be one to 30
characters long with no imbedded spaces. The name
must be exactly the same, including capitals and all
other characters, in all places it appears or you
will not be able to reference it correctly. The
difference between \CALL and \JUMP is that \RETURN
will return processing to the instruction that
follows the \CALL. The instructions that the
program does between the \CALL and the matching
\RETURN are called a subroutine. A subroutine may
call other subroutines, and the current call could
in turn have been called... You can go thirty-two
(32) deep before you get in too deep and the program
can't process. (An error message appears.)
**** CALLM ****
FORMAT: \CALLM NNNNN
Use this special form of the \CALL command to call
paragraphs within macros from text files. Within
all macros, you are expected to eventually \RETURN
to the calling text file, or return with an \ON KEY
or \READ command.
Once inside a macro use the regular \CALL command to
call other paragraphs within the macro area.
When you read in a new text file all nested \CALL's,
\CALLM's and \IF's are reset, and processing begins
at the start of the text file. This will happen
even if the program does not actually read the file
because it is already in RAM (see \READ).
**** CIRCLE ****
FORMAT: \CIRCLE {ANGLE=#,# COLOR=# LOCATION=#,#
RADIUS=#,#}
Draws a circle, oval, or arc by one of two methods.
ANGLE=#,#
If specified the program will use a lookup table of
sine values to calculate the endpoints of 1-degree
connected line segments. If you draw a complete
circle by not specifying any angle (not by
specifying 0,360) it calculates the dots
mathematically using the Pythagorean Theorem.
COLOR=#
If in XOR mode when executed, will produce a
speckled circle because some dots are drawn more
than once.
LOCATION=#,#
Is the location of the center of the circle. It
need not be on the screen.
RADIUS=#,#
Is the length of the radii on the X, Y axis. ANGLES
are only "correct" (circular, not oval) for radii of
10:12 ratio--the ratio of the individual dot's width
to height on a standard CGA monitor with a 4:3
ratio. Other ratios will affect the actual angle
that a specified angle is drawn at. Maximum radius
on either axis is 2000.
**** CLEAR ****
FORMAT: \CLEAR {KEYBOARD, MACROS, NAMES, ON KEYS,
PICTURES, SCREEN, SHOW, SPRITES, SPRITE #}
Resets parameters to "standard" values. Use only
one option at a time.
KEYBOARD
Clears all keys out of the keyboard buffer. The key
values are lost. The program always gets ONE
keypress (if available) between each command line or
cycle of animation and puts it in variable "B". It
is therefore unlikely that the keyboard buffer will
ever fill up, except when executing commands that
take a long time to process. \DRAW with the PAINT
option and \READ are both candidates. Of course,
the user would have to be pressing a lot of keys or
holding one down.
MACROS
Clears the macros you have read so far and their
names. The program stores up to nine macro
filenames that have been read as well as the macros
themselves. This command clears out both the names
and the macros. You can read more than nine macros
without \CLEARing if they will fit in the 10k
(approximate) available, but the names will not be
stored. \READ will reread the macro if it
encounters a name it hasn't stored, possibly filling
up your macro area. You can use \DELETE to remove
specific macro filenames without \CLEARing the macro
area. This command also clears any \ON KEY
specifications that refer to paragraphs in the macro
area.
MOUSE
Sets mouse options to default values. See \MOUSE
for what these values are. The \SCREEN command, if
it changes the current mode, will execute a \CLEAR
MOUSE command automatically.
NAMES
Clears all symbolic auxnames that you have created.
No auxbox data is cleared; it may still be referred
to by auxbox number. Reading new text files and
using the editor does NOT clear auxbox names.
ON KEYS
Clears all \ON KEY specifications either for macros
or for text depending on where the command appears
(it clears only the one it's in). You need not
specify which one to clear. The program clears the
macro specs if you are in a macro and the text specs
if you aren't.
ON ERROR
Clears the \ON ERROR command, making the program
stop on any error again (That's the default.)
PICTURES
This removes all pictures in RAM or EMM from memory.
Use before changing screen modes because you cannot
change to incompatible modes (different resolutions)
while you have pictures in RAM or EMM. You cannot
use this option if you have changes to the current
file or if you are in the picture editor at the
time.
SCREEN
This is a fastest way to clear the screen. Will
clear the background screen if it is currently
active.
SHOW
This clears the parameters set up with the keyword
options of \SHOW. WINDOW is set to the full screen,
AND=NO, OR=NO, XOR=NO, PATH=NO, LOCATION=0,0 and
MOTION=0,0. The \SCREEN command, if it changes the
current mode, will execute a \CLEAR SHOW command
automatically.
SPRITES
Clears all sprites that have been set up with
\SPRITE and \SPRINT and resets all the \SPRITE
parameters to the default values listed in \SPRITE.
SPRITE #
Clears one sprinted frame or resets the \SPRITE
values to their defaults without clearing any
frames. To use this option to clear a single sprite
element you must keep track of which frames were set
up with \SPRINT and in what order. To clear the
first sprinted frame use 1, the second, 2 etc. A
value of zero (0) will reset the \SPRITE parameters
but will NOT clear the elements you have already set
up.
**** CLOCK ****
FORMAT: \CLOCK SPEED=# CURSOR=#,# FORMAT={MM:SS,
HH:MM:SS, HH:MM,SS}
Clock serves several functions. It can be used to
set the number of times that the PC Asynchronous
Clock interrupt occurs each second (SPEED= option),
or to display the current time somewhere on the
screen. When displaying the time only the digits
that change are updated, except the hours digits are
updated with the minutes digits. If you place a
drawing or text over the clock it will not
completely reappear immediately. If a \CLEAR SCREEN
or similar command is executed the entire clock
display will be rewritten.
SPEED=#
Specifies the number of times the asynchronous clock
should cause an internal software interrupt, per
second. Values are from 1 to 6 where one is the
standard DOS amount, about 18.2 times per second,
and each unit above (2, 3 etc.) is twice as often.
The default is 5, or about 584 times per second.
This provides enough control for most applications
without taking too much "overhead" in CPU usage.
This value is temporarily reset to the standard
value, 18.2, during the \EXECUTE command. It is
also reset on exit.
CURSOR=#,#
Specify the position of the on-screen clock on the
screen. Values are in characters on the X, Y axis,
where 0,0 is the upper left corner of the screen.
FORMAT={MM:SS, HH:MM:SS, HH:MM,SS}
Lets you specify how much of the current time you
would like to display. The format HH:MM will blink
the colon every second, other formats update the
hours and minutes only once a minute.
**** CLOSE ****
FORMAT: \CLOSE NNNNNNNN.EXT or LPT#:
This closes a named file or turns off access to
LPT#: (the system printer). NNNNNNNN is the file
name. The extension can be DAT, PIC, or PRN. The
file must have previously been opened with \OPEN.
Errors in processing will cause these files to be
closed automatically when processing stops. They
will also be closed if you exit to DOS.
Files must always be closed if they have been
written to, so that the file directory information
that DOS maintains will be properly updated. For
all manual operations with the editor and when
writing auxiliary files, this program automatically
closes files after it writes them.
Closing LPT#: (where # is 1, 2, or 3) does not
actually signal the printer in any way, it simply
disables access to it with \PRINT. You might do this
so that you can use the statement to write print
files to disk.
EXAMPLES:
\CLOSE LPT1:
\CLOSE SOANDSO.PRN
**** CONNECT ****
FORMAT: \CONNECT {ON or YES} or {OFF or NO}
This will cause vector images to be drawn with
connected dots in the picture editor and with \SHOW.
To draw connected dots with sprites use the
CONNECT=YES option of \SPRITE. The color of the
line that is drawn will be the color of the upcoming
dot. The starting dot of each line segment will not
be drawn after the first one in the image. The
connect option is initially OFF. \CONNECT with no
parameters defaults to turning connected mode ON.
The lines are clipped if the endpoints are off the
screen. In Version 7.24 if the endpoints are more
than 32767 dots apart on any axis a sign conversion
error may occur during internal calculations, and
the line will not be drawn properly. This
separation corresponds to more than 100 times the
width of the screen in the CGA mode and over 150
times the CGA height of 200 dots.
EXAMPLES:
\CONNECT NO ;turns it off
\CONNECT YES ;turns it on
**** CONVERT ****
FORMAT: \CONVERT #
This will convert an auxbox from an alphanumeric to
a numeric or from a numeric to an alphanumeric. It
is up to you to know which way you are going. If
you are going from an alphanumeric to a numeric and
the alphanumeric starts with numbers, it will
convert the numbers only. Numbers that become
greater than 32767 or less than -32768 will produce
an error. The alphanumeric auxbox produced when you
convert from a number is six bytes long and will
contain "leading" (left-hand) spaces in place of
high-order zeroes, with a minus sign (-) if needed
next to the leading character. Non-numeric auxboxes
are displayed with the current font at a location
set by the \LOCATE command. Numeric auxboxes are
displayed with the DOS font, and the cursor position
is then set with \CURSOR.
EXAMPLES:
\MOVE 328 TO #80
\CURSOR 0,0
\DISPLAY #80 ;328 is displayed as a numeric
\CONVERT #80
\LOCATE 0,10
\DISPLAY #80 ;328 displayed in the current font
\DISPLAY #80[4,2] ;32 is displayed.
**** CRAWL ****
FORMAT: \CRAWL #{,X or A or O,#}
This sets text display mode to CRAWL from right to
left. The first number is the speed of the crawl,
the second parameter if included should be an X to
XOR the text onto the screen, or an A or O to AND or
OR the text. If the text is to be XORed, ANDed or
ORed, then a third value should be included as the
color to XOR, AND or OR the text with as it is
placed on the screen. Like \SCROLL and unlike
\OVERLAY it does not XOR, AND or OR the text with
what is already on the screen.
The area to be crawled is set with \LOCATE for the
upper left corner, and \WIDTH. All \CRAWLed text is
one character high.
Anything in the crawl area that was there before
will be shifted off the screen.
This command gives the effect of an electronic news
banner crawling through a window from right to left.
AND, OR, and XOR are most useful for fonts designed
with just black (background) and the highest numeric
color available for the screen mode.
Special considerations for BITPLANE modes:
With \SCROLL and \OVERLAY, in bitplane modes you can
only XOR, AND, or OR with color 1. Use \TEXT PLANE=
for effects similar to what other color values would
give you in bitmapped modes.
OR has no effect in bitplane modes (will work the
same as XOR).
AND with 0 has no effect in ANY mode.
**** CURSOR ****
FORMAT: \CURSOR #,# {,#,#}
This sets a cursor for user input and numeric data
output. The screen in this case should be thought
of as being cursor positions. See the \SCREEN
command for a table of character dimensions for each
screen mode. The upper left corner is position 0,0.
In CGA mode, which is 320 by 200 dots, there are 40
X 25 cursor positions. The first value is the
column (0-39) and the second value is the row (0-
24). The bottom right position of the screen is not
available because DOS would scroll the entire screen
if a character is placed there.
The second two numbers, if present, create a window
for user input and numeric data output. The cursor
will be set to the upper left corner (the place
specified by the first two numbers.) Text lines
that are too long for the available window will be
automatically scrolled for the user.
**** DATA ****
FORMAT: \DATA #{,#,#...}
This command reads ASCII data into auxboxes in P11.
The file should be delimited by commas for each
field and by 13,10 (carriage return, line feed) for
each record. Each \DATA statement reads ONE record.
Maximum record length is 512 bytes including the
13,10. Each field is placed in the corresponding
auxbox, by position.
You should \ELIMINATE the auxbox(s) you will read
data into before executing the \DATA statement.
That way if the auxbox(s) still don't exist you know
you read the last record or a blank (empty) record.
**** DELETE ****
FORMAT: \DELETE {FRAME #} {MACRO NNNNNNNN}
The FRAME option of this command will delete the
frame requested from the current picture file in RAM
provided there are no changes to that file since the
last save. This command will only return the space
to DOS if the frame being deleted is the sole user
of the associated chunk of RAM. See Appendix "E",
Space Considerations, for more information.
The MACRO option will delete the macro name from the
list of stored names. IT WILL NOT DELETE THE MACRO!
This is so you can more easily control which macro
names are stored. When a \READ statement is
encountered and the name matches one of the nine
stored macro names, the read is skipped. You may
use \CLEAR to remove all the macro names but that
also removes the macros.
EXAMPLES:
\DELETE FRAME 23
\DELETE MACRO SETNAMES
**** DIGITIZER ****
FORMAT: \DIGITIZER {OFF}, {INITIALIZE #,#{,#{,#,#}}}, or
{?}
INITIALIZE
Turns the digitizer on. The first two numbers for
X, Y axis resolution are not adjusted before being
passed to the digitizer so be sure to account for
any rounding that the digitizer will do. The
default values (in CGA mode) are 328 on the X-axis
and 298 on the Y-axis. Refer to your digitizer's
manual for more information. The third number if
present should be a two or a one (2 or 1). If two,
COM2 rather than COM1 will be used. (The
communications port COM1 is located at address 3F8h,
while COM2 is at 2F8h.)
The fourth and fifth numbers are the X-offset and
the Y-offset, if you don't want offset 0,0. The
offset is added to the screen X,Y position to get
the minimum axis values. You may prefer a border on
the right as well as the left.
OFF
Turns the digitizer off if it was on.
?
Returns the current state of the digitizer. 0 is
off, 1 is off, but had previously been on, and 2 is
currently on. Value is returned is variable "A".
Turning on the digitizer turns off the mouse or
joystick if they are on.
If you change screen modes you should reset the
digitizer, because the maximum X- and Y- axis values
may be incorrect for the new screen mode.
**** DISPLAY ****
FORMAT: \DISPLAY #{,#,#...}
Will display text or numbers on the screen. Numbers
are displayed using the DOS standard font, and
always on the actual screen, wherever \CURSOR set
the cursor. Alphanumerics, including literals in
quotes, are displayed using the current font
wherever \LOCATE set the text cursor, on the active
screen (see \ACTIVATE.) Additional items can be
displayed when separated by commas. Any literal
auxbox can have just a portion of it displayed by
immediately following the name or # with brackets
and two numbers:
\DISPLAY #45[12,23]
The first number in the brackets is the starting
position to display and the second is the length.
These numbers can be variables or even numeric
auxboxes. Do not use the tab character within a
\DISLAY sequence.
EXAMPLES:
\DISPLAY "Today is ",TIME&DATE[1,8]
\DISPLAY A,B,C,#1,#45,#32767
In the second example, first the variables A, B, and
C will be displayed using the DOS character set at
the current numeric cursor location, and the numeric
cursor location will be advanced by seven places for
each variable displayed. If there is not enough
room (seven characters) the cursor will be advanced
to the next line and to the top of the screen if at
the bottom. The placement of auxboxes #1 and #45 in
this example would depend on whether they were
numeric or not. Auxbox #32767 (TIME&DATE) would be
displayed wherever the non-numeric cursor is set (in
the current font) and would advance the cursor
according to the width of the font. (See \LOCATE.)
**** DIVIDE ****
FORMAT: \DIVIDE # by # {REMAINDER #}
Don't divide by zero, of course. The second number
can be a numeric literal, mathematical equation,
numeric auxbox or variable. The first number must
be a numeric auxbox or variable. The result (aside
from the remainder) goes in the first value, and the
remainder (if specified) goes in the third value.
REMAINDER is optional. If used only the first few
letters (REM) are actually needed. REMAINDER must
follow the second number by at least one space.
EXAMPLES:
\MOVE 32000 TO #48
\DIVIDE #48 BY (34*55) +16000 REM A
\DISPLAY #48,A
1 and 14130 are displayed on the screen. First, the
portion referenced by the word BY is evaluated so that
the program knows what to divide #48 by. (34*55)+16000
is equal to 17870. Dividing 32000 by 17870 gives 1
with a remainder of 14130.
**** DOT ****
FORMAT: \DOT #,#,#{,X or A or O}
The first two numbers are the X, Y location for the
dot. The third number is the color of the dot,
where zero is the background color. The optional ,X
(comma X) will XOR the dot onto the screen. ,X will
also turn on XOR mode for future \DRAW and \LINE
commands. Similarly, A will turn on AND mode and O
will turn on OR mode. Another \DOT command is
needed to turn off XOR, AND and OR. To just turn on
XOR or OR without actually drawing anything, draw a
background dot: This command writes a dot but
background (0) XORs to produce no change. To just
turn on AND, write a foreground dot (whatever the
current screen mode allows as the highest value
dot.) If the third option is a question mark (?)
the color of the dot at the location specified is
put in variable "A". In this case do not use XOR,
AND, or OR.
\PEN can also be used to turn on XOR, AND, and OR
mode.
**** DRAW ****
FORMAT: \DRAW {UDLREFGH}#, C#, J#,#, M{+,-}#,{+,-}#, P
#,{UDLRHVA}, S{X,Y or A}
All parameters here are one letter and then some
numbers or letters or whatever. The options that
belong to each parameter follow that parameter
immediately without spaces, except P (Paint).
Commas are not necessary to separate the elements
providing the syntax is still understandable. For
example the two values that follow the "J", "P", and
"M" options must be separated by commas, but options
need not be.
\DRAW functions more or less as a series of line
segments.
J#,# will Jump to that spot on the screen without
drawing.
UDLREFGH# will move # dots in the direction specified-
-Up, Down, Left, Right and E, F, G, and H which
go at angles. For example one dot to the left
and one up is H while one dot to the right and
one down is F.
C# is a Color, but C followed by just a comma (C,)
sets the current color to clear (which is not the
same as blank.)
S{X, Y or A}# is the Scale amount. X changes the scale
for the X-axis, Y changes the scale for Y-axis,
and A changes them both. A number follows X, Y
or A. 8 is unscaled, so 4 is half scale and 16
is double scale. The X, Y or A must immediately
follow the S with no spaces.
P is the only draw command that should be followed by
one or more spaces after the letter. It stands
for Paint and IS the Paint command, but use only
one letter to describe it. (See \Paint).
M {+,-}#,{+,-}# is Move. M will draw from the current
cursor location to the spot named by the
coordinates #,# that follow the M. The line will
be in the current color If you precede the
numbers with a + or a -, the move will be
relative to the initial cursor position. Both X
and Y must be specified even if they are 0.
EXAMPLES:
\DRAW P 2,D,C2R33M+20,-35J40,43C,R22
IS THE SAME AS:
\DRAW P 2,D,C2,R33,M+20,-35,J40,43,C3,D4,C,R22
In the above example, Paint mode is first set to a
border color of two (2) (red in palette 0 of CGA 4-
color mode), and aimed down. Then the color is set
to two (2) and the cursor is moved to the right 33
units, painting as it goes. The starting position
was not specified so the command would use the
current position. Then the cursor moves to a point
20 dots to the right AND 35 dots down, still
painting as it goes. Next it jumps to location
40,43 WITHOUT DRAWING ANYTHING. Then we set the
color to 3 (yellow in CGA palette 0) and draw down
four dots. Then the color is set to clear and we
move right 22 units, perhaps so that another draw
command can do something there.
**** ELIMINATE ****
FORMAT: \ELIMINATE #,#,# TO #,# TO # etc..
Eliminates auxboxes from the auxfile in RAM. You
can delete one (1) or all (except the 32767th, which
is TIME&DATE). Commas are used to separate boxes to
be removed. When the word TO separates the auxbox
numbers, the range, inclusive, is removed. It is
important to remember two things about this command:
First, you cannot use symbolic names or math
equations or variables to specify the locations to
be eliminated. The expressions must be #23, #45 TO
#87, and so on. They are NOT evaluated--the first
one just listed would remove auxbox 23, not the one
represented by the value stored in 23. Second, the
symbolic name is NOT removed. It still refers to
this box. (Names are removed with \CLEAR NAMES.)
A \READ will NOT read the aux file if it is the
exact same name as the aux file already in RAM.
EXAMPLES:
\* this command clears all auxboxes except,
\* of course, the TIME&DATE auxbox.
\ELIMINATE #1 TO #32766
**** ELSE ****
FORMAT: \ELSE
Part of IF-THEN-ELSE statements. See \IF. When \IF
statements are evaluated, they are either TRUE or
FALSE. If they are false, they go to the
corresponding \ELSE statement (skipping any
subordinate \IF's and the \THEN's and \ELSE's that
accompany them).
Either the \THEN or the \ELSE clause and any
accompanying actions can be left off, but to leave
both off would be totally useless.
EXAMPLES:
\IF #34 = 233
\ELSE
\JUMP NEXT_CHECK
\ENDIF
\IF #54 = "5"
\MOVE 4 TO G
\ENDIF
\X NEXT_CHECK
\IF T = 76
\THEN \MOVE 6 TO Q
\ELSE \MOVE 4 TO Q
\ENDIF
**** END ****
FORMAT: \END
Stops processing and returns you to the editor, or
returns processing to DOS if using the runtime
version.
When the program returns to DOS it passes a return
code as follows:
0--Normal exit--either with this command or
interactively through F6.
1--An error occurred (errors are listed in the back of
this manual).
2--A critical error occurred--most likely a disk error,
but possibly a character device error.
3--Both an error and a critical error occurred. This
is difficult if not impossible to achieve.
**** ENDIF ****
FORMAT: \ENDIF
Ends an IF-THEN-ELSE statement. See \IF. This
statement must come before an \X command (paragraph
name) coded in-line (sequentially) in the text file.
However, you can \JUMP and \CALL your way out of an
\IF statement or even read in a new text file or
\END the program.
\ENDIF ends all nested \IF statements that have been
coded in-line. It does NOT end \IF statements that
were in process when a call occurred, only the one's
SINCE the last call.
EXAMPLES:
\IF #32<999
\ADD 1 TO #32
\ELSE
\MOVE 0 TO #32
\IF C=3
\MOVE 0 TO C
\ELSE
\ADD 1 TO C
\ENDIF
**** ERROR ****
FORMAT: \ERROR ?
Places the last (most recent) error code in variable
"A". It has no other purpose. Use \ON ERROR for
error trapping.
**** EXCHANGE ****
FORMAT: \EXCHANGE SCREENS
If you have saved a screen with \SAVE SCREEN you can
exchange (swap) the current screen with the saved
screen using this command. The screen is saved to
the background screen, screen 1. (See \ACTIVATE.)
The background screen is used for raster frame mask
operations.
If you have set B:0 in the environmental variable
P11FLAGS= or in the startup parameters on the
command line, then the screen will be exchanged with
a previously saved version on disk, in the \P11\TEMP
directory. That directory MUST exist and a screen
must be saved in it before using \EXCHANGE SCREEN.
This will toggle the name of the current saved
screen between SCRNDUMP.SV1 and SCRNDUMP.SV2, so
there must be enough disk space for two entire
screen images in order to use \EXCHANGE SCREEN.
**** EXECUTE ****
FORMAT: \EXECUTE DOS> and then anything you would type at
the DOS prompt, or \EXECUTE > and then a
program you wish to load and execute (run).
This command does not "exit" to DOS. Instead it
will load and execute the named program or load a
second copy of the COMMAND PROCESSOR (DOS) and give
it the command (if any) that follows the greater
than (>) sign.
Legitimate commands could be anything that will fit
in memory. See Appendix "N" for a complete
discussion of this powerful command. What you code
after the > is not evaluated for variables or
auxboxes. It is given directly to the second copy
of DOS, or simply used to load and execute a
program. Therefore drive specifications are NOT
variables or auxboxes. Drive "A" is drive 1, drive
"B" is drive 2 and so on. Use forward slashes (/)
for pathnames: this program will reverse them
automatically (up to the first space). A backslash
would indicate another command on the same line for
this program. If you want to use a backslash after
a space, you can use an auxbox to specify the
command line: Use a parenthesis and specify the
auxbox within the parenthesis: \EXECUTE >(#454)
As of version 7.30 you can do an \EXECUTE with a
PRN, DAT, or PIC file open, but you should be sure
to consider the consequences of this before you do
it: If a file is open and you change disks or
delete the file, you may mess up DOS's idea of the
current file status', damaging that file. It is
advised that you never do an \EXECUTE without
closing all files unless you HAVE TO have them open,
in which case you should try not to let the user
have control during the \EXECUTEd operation. Just
do what you have to do, like an HPRASTER print for
example, and come back.
During an \EXECUTE you can do anything that will fit
in RAM, including formatting disks. However you
should only format diskettes or execute Terminate,
Stay Resident programs if absolutely necessary as it
is likely to take some base RAM to do this, and that
memory will NOT be returned until you reboot.
When executing the command processor, use the
command EXIT there to return to this program (either
at the DOS prompt or from a batch file).
DOS returns a code upon completion of an executed
program. You will find this code in variable "A".
The executed program may return it's own code. This
will be in variable "C". Both these variables will
be changed by \EXECUTE. If the command fails for
some reason variable "A" will contain -1 and
variable "C" will contain the error code returned by
DOS. Possible reasons would be disk errors, file
not found, etc.
**** FRAME ****
FORMAT: \FRAME #,#,#,#{,M or O or OM or MO} or \FRAME #
or \FRAME ?
Specifies that a frame should be added to the end of
the current picture file. You must already have a
picture file in RAM or EMM. This command will only
add a single frame at the end. If you specify four
numbers this will add a raster frame. If you
specify just one number a vector frame of that
number of dots will be added. It will have "random"
dot values at the start. A question mark (?) will
place the current total number of frames in variable
"A".
Specify four numbers to get a raster image from the
screen. The first two are the upper left X, Y
location on the screen. The third and fourth
numbers indicate the size of the frame. This
command will round the first value, the X-
coordinate, down to a byte boundary. In CGA mode
there are four dots per byte so values of 0, 4, 8,
12 etc. would not be changed but 1, 2 and 3 would
all be rounded down, having the effect of saving
from the zero position on the X-axis. 5, 6 and 7
would all round to the fourth dot position and so
on. The right-hand edge will be adjusted
accordingly so that the width will remain unchanged.
See the \SCREEN command for a table of dots per byte
for each available screen mode.
,M will add a masked frame, while ,O will add on
onion skin frame. ,MO or ,OM will add a masked
onion skin frame. Of course, onion skin mode is not
available in monochrome modes!
The base location stored in the header of the new
frame will be 0,0 as will the base time value.
Therefore, you will need to use the location
specified in the \FRAME command when you display the
frame, for it to be in the same location.
You can save up to a full screen--in CGA mode that
would be 320 on the X-axis and 200 on the Y-axis.
When testing a text file that contains this command,
the command will add a frame each time it is
encountered, so you may find you picture file
getting very big very quickly!
If you need to allow more than the default maximum
of about 1000 frames, use the P11FLAGS= environment
string option or command line parameter:
F:# (where # is between 10 and
8,000.)
**** HEIGHT ****
FORMAT: \HEIGHT #
Specifies the height of a text window on the screen.
Used with \LOCATE and \WIDTH to define the area text
will appear in. Text can be \SCROLLed or \OVERLAYd
in the window you define and place with \HEIGHT,
\WIDTH and \LOCATE. (\CRAWL does not use \HEIGHT.)
**** HUE ****
FORMAT: \HUE {COLOR=#,#} {SET=#,#,#} {INCREMENT=#,#,#}
{HOLD={YES or NO}} {CY=YES or NO} GRAY={Y or N}
Hues are preset for all colors, but on VGA systems
you can reset each color to a choice of 262,144
hues. Each of the three portions of each color--
red, green, and blue, can be set to numbers from 0
to 63.
By using this command repeatedly in a text file you
can do "color cycling."
You can set the internal hue table and not actually
set the hue hardware registers by using HOLD=YES.
INCREMENT= will modify the current hue values of a
color. The increment values can each be positive,
negative, or 0.
The COLORS= values are the low and high color
numbers that are to be changed.
CYCLES=YES does color cycling. It moves the color
down 1 within the range and flips the bottom to the
top. Can be added to \RUN too.
GRAY=YES the colors are changed but NOT the color
table. To go back to non-grayscale, use \HUE C=#,#
without any other parameters. If C=#,# is included
with GRAY=Y, only those colors would be gray scaled.
For gray scaling, S, I, and H are ignored.
**** IF ****
FORMAT: \IF # {=><} # {{AND or OR} # {=><} #}
This command is used to compare two operands or two
sets of two operands.
The expression is evaluated and if true the \THEN
clause is executed, then the \ELSE clause is
skipped. If it evaluates to false the \THEN portion
is skipped and the \ELSE clause is executed. These
can be nested 32 deep, and should be ended with
\ENDIF.
If the two #'s represent numbers they are compared
arithmetically. If they represent auxboxes with
alphanumerics in them they are compared as ASCII
strings with the exception that lower-case letters
are capitalized for the comparison. If the two
strings are of unequal length the shorter one is
"padded" with spaces. The ASCII value of a single
character in quote marks (single or double) can be
compared arithmetically. You may use two operators
together (<=, <>, or >=) if desired. You may
connect two sets of comparisons together with either
AND or OR, but only one such connection can be made
(only one keyword AND or OR will be evaluated per
\IF command).
EXAMPLE:
\IF (A + 4) < B\THEN\IF #44 <= #54\THEN\MOVE 44 TO #87
\ELSE\IF S <> 99 OR V=88\THEN\CALL LOOP1\ELSE
\JUMP LOOP2\ELSE\MOVE "APPLES AND ORANGES" to
#989\ENDIF
NOTE: the THEN command is always optional. Spaces
after the backslash are ignored and can sometimes
make program logic easier to follow.
You may want to consult the section on programming
and the \ELSE, \THEN, and \ENDIF commands for
further descriptions of "if" statements.
**** IN ****
FORMAT: \IN # {BYTE or WORD}
IN will let you receive data from a hardware device,
often called a PORT. The byte or word input will be
placed in variable "A". Generally, # is between 0
and 255 and refers to a device in the system.
**** JOYSTICK ****
FORMAT: \JOY (or \JOYSTICK) {OFF, ?} {INITIALIZE
{CENTERED=#,# RESOLUTION=#,# SAMPLES=#}} {ZERO}
{ACCURACY=#,#}
If INITIALIZE is used, the same thing happens as
when you press <CTRL>+j while creating drawings
except values for RESOLUTION, SAMPLES, and CENTERED
are taken from the command and not asked of the
user. A message appears near the bottom of the
screen instructing the user to move the joystick
around and press a key. These keypresses do NOT go
into variable "B".
The numbers that the joystick returns are products
of the current cursor location plus values that
correspond to the joystick positions.
\JOYSTICK ON or \JOYSTICK with no parameters will
get joystick information and if the joystick was off
but had been previously initialed, will turn it on
again.
OFF will inhibit use of the joystick but does not
actually send any signal to the input device.
A question mark (?) will put the status of the
joystick in variable "A". Any other parameters
would be ignored. The status is as follows:
1 - port assumed to be available, not on.
2 - port used, so definitely available.
3 - currently in use (active).
Initializing the joystick turns off the digitizer
but not the mouse if on. Use \MOUSE OFF if you do
not want both on.
RESOLUTION is the maximum variation from the current
position that the joystick can return (maximum
deflection by the user) and is a number from 0 to 50
(0 means no movement on that axis.)
SAMPLES are the number of times to read the joystick
value that is returned before automatically summing
the numbers, throwing out the highest and lowest
values, and averaging the rest. Sampling is a
number from 4 to 50.
The Centered option will cause the joystick to move
the cursor around the point specified. It will be
able to move the distance specified in the
RESOLUTION= parameter. In this mode deflection will
always be from the centered point, not from the last
value returned.
ACCURACY is the units of variation. For example,
A=5,5 will return values of -15,-10,-5,0,5,10,15,
etc. within RESOLUTION maximums (plus and minus.)
The accuracy rounds towards 0 to a multiple of these
settings.
The joystick will simply invert the #'s if the
joystick is held upside down and initialized, but if
at a 90 degree angle, you will get an error message
(Error Code 3585.)
**** JRCOLOR ****
FORMAT: \JRCOLOR #,#,#,#,#
The IBM-PCjr, as well as most TANDY (Radio Shack)
PC-compatibles have the ability to display any four
of 16 colors in CGA mode. To set these colors, use
this command.
Set the background with the first value, then the
three foreground colors. The fifth value is for the
border, which can also be set to one of the 16
available colors.
On TANDY machines you may have to execute the DOS
command MODE with the option COLORMAP before
executing this program for \JRCOLOR to work.
**** JUMP ****
FORMAT: \JUMP NNNNNN
NNNNNN is a named place in your text file. See the
\X command. The name can be one (1) to 30 bytes
long and cannot contain spaces. \JUMPs are
different from \CALLs because they do not retain a
return address (the address of the command after a
\CALL statement is saved for a corresponding \RETURN
statement to use.) Jumps just go somewhere and
processing continues from there. The usual thing to
code after a \JUMP is an \X command for some other
\JUMP, \CALL, \ON KEY or \ON ERROR command to go to,
or if the \JUMP was within the \THEN portion of an
\IF statement, an \ELSE or \ENDIF command may also
follow a \JUMP.
Example:
\* This routine waits forever for ANY key and then
displays it's value.
\MOVE 0 TO B
\X NO_KEY_PRESSED_YET
\IF B=0
\ JUMP NO_KEY_PRESSED_YET
\ENDIF
\DISPLAY B
**** KEY ****
FORMAT: \KEY CYCLE=# DECREASE=# END=# FORWARD=#
INCREASE=# MINUS=# NEXT=# PLUS=# REVERSE=#
SINGLES=#
Lets you assign keyboard codes for various \SHOW and
\RUN options. The numbers correspond to DOS scan
codes for various keypresses.
CYCLE=#
Assigns a key which will cause animation to stop at
the end of the cycle. Only used for \SHOW.
DECREASE=#
Assigns a key for slowing down animation.
END=#
Assigns an alternate key for the ESC key. Pressing
the real ESC key three times in a row will override
this and force the keycode anyway. You cannot code
the RET (return) keycode (7181) for this key.
FORWARD=#
Assigns a key for single-stepping forward through
the frames. Only used for \SHOW.
INCREASE=#
Assigns a key for speeding up animation.
MINUS=#
Assigns a key for making animation run backward.
Only used for \SHOW.
NEXT=#
Assigns a key for ending animation and advancing to
the next command. Only used for \SHOW.
PLUS=#
Assigns a key for making animation run forward.
Only used for \SHOW.
REVERSE=#
Assigns a key for single-stepping backwards through
the frames. Only used for \SHOW.
SINGLES=#
Changes the single-dot cursor movement toggle key.
Initially the "5" key on the numeric keypad serves
this purpose on XT-style keyboards. Setting this
will toggle it to single-dot. A value of 0 will
inhibit changing the dot travel distance.
NOTE: + and - (plus and minus) on the numeric
keyboard are already assigned to PLUS= and MINUS=.
For some of these keys we recommend using the
following keys:
DESCRIPTION KEY
KEY VALUE
CYCLE........SPACE BAR...................14624
DECREASE.....DOWN ARROW..................20480
FORWARD......RIGHT ARROW.................19712
INCREASE.....UP ARROW....................18432
NEXT.........RETURN KEY.................. 7181
MINUS........MINUS KEY...................18989
PLUS.........PLUS KEY....................20011
REVERSE......LEFT ARROW..................19200
SINGLES......"5" KEY ON KEYPAD (XT-STYLE)19456
0 coded in any parameter turns off that option.
NUM LOCK ON NUM LOCK OFF
KEY VALUE
PG DN........20787.......................20736
PG UP........18745.......................18688
HOME.........18231.......................18176
END..........20273.......................20224
LEFT ARROW...19252.......................19200
RIGHT ARROW..19766.......................19712
UP ARROW.....18488.......................18432
DOWN ARROW...20530.......................20480
**** LENGTH ****
FORMAT: \LENGTH #
Gets the length of the specified auxbox and puts it
in variable "A". Numeric auxboxes are always two
bytes long. If the auxbox does not exist the length
will be zero (0).
Example:
\MOVE "EAT MORE CHILI!" TO #32
\LENGTH #32
\DISPLAY A ;15 would be displayed
\MOVE 324 TO #33
\LENGTH #33
\DISPLAY A ;2 would be displayed
**** LINE ****
FORMAT: \LINE #,#,#,#,#{,B or ,BF} or \LINE ,#,#,#{,B or
,BF}
Draws a line on the screen.
The first two numbers are the X, Y coordinates of
one end of the line, the next two are the other end.
The fifth number is the color. The second position
given will become the "current" endpoint (see
below).
If you use the second option (three values preceded
by a comma) a line will be drawn from the current
endpoint (set by a previous \LINE or \DRAW command)
to the endpoint given in the first two values. The
third value is the color. The current endpoint will
be updated to the new endpoint.
,B (comma B) will draw a rectangle with corners as
specified, while ,BF will draw a filled box. The
,BF option will NOT be affected by the status of the
XOR switch nor will it affect that switch. All
other options of \LINE are affected by the current
state of the XOR switch (set with \DOT).
Some lines are not clipped properly. Specifically,
if the total separation on either axis of the two
endpoints is greater than 32767 and both endpoints
are off the screen the displayed line may not be
correct, or incorrect lines are displayed that
should have been completely off the screen. This
does not occur except on widely separated endpoints.
These long lines are excessive values that cannot be
coded in vector draw mode, and are unlikely to be
coded in \LINE or \DRAW commands. But since it's
documented, don't be surprised when--and if--it ever
happens to you. Don't utilize it though--it may be
inconsistent!
**** LOAD ****
FORMAT: \LOAD NNNNNNNN.PIC
This works as a combination of \OPEN and \READ. You
can \READ and \LOAD at the same time. You CANNOT
\OPEN and \LOAD at the same time.
Load will not decompress the file, but nor will it
use EMM. So, if you are working in base RAM, this
can save space, BUT, and this is a big but, it will
only do the things \OPEN can do - it won't work with
\RUN, only with \SHOW.
**** LOCATE ****
FORMAT: \LOCATE #,#
#,# is the X and Y position for the text cursor to
put text lines, alphanumeric auxboxes and literals
on the screen. The X-axis number may be rounded
down, because resolution is every byte on the X-axis
and every dot on the Y-axis. For example, in CGA
mode there are 4 dots per byte on the X-axis. In
all bitplane modes, there are 8 dots per byte.
**** MARQUE ****
FORMAT: \MARQUE #,#,#,#{,#{,#}}
This forms a moving multi-colored rectangle on the
screen. The first four numbers are the X, Y upper
left corner and the X, Y lower right corner. The
fifth number is the number of colors to use in the
marque. If a sixth number is included, then the
fifth and sixth numbers are the "from" and "to"
numbers for the marque. The marque will remain
running on the screen until any key is pressed or
until the value set with \ROUNDS is exceeded (see
\ROUNDS). Speed of each cycle is set with the SPEED
option of \ROUNDS. If ROUNDS is exceeded, -1 will
be in variable "B", otherwise the value of the key
pressed will be there. A mouse button press will
also exit this routine. Variable "C" will have the
number of completed cycles.
A good use of this command might be to indicate
where the user is to enter a response--it doesn't
"absorb" the keypress. If the very next command
were \QUESTION coded on the same line the key
pressed would go into that routine. \MARQUE gets
the key value and puts it in variable "B" but does
not get the key from the keyboard. Pressing a mouse
button would simply exit the \MARQUE command and
enter the next command.
EXAMPLES:
\MARQUE 20,27,44,78,2 \QUESTION #33
The above example would give the keypress (if one
occurred before either the time ran out or a mouse
button was pressed) to \QUESTION because they are
coded on the same line.
\MARQUE 11,13,99,122,3
\QUESTION W
The above example would NOT give the key that ended
\MARQUE to \QUESTION.
**** MEMORY ****
FORMAT: \MEMORY {?} {EMM}
Places the size of the largest piece of memory left
for pictures, executing subprograms, etc. in
variable "A". This does not include space used by
any pictures already in RAM, so it is indicative of
space left to \APPEND frames with. The value
returned is in K (1024 bytes). The question mark
(?) is optional.
If the second option, EMM, is used, this will return
the total number of NEVER-USED 16K (16384 byte)
pages that have been allocated to the program. It
is NOT necessarily the available amount, but is
certainly less than or equal to the amount
available. When pages of EMM are taken by the
program, they are not returned until exiting the
program. Therefore, for example, if you read in a
very large picture file and then a very small
picture file, the number of pages returned by this
function will be quite a bit less than what is
actually available at the time, since once you had
read in the large file, the amount never used will
be less.
**** MOUSE ****
FORMAT: \MOUSE {INITIALIZE, OFF, or ?} {AND={YES or NO}
ACCURACY=#,# END=#,#,#,# FRAME=#,# KEEP=Y (or
anything for no) LOCATION=#,# OR={YES or NO}
RESOLUTION=#,# ROUNDS=# SPEED=# WINDOW=#,#,#,#
XOR={YES or NO or AUTOMATIC}}
\MOUSE allows input of the cursor location and
buttons pressed from the active input device, and
displays a cursor (either a frame, or crosshairs, or
both) at the current position. Raster frames, if
used as a cursor, are positioned with their center
on the current cursor position.
\MOUSE executes until exited by one of several
methods. To exit, the timer can run out (which is
set with the ROUNDS= option); the user can press
any mouse button; they can press any active \ON KEY
key; they can enter any active END window; or they
can press RETURN.
The user can use the cursor keys and the number keys
to move the cursor. The joystick, keyboard or
digitizer can be substituted for the mouse.
(Hardware limitations do not allow the digitizer and
the cursor keys to both work at the same time.) To
some extent, the joystick and the mouse may be used
together.
If you want the user to use the mouse buttons (or
RETURN) to end the mouse activity then don't set any
END= parameters after a \CLEAR MOUSE command. If
you want action to end the moment they enter a
"forbidden zone" (or zones) then END is the choice.
You may not need to know how the \MOUSE command was
exited, but that can be discerned by examining the
appropriate variables. Variable "F" will contain
the input device button value that was pressed if
that is how the routine was exited, or it will have
zero and variable "B" will have the last key
pressed. If variable "F" is zero and variable "B"
is unchanged from a non-valid key value that you had
previously set it to, AND variable "C" indicates
that ROUNDS= had not completed, then the end MUST
have been due to the mouse entering an "END" window.
In any case "D" and "E" will have the mouse X- and
Y- axis positions.
INITIALIZE
INITIALIZE can only be used if no editing changes
exist to any files in RAM, or the mouse has
previously been initialized. However, since the
program initializes the mouse immediately after
loading, this problem should never occur. The
reason the program will not let you initialize the
mouse if changes exist is that if mouse software is
not installed you may have to "reboot" if you try to
initialize the mouse! This in not very likely,
perhaps not even possible, but there is no way for
the program to be absolutely sure. The program
checks for a valid (non-zero) address where the
mouse software address should be. If it's non-zero,
the program "dips it's toe in the water" and sends a
request to the mouse. See Appendix "K" and Appendix
"N" for more information.
?
? (Question mark) will put the current status of the
mouse in variable "A". The meanings are as follows:
0 - mouse software definitely not installed yet, can't
initialize.
1 - can initialize, but are not connected yet.
2 - mouse is already initialized.
NOTE:
? sends a reset message to initialize the MOUSE.
IF THAT SOFTWARE IS NOT INSTALLED, THE PROBLEMS
MENTIONED EARLIER MAY OCCUR.
OFF
Will turn the mouse off if it is on.
The other options can be entered in any order. For
any that are not included the previous settings are
maintained.
AND=YES or NO
AND will place the image on the screen with AND. It
will leave a trail. \CLEAR MOUSE sets AND to NO
(off).
ACCURACY=#,#
Sets the X and Y accuracy in dots. Useful when
block-highlighting text. To do this, set the mouse
WINDOW= parameter width to 1 dot and the height to a
multiple of the text font height. Set ACCURACY= to
the text font height. Make a frame the inverse
color of the text you will use, the size of the text
box to be highlighted and use it as a cursor. Use
the XOR=AUTOMATIC option. You could make a grid of
text boxes this way too. \CLEAR MOUSE sets ACCURACY
to 1,1. The ACCURACY= calculations are done as if
the starting location was 0,0 then the X and Y
offsets are added to get the "actual" current cursor
location.
COLOR=#
Allows you to set the color of the cursor
crosshairs. Valid colors in CGA mode are 1, 2 or 3
(not 0). In MCGA mode the highest color values are
not available (above 247). In all modes, color
cannot be 0.
END=#,#,#,#
This defines a window that will end the mouse
routine if the mouse ever enters it. You may have
up to 10 active END windows. \CLEAR MOUSE sets this
to 0 (no end-windows). Order is X-low, Y-low,
X-high, Y-high. These parameters are not checked
against each other for equivalency, so don't code
the same one 11 times--you'll get a CAN'T PROCEED
error the 11th time. To avoid this, issue \CLEAR
MOUSE prior to setting up the END parameters.
FRAME=#,#
The first value sets the size of the cursor
crosshairs and the second value sets a frame to use
as a cursor. If both are zero the cursor will be a
single dot, but if the frame # is not zero and the
crosshair value is zero, then there will be no
crosshair. \CLEAR MOUSE sets this to 4,0.
KEEP=Y or anything else
Only useful if XOR=AUTO. Leaves the last frame
(and/or crosshair) on the screen when \MOUSE is
exited (regardless of what causes the exit).
LOCATION=#,#
This option sets the starting location for the
mouse. If not included, the position is decided by
the current mouse location if the mouse is active or
by the location set by \DOT or several other
commands.
OR=YES or NO
OR will place the image on the screen with OR. It
will leave a trail. \CLEAR MOUSE sets OR to NO
(off).
RESOLUTION=#,#
Is the maximum variation from the current position
that can occur per cycle. First value is the
minimum change and the second value is the maximum
change. \CLEAR MOUSE sets RESOLUTION to 1,-1.
ROUNDS=#
Sets an upper limit for how long the mouse will be
active. The number of rounds executed will be in
variable "C" at the end. A round is defined as a
new location or one cycle, initially about 1/20th of
a second. If you set this value to -1 the mouse
will run forever unless one of the other exit
methods occurs. \CLEAR MOUSE sets this to -1. If
you set it to 0 the mouse cursor will not be
displayed or used at all.
SPEED=#
Sets the timing for each ROUND. Initially it is set
to 29, which is about 20 cycles per second. At that
rate the number of ROUNDS divided by 20 is
approximately equal to the number of seconds that
the mouse will be active. Zero (0) here means "as
fast as possible". Program updates the mouse
location once per cycle. \CLEAR MOUSE resets this
to 29. This is the speed of the screen image
update.
WINDOW=#,#,#,#
This sets maximum and minimum values for the cursor
in the form X-low, Y-low, X-high, Y-high. The
cursor will appear whole even if parts of it are
outside of this window but the cursor location will
stay within these values (inclusive). By using
narrow values for one of the axis you can make the
cursor move only up and down or back and forth,
useful for choosing menu options. \CLEAR MOUSE sets
this to the full screen.
XOR=YES, NO, or AUTOMATIC
The frame used as a cursor can be permanently placed
at every point it touches if so desired (NO) or it
can be automatically XOR'ed onto the screen and
XOR'ed off again when moved (AUTO). It can also be
set to be XORed onto the screen but not XORed off
(YES). The crosshair is not affected by this
option--it is always removed. Set to auto-xor by
\CLEAR MOUSE.
EXAMPLES:
\MOUSE INIT
\MOUSE R=4444 W=33,44,104,199 L=12,13
\MOUSE ROUNDS=44 WINDOW=0,22,319,23
\MOUSE R=-1 A=10,1 W=33,10,33,190
(The last example would run forever until one of the
exit methods discussed above is taken).
**** MOVE ****
FORMAT: \MOVE #{[#,#]} TO #
The first # can be a literal in single or double
quotes. The # after TO can be a variable or an
auxbox. Of course if it's a variable the first #
has to be numeric data. This command creates the
auxbox if it has not been created yet and changes it
to numeric or alphanumeric as needed. The
destination auxbox will always become the same type
as the source. You can move variables to auxboxes
and you can move auxboxes to variables if the auxbox
is numeric.
You can move a portion of an alphanumeric auxbox by
immediately following the auxbox name or number with
brackets and two values separated by commas. The
values are the starting position within the source
auxbox and the length in characters to move.
If the starting string is shorter than the
"destination" as defined by your offset and length
values, it will pad with spaces.
When moving a literal (in single or double quote
marks) to an auxbox the maximum length of the
literal itself is 254 characters.
EXAMPLES:
\MOVE 343 TO W
\MOVE TIME&DATE[1,8] TO #32
\MOVE "Hi! " TO #1
**** MULTIPLY ****
FORMAT: \MULTIPLY # BY #
Both values must be numeric. The second number can
be an expression that evaluates to a value and the
result goes in the first value, which must be a
variable or auxbox.
EXAMPLES:
MULTIPLY G BY 23
MULTIPLY W BY (#33 * 22)-44+(X*Y*Z)
**** NAME ****
FORMAT: \NAME # = NNNNNNNN
Defines a symbolic name which can then be used to
refer to an auxbox, instead of using its number.
NNNNNNNN is a name that starts with three (3)
capital letters and is at least three (3) characters
long. It ends with a capital letter and is a
maximum of 30 characters. It cannot contain any
spaces. The only other legal characters are the
numbers 0 through 9, the ampersand (&) and the
underline (_). Each auxbox can have no name or one
symbolic name, and a name can refer to only one
auxbox. \NAME does NOT establish the existence of
an auxbox, only its name. Use \MOVE to create the
auxbox. The name TIME&DATE is already assigned to
auxbox #32767. All other names can be cleared with
\CLEAR NAMES.
EXAMPLE:
\NAME #2346=SAVE_THE_PLANET
\MOVE "YES" TO SAVE_THE_PLANET
**** ON ERROR ****
FORMAT: \ON ERROR [JUMP or CALL or CALLM] NNNNN
FORMAT 2: \ON ERROR
This will do a jump or call to the paragraph
specified as NNNNNN if any error occurs other than
those listed as SEVERE errors (see below.) The line
number where the error occurred will be in variable
"A". To get the actual error code that occurred (or
the last one if multiple errors occurred on the
line) use \ERROR. If nothing is specified after \ON
ERROR then error trapping is turned off (format 2).
Error trapping is a one-shot: once used, it is set
off until another \ON ERROR jump or call is issued.
Therefore if an error occurs, you must issue another
\ON ERROR command to inhibit any errors again. You
may want to do this in the error trap routine
itself.
IMPORTANT NOTE: Some errors, documented elsewhere in
this manual, indicate that a reboot may be necessary
after they occur. Although these errors SHOULD be
impossible to get, it is noted here for completeness
that the controlled recovery capabilities of this
command may not work in these cases. All efforts
have been made to make the program "bulletproof",
that is, it should not be possible to crash your
computer while using this program. However despite
all the effort this may not be the case!
The active screen will be the real screen (screen 0)
after ANY error, even if it was trapped.
The real purpose of this command is not so that you
can always restart but rather it is to provide a
mechanism to handle things like file-not-found,
disk-full and so on.
Errors in the runtime version that cannot be
restarted (whose SEVERITY LEVEL is too high)
include:
3562 & 3563 (wrong screen mode errors.)
32767 & 32765 (load errors.)
Both these errors can only occur during the initial
program load, before any files have been read.
Other errors that cannot be restarted involve
attempting to change .i.screen modes; while picture
files for other modes exist in RAM or EMM.
The following additional errors are severe because
they would result in overlaying edit changes. They
can only occur in the editor version:
5, 7, 525, 2624, 4522 & 9218.
And these errors are also severe, and indicate you
wrote your program with syntax errors:
4 and 4004. (paragraph names not found.)
**** ON KEY ****
FORMAT 1: \ON KEY= {YES or NO}
Sets the program to jump to the second command of
a text file. Format is an equal sign (=)
followed by YES or NO.
FORMAT 2: \ON KEY F# {{JUMP or CALL or CALLM} NNNNNN}
This format sets \ON KEY specifications for
function key values. Code an F immediately
followed by a number 1 thru 10 (NOT something
that evaluates to a number, an actual number)
with no space. Follow with CALL or JUMP and then
a paragraph name (NNNNNN) to set \ON KEY
processing. Use just the function number to shut
off a previously set \ON KEY specification.
FORMAT 3: \ON KEY # {{JUMP or CALL or CALLM} NNNNNN}
\ON KEY # {JUMP, CALL or CALLM} NNNNNN where # is
the decimal value of a key and NNNNNN is a
paragraph name to jump to or call when that key
is pressed. Leave the name blank after the key
value to turn off the specification. Fifteen
(15) individual key specifications can be active
at one time, plus function key specifications.
\ON KEY=YES
Means any keypress (except ESCAPE) will cause a jump
to the second command of the text file. It will NOT
jump to the second line of the command file unless
the first line has only one command. =NO turns off
this function. You will find the key value in
variable "B".
ON KEYs are used to control branching within a text
file based on user input. An ON KEY command remains
in affect until it is set off (or a new text file is
read in.) A maximum of 15 specific keys (format 3)
plus 10 function keys (format 2) can be set at one
time.
An important fact to keep in mind when using \ON KEY
is that all \CALL, \CALLM, and \IF nesting is lost
with execution of an \ON KEY JUMP but NOT when an
\ON KEY CALL occurs. An \ON KEY...JUMP works just
like a \JUMP command but occurs when the user
presses the appropriate key, while an \ON KEY...CALL
behaves like a \CALL or \CALLM command.
There are only two ways to get back to a text file
after an \ON KEY jump into a macro file. You could
have coded an \ON KEY in the text file that would
still be active, or you could issue a \READ command
to read a text file and processing will go to the
start of the text file. Other than these two ways,
you will be stuck in macros forever.
It is possible to code values which do not represent
any possible keypress. You can code a value which
represents ESCAPE to the program (283) but if the
user presses that key three times in a row an escape
option WILL BE PROCESSED. You can use \PASSWORD to
prevent unauthorized exiting.
The global \ON KEY specification (format 1) is NOT
ACTIVE during \QUESTION. All other \ON KEY's are
checked with each key the user presses. If an \ON
KEY jump occurs while the user is editing a line the
line is accepted as is and then the \ON KEY process
occurs. Global \ON KEYs are also not active during
"single-step" (debugging) mode. If both global and
specific \ON KEYs are active the specific \ON KEYs
take precedence.
ON KEY...CALL's exit the current command or text
line and will not reenter \MARQUE, \SHOW, \MOUSE and
\RUN. \RETURN will be to the command following the
current command. If you changed fonts and locations
and so on in the \ON KEY called routine these will
remain as changed. Paragraphs that are called with
\ON KEY...CALL should IMMEDIATELY turn off the \ON
KEY condition that called them, on the same line as
the paragraph name (or on a line connected with a \+
command). Otherwise if pressed again it will "re-
call" the paragraph! Just before the \RETURN (on
the same or a connected line) turn the \ON KEY
condition on again. Since \ON KEY's are NOT checked
after a \RETURN command this will mean that
processing will have a chance to return to the
original calling area before doing another \ON
KEY...CALL. In general, \ON KEY...JUMP's are quite
a bit simpler to use and are recommended whenever
possible.
Using \ON KEY # CALL NNNNN can result in a CAN'T
PROCEED error code 3 (Too many calls), especially
if taken via a mouse or other user input device
button. This is because the program checks for the
pressing of the button very rapidly; it can do it
many times before the button is released. To avoid
this, turn OFF the \ON KEY CALL (\ON KEY # will do
it) as soon as you get to the called paragraph (on
the same line as the paragraph name or connected to
it with a \+ command.) Also be sure to connect the
line that turns \ON KEY back on with the \RETURN
that matches the call. Or, have the entire called
paragraph be connected with \+ commands.
ON KEY's are checked once between each command line
in the text file. For text lines, once between each
row or column placed on the screen. The actual
number of checks that will occur per text line would
depend on the height or width of the font. Checking
will NOT occur between multiple commands on the same
line, except prior to \" commands. You can
temporarily "inhibit" \ON KEY checking by coding
commands on the same line. This can be significant
help in insuring that several processes all occur if
the first one occurs. It also executes faster. You
can inhibit \ON KEY checking between command lines
if the last command on the previous line is \+. See
that command for more information on it's use and
restrictions. \ON KEY's are always checked after a
\JUMP has occurred.
EXAMPLES:
\ON KEY=YES
\ON KEY F8 ;Turns off a specification for F8.
\ON KEY #3071 JUMP BEGIN
\ON KEY 16424 CALL SPACE_BAR_PRESSED
\ON KEY F3 JUMP SOME_PLACE_NICE
\ON KEY 7181 ;Turns off \ON KEY for the RETURN key.
\ON KEY 7181 JUMP UP_AND_DOWN
**** OPEN ****
FORMAT: \OPEN {NNNNNNNN.PIC} {NNNNNNNN.DAT} {NNNNNNNN.PRN
{ADD}} {LPT1:} {LPT2:} {LPT3:} {LPT?:} {IGNORE}
Use NNNNNNNN.PIC to open disk-based animation files.
These are animation sequences for use by the \SHOW
command. It is a way to animate sequences of frames
that are larger (perhaps much larger!) than
available RAM or EMM. File should be closed after
use.
Use NNNNNNNN.DAT to open text-style data files for
use with the \DATA command. File should be closed
after use.
For print files (output ASCII files), \OPEN can
specify either a disk file (extension PRN), or the
system printer; LPT1, LPT2, or LPT3, or any printer,
LPT?. Either LPT#, or a print file MUST be opened
before any \PRINT statements attempt to write to
them. You can use the option IGNORE after the LPT#:
to ignore the return code--the printer will be
considered opened regardless of what the status
value is. We recommend you DO NOT use this option
without advising the user explicitly that the system
could hang if the program tries to access a printer
that is not available.
You can only have one print file open at a time.
Use the \CLOSE statement to close them. A disk file
may be reopened after being closed, for additional
\PRINT statements to use, by using the ADD option of
\OPEN. The "file pointer" will be at the end of the
file, of course.
Any CAN'T PROCEED errors in processing will cause
print, data, and disk-based animation files and/or
LPT1, LPT2, or LPT3 to be closed. Opening a print
file will destroy an old one on the disk with the
same name unless you use the ADD option, so only do
this with files you want this to happen to! When
you open LPT1, LPT2, LPT3, or LPT? a reset code is
sent through the BIOS to the printer and the
printer's return status code is placed in variable
"A". The meaning of this code is documented in BIOS
technical references. The program will wait up to
about 12 seconds for the printer to return a valid
(not busy) code.
Picture files shown with \OPEN can use significantly
less RAM since they use only the decompress area and
take no additional RAM or EMM of their own.
Note: Any \ON KEY jumps leave the opened file open,
so have the jumps go to places that close the opened
files or don't use \ON KEY jumps with \OPEN, or set
it up so it expects files to be opened, or store the
status of the file and behave accordingly. Or
something...
**** OUT ****
FORMAT: \OUT #,# {BYTE or WORD}
The first value is the port, usually 0 to 255, and
the second value is the amount to be \OUTed. The
second value can be \OUTed at the address given in
the first value as a byte or word, depending or
which parameter you use. As a byte it must be
between 0 and 255 and as a word, -32K to +32K.
To use this command, you MUST know what you are
doing! This can directly affect the hardware of
your system and even cause damage to your system or
that of your users! You could actually harm a
monitor, disk drive, or other device with this
command! Of course, you are much more likely to
just need to reboot if you use it without
understanding it, but... DON'T USE \OUT UNLESS YOU
UNDERSTAND WHAT IT DOES.
Therefore, you must use \AUTHORITY HIGH to enable
this command.
Do not, REPEAT DO NOT use this command unless you
are absolutely sure that you understand the purpose
of ports, hardware devices, the ASSEMBLER LANGUAGE
OUT command (which this executes), and anything else
that might be important, depending on which port you
plan to OUT data to!
And don't come crying to us if you disobey these
cautions and ruin your system! THIS COMMAND IS
DANGEROUS DON'T USE IT WITHOUT UNDERSTANDING IT
FIRST.
**** OVERLAY ****
FORMAT: \OVERLAY #{,X or O or A}
Sets the text display mode to OVERLAY (as opposed to
SCROLL or CRAWL). The number is the speed at which
to overlay text. If a question mark (?) is used,
text mode is changed to overlay and the current
speed is placed in variable "A". IF ,X is included
the text is XORed onto the screen, if ,A ANDed, if
,O ORed.
AND, OR, and XOR are most useful for fonts designed
with just black (background) and the highest numeric
color available for the screen mode.
In bitplane modes you can AND, OR, and XOR with
color 1 only. Use TEXT PLANE= to get similar
effects to what this would have given with XOR, AND,
and OR in bitmapped modes.
**** PAINT ****
FORMAT: \PAINT #,{UDLRVHBA}
The # specifies the border color to paint up to.
The program will paint in the current color (perhaps
set with \DOT until it reaches the border. The
UDLRVHBA indicates in which direction to paint (up,
down, left, right, vertical, horizontal, both
(vertical and horizontal) and all). Painting occurs
from the current position. When called from \DRAW
just the P should be used (not the AINT). The
option Small Square, available in the picture
editor, is not available as a command.
Painting will take place in the current color set
with \LINE, \DOT, \DRAW, etc.. Except for option
"A" \PAINT will remain active until turned off.
Only one direction can be used at a time. \PAINT
without any parameters turns OFF paint mode.
For the "A" option, the next dot drawn acts as the
"seed" and painting occurs within an area bounded by
the border color specified or the paint color. This
option shuts off after one use. This option uses
the same storage area that "tilt" (in the editor's
draw mode) uses, so if you want to use a tilt line
repeatedly, do NOT paint in between uses. (See
tilt.)
The paint "all" option utilizes a temporary storage
area in RAM to accomplish it's task. It is possible
to use up this area in a very "complex" paint job.
If this happens, some areas will not get filled
completely. The position of the original "seed" can
have some effect on the result in this case. If
this is a problem, try to divide the area to be
painted into two or more individual sections to
paint.
**** PASSWORD ****
FORMAT: \PASSWORD EXIT=# {or "NNNN" or 'NNNN'} TIME=#
This allows you to control runtime user's ability to
return to DOS from within an application.
The maximum password length in single or double
quotes is 10 characters. It may be an alphanumeric
auxbox or literal in quotes but NOT a variable or
numeric auxbox. A password of a space or spaces
clears the option.
Password checking occurs when ESCAPE (or a key
assigned to ESCAPE) is pressed. The full length is
taken even if a wrong key is pressed. Passwords are
only used in the runtime version. The editor
version will parse the command but will not actually
set up a password protection scheme.
Time is specified in 584ths (approx.) of a second
units. The minimum value of 118 is equivalent to
about 1/5th second. Time is per character.
Return must be pressed after the password is
entered.
**** PEN ****
FORMAT: \PEN {AIRBRUSH={NO or #{,#,#...}}} {COLOR=#}
{WIDTH=#} {XOR={YES, NO, ON, OFF}} {CYCLE={NO
or #{,#,#...}}}
Sets pen options for \DOT, \DRAW, \LINE and \CIRCLE.
AIRBRUSH=NO or #{,#,#...}
Turns airbrush mode on or off for subsequent \DOT,
\DRAW, \LINE and \CIRCLE commands. Strength of the
spray is set with the WIDTH option. You can specify
up to ten different colors and these override the
COLOR option (see below). Use NO to turn off the
airbrush.
COLOR=#
Sets pen color for subsequent \DOT, \DRAW, \LINE and
\CIRCLE commands. Valid options are 0 through the
maximum color for the screen mode (3 in CGA mode).
Use any negative number for clear. No value will
also evaluate to clear, but only if this is the last
option in the command. (Otherwise the keyword for
the next option will be evaluated as the number!)
CYCLE=NO or #{,#,#...}
Turns color cycle mode on or off for subsequent
\DOT, \DRAW, \LINE and \CIRCLE commands. You can
specify up to ten different colors. Use NO to turn
off the color cycle option. Since C= would set a
color, you must type at least the CY= portion of
this parameter.
WIDTH=#
Sets pen size for subsequent \DOT, \DRAW, \LINE and
\CIRCLE commands. Valid options are 1 through 5.
XOR=YES or NO, ON or OFF, AND, OR, XOR
Sets XOR, AND, or OR on or off for subsequent
\DRAW, \LINE and \CIRCLE commands. \DOT is not
affected by this command's XOR setting. Through the
current release 7.24, XOR is not compatible with
wide pen lines. Only a one-dot wide line will be
drawn properly in XOR mode. YES/ON and NO/OFF are
exactly equivalent.
**** PRINT ****
FORMAT: \PRINT #{,#,#,#...}
Writes to a print file or LPT#:. You must first
\OPEN the file or use \OPEN to initialize the system
printer.
The format of \PRINT's parameters work just like
\DISPLAY, except you may specify numeric values to
print with brackets ([#]). If you have a trailing
comma the program will NOT add a
carriage-return/line-feed after whatever you print,
but if the comma is not there, then it WILL add the
CR and LF characters (13,10). Numeric values except
those in brackets ([ ]) are converted to a string of
ASCII characters and then the string is printed
Those inside of brackets are sent as 1-byte unsigned
numbers and cannot be less than zero or greater than
255.
If you have not opened LPT#: \PRINT writes to a disk
file previously \OPENed and does not write to the
printer. It will actually write the record to disk
whenever 512 bytes have been printed. When the file
is closed the rest, if any, is written.
One way to print this file later might be to issue a
command to do so from DOS with \EXECUTE. You must
close the disk file before you do this.
EXAMPLES:
\PRINT [27],' Prints the escape character, which has a
decimal value of 27, and then prints this message
followed by a cr/lf.'
\PRINT #232,TIME&DATE," HAVE A NICE DAY",
The second example would print whatever is in auxbox
#232 immediately followed by the TIME&DATE auxbox,
followed by the phrase HAVE A NICE DAY which starts
with a space. No cr/lf is added since the command
ends with a comma.
**** QUESTION ****
FORMAT: \QUESTION #,#{,#{,LOWER}}
Gets keyboard input from the user and places their
response in a variable or auxbox.
If the value of the second number is 0, this asks
for a number from the user and puts it's value in
the location mentioned in the first number, which
must be an auxbox or variable. Otherwise it gets an
ASCII string of the length specified by the second
number (1 thru 80) and puts it in the auxbox
specified by the first number. If the auxbox
already contains alphanumeric data its contents will
appear in the user's edit window for them to make
additional changes to. The user's edit window
location is set with the \CURSOR command. \WAIT
LIMIT sets how long, in seconds, this command will
wait for user input. The user exits \QUESTION by
pressing the RETURN key or any mouse button (unless
the button has been reassigned to a different key.)
\QUESTION uses the DOS standard font for user input,
and the actual screen. It will not use the
background screen.
The third parameter is the cursor position when the
routine begins. If not specified it will be on the
first character in the line. After getting numerics
the cursor will be advanced seven positions. If you
specified a text window with \CURSOR #,#,#,# then
the line will be kept inside that window with
automatic scrolling if necessary. After getting
alphanumerics the cursor position will be set to the
beginning of the line.
When entering alphanumerics users can only enter
capitalized letters unless LOWER has been specified
as the fourth parameter. The third parameter must
be included to use this fourth parameter.
Numeric data outside the valid range (-32768 to
+32767) will be forced into the valid range.
Numbers entered which are less than -32768 will be
returned as -32768, and numbers greater than 32767
will become 32767.. In both instances, the speaker
will beep if the sound is not toggled off. When
getting numeric data, this will blank the six (6)
characters forward from (to the left of) the current
cursor position FIRST.
**** READ ****
FORMAT: \READ {drive:}{/path/}NNNNNNNN.EXT
Reads a picture, font, text, macro, hue, or
auxiliary file into RAM or EMM.
The filename (NNNNNNNN) can be proceeded by a
numeric literal, variable or auxbox and a colon (:).
This will force a new default drive. You are
probably used to referring to the drives as "A",
"B", and "C". Within this program use numbers--
Drive "A" is 1, "B" is 2, etc.
You may optionally include a path specification,
this will change the default path. Since
the program uses the backslash (\) for
commands you cannot use that slash for
pathnames in command lines! Use the forward
slash (/) for pathnames instead.
EXT determines most of what this command does:
TXT will read in a new text file and start
executing that file from the beginning.
Your previous text file is overlaid. (You
cannot overlay edit changes, of course.)
Any \ON KEY specifications that were active
for text will be eliminated when this
command is executed, but NOT any macro \ON
KEY specifications.
FON will read a font file into the font area,
overlaying any previous font. It will NOT
move the font into the picture area. This
can only be done manually. The font area is
normally 20K bytes, but can be set before
loading P11 to any value from 3K to 63K
bytes with a parameter in the P11FLAGS=
environment string (or on the command line).
To do so, use:
FONT:# (# is from 3 to 63)
HUE will read a hue file into the hue table
area, overlaying any hue information that
was already there (you cannot overlay
changes in the editor.) Each screen mode
has it's own hue table where the hue data
will go. You should only read a HUE file
for the mode you are in.
AUX will read an auxiliary file into the aux
area overlaying any auxfile that was already
there.
PIC reads a picture file providing no changes
were made to the current one. The picture
will be read into RAM, or EMM if available.
The number of frames read in will be in
variable "A" after this option is executed.
If the picture is in a different mode from
the current one the screen mode will be
changed to the new picture mode. EMM usage
can be disabled or limited by setting the
P11FLAGS= environment string or the command
line parameter:
EMM:# (0 to inhibit EMM, or any
desired # of EMM pages.)
MAC reads a macro file if the name is not one of
the nine (maximum) stored names. Reading a
macro does NOT clear \ON KEY specifications
for other macros. \CLEAR MACROS will. All
paragraph names in all macros in memory at
any one time must be different or the
program will only access the first one it
encounters. This will not necessarily be
the first one in the file. It may be the
closest, the first, the next, etc. The
easiest way to insure that the proper name
is found is to give all the paragraph names
in each macro a unique prefix.
You may specify the drive as a variable, number, or
numeric auxbox. You can specify the path and
filename (with the extension) as auxboxes too. To
do this, put the auxbox in parenthesis. The path
must ALSO be within slashes (NOT backslashes).
Within the auxboxes, put the period and the
extension with the filename (example: HORSE.TXT).
Within the pathname auxbox include slashes (forward-
or back-slashes are okay within auxboxes). You may
use a single auxbox which includes drive, path and
filename.
NOTE: These commands will only read the file off
the disk if the file is not already in RAM.
EXAMPLES:
\READ #3:/(#4)/(#5)
\READ 3:/FROG/(#6)
\READ /FROG/PIG.PIC
\READ (#7)
In the first example all three elements--drive, path
and filename with extension--are specified symbolically
through the use of auxboxes. In the next example the
path and drive are "hardcoded" and the filename.ext are
in auxbox #6. In the third example the current drive
is used and the path and filename are "hardcoded". In
the last example auxbox #7 may contain the entire
drive, path and filename, or the path and filename, or
the drive and filename, or just the filename. Current
values will be used for unspecified elements.
**** RESTORE ****
FORMAT: \RESTORE {SCREEN}
The entire screen can be stored in a background
area. This will get a screen previously saved with
\SAVE SCREEN. The background area is the same area
used by the raster frame mask option.
You can also restore the screen from disk by setting
B:0 in environment variable P11FLAGS= or on the
command line. This will cause the entire screen to
be read from a file called SCRNDUMP.SV# (#=1 or 2)
in the directory \P11\TEMP.
**** RETURN ****
FORMAT: \RETURN
Will cause processing to return to the command
immediately after the last call. A call can be
established with \CALL, \CALLM, \ON KEY...CALL or
\ON ERROR...CALL. The place returned to could be in
the midst of an \IF statement, but the \RETURN
itself cannot be between an \IF statement and
\ENDIF. No \ON KEY processing or input device
checking occurs between a \RETURN command and the
next command.
**** ROTATE ****
FORMAT: \ROTATE {ANGLE=# FRAME=# LOCATION=#,#}
Lets you rotate a vector frame anywhere from 0 to 90
degrees. The parameters can appear in any order and
should be separated by at least one space. Location
refers to the center dot location about which the
rotation should take place. The location must be
between -2000 and +2000 inclusive on each axis.
Angle is degrees of clockwise rotation.
**** ROUNDS ****
FORMAT: \ROUNDS # {SPEED # or [#{,REPEAT}] {FIXED}
{REVERSIBLE} {WAVING}} {RANGE #,#} {RETRACE}
Sets the number of cycles that \MARQUE, \SHOW or
\RUN will execute. SPEED refers to the time for
each cycle. Each unit represents a small fraction
(about 1/584th) of a second. The larger the number
the longer the pause. If a question mark appears in
SPEED or RUN, the current value will be placed in
variable "A". When the program starts ROUNDS is set
to -1 (cycle forever), and SPEED is set to [0] (use
frame speed controls).
If the speed value is enclosed in brackets ([ ])
then the frame number specified will be used to
control the speed. If non-0, frame must be in RAM
or EMM: it cannot be part of a disk-based picture.
This must be a vector frame. The Y-axis values will
be the timing units for each frame. The first and
last dots will not be used. If the frame number is
followed by the word REPEAT then the cycle will be
repeated. Otherwise the last value will be used
repeatedly after cycling through the frame once. A
value of 0 in brackets ([0]) will use the base
timing values for each frame This is the default
when the program starts. Base timing values of -1
will wait for a keypress or mouse press.
The following additional words may be included after
the SPEED parameter. They do not affect \MARQUE.
FIXED (F)
When specified the user CANNOT change the animation
speed with the up and down arrow keys (or any other
keys that might have been set with the \KEYs
command.) The default is not FIXED.
REVERSIBLE (R)
Allows the user to reverse any animation that
following \SHOW commands display (not used with
\RUN). To do this they must press "-" (minus). "+"
(plus) makes animation run forward again. These
keys may be reassigned with \KEY. The default is
not REVERSIBLE.
WAVING (W)
Used with \SHOW. Animation goes from the first
frame to the last and then back down again a frame
at a time. The default is NOT waving.
RANGE (RA)
The user can speed the animation up to as fast as
the first number and as slow as the second number.
The defaults are 0 (as fast as possible) and -1
(stopped). Whatever you set these to will remain in
effect until the next \ROUNDS command, where it will
be set to the defaults unless reset by you. Note
that a "wrong" initial value for SPEED in terms of
being OUTSIDE the max/min speeds in RANGE will NOT
be checked - but the first time speed is CHANGED by
the user - POOF! it must fit in the boundaries!
RETRACE (RET)
For \SHOW, this will start placing each frame on the
screen at the START of the next vertical retrace
period. This MIGHT make some bitplane animations
smoother. The default is NOT paying any attention
to retrace timing.
**** RUN ****
FORMAT: \RUN {FROM #} {TEXT} {MOUSE} {HUES} {NUMBERS or
FACTS {#}}
Runs animation sequences set up with \SPRITE and
\SPRINT for \ROUNDS number of cycles unless an exit,
such as an \ON KEY keypress, occurs. The user can
adjust the speed if the FIXED option of \ROUNDS has
not been issued.
FROM # causes the \ROUNDS cycle counter to start at
the value specified rather than at zero. No
actions, such as string or position increments etc.
prior to that cycle will take place. The cycle
counter counts up until it reaches the number
specified in \ROUNDS.
With each cycle of \RUN animation, vector images
with \SPRITE XOR=AUTO will XOR off the previous one
before XORing on the new frame. With raster images
it does these two operations concurrently.
HUES will execute the previous HUES command
once with each cycle. This is for use with
CY=YES in the \HUES command.
MOUSE will execute a previous \MOUSE command
concurrent with the sprite activity. The
ROUNDS= and SPEED= options of \MOUSE are
ignored in this case. This lets a mouse
cursor be moved around on the screen with
the \RUN animation, but can leave unusual
pieces of images on the screen in some
cases.
TEXT will cause lines of text to be displayed
concurrently. The lines to be shown follow
\RUN in the text file, and will be placed on
the screen according to the current text
display mode. If a command line is
encountered the text display will stop and
the \RUN command will finish it's cycles.
If on the other hand the \RUN cycles finish
first, the text line display will complete
before going on to the next text line or
command.
The number of cycles completed will be in variable
"C" when this command is exited regardless of how
the exit occurred (finished, \ON KEY pressed, etc.)
Through the current release, if more than 32767
rounds have passed negative numbers will be used,
counting up from -32768.
NUMBERS and FACTS are debugging aids available only
in the editor version. If either is included with a
FROM parameter, FROM must be coded first.
NUMBERS will display five numbers on the bottom of the
screen. The first is the \SPRINT number being
shown. The second number is the frame number in
the picture file. The next number is the current
round, and the last two numbers are the current
position of the sprite.
FACTS displays the current values for sprite motion.
It shows two number columns and one character
column. The top line on the screen is the same
as that displayed by the NUMBERS option at the
bottom of the screen. See Appendix "A" for a
complete listing of what each value refers to.
Press Pg Dn to show more numbers for the same
frame and HOME to go back to the first screen of
information. Use the left and right arrow keys
to see other sprite values without advancing to
the next frame. Press any other key to advance
to the next frame. \ON KEY jumps and calls are
partially inhibited in this mode. You may have
to press the key repeatedly or hold it down to
get it to "take".
FACTS and NUMBERS can be followed by at least one
space and a number. If present then facts/numbers
will not be displayed until after that round has
occurred. If left in a RUNTIME version, these must
be the last parameters on the line and will be
ignored. It is better to remove them after use.
EXAMPLES:
\RUN FROM 23 NUMBERS 44
\RUN MOUSE FACTS
\RUN
\RUN TEXT MOUSE FROM 23 NUMBERS 30
**** SAVE ****
FORMAT: \SAVE {SCREEN}
The entire screen can be copied to its own storage
area. The screen can then be restored with \RESTORE
SCREEN. This uses the same area that is used for
raster pictures with masks.
You can also save the screen to disk by using the
option B:0 in the environment variable P11FLAGS= or
on the command line. This will cause the entire
screen to be "dumped" to a file called SCRNDUMP.SV#
(#=1 or 2) in the directory \P11\TEMP. This
directory MUST exist to use this option! The disk
name will end in either a 1 or a 2. \EXCHANGE
SCREEN will toggle the name since it first writes
out a new screen dump, then reads the old one.
**** SCREEN ****
FORMAT \SCREEN #,#{,#} or MODE=# or ?
The first number is the background color, the second
is the palette, and the third number, if present, is
the screen mode. The default screen mode is 4, CGA.
If the parameter form is used, only the mode number
is changed. Since only CGA uses the background and
palette values, MODE=# is sufficient for all other
modes. Note: Do NOT use the MODE= option in the
environmental variables or on the command line. It
is not able to parse that option. Use the three #'s
version instead.
If a question mark (?) is used the current mode is
placed in variable "A".
This command can be entered from the P11FLAGS=
environment string or from the command line, in
brackets. If it is found there, the mode will be
set before any files are read in. In the editor you
can use this option to convert images from one
screen mode to another. Enter the mode you want the
picture to end up as in the environment string and
then read the picture file into the editor.
SCREEN:#,#,#
In CGA there are two palettes, 0 and 1, and 16
background colors, 0 through 15. Background and
palette values are passed to DOS, which changes the
screen.
If the screen mode is actually changed by this
command, \CLEAR MOUSE and \CLEAR SHOW commands are
executed automatically. It is a good idea to re-
initialize the digitizer if it is being used,
because the dimensions may not match the current
screen mode.
Valid modes are:
Screen Dot
Character
Mode Dimensions Colors Dots/byte Dimensions
Comments
4.......320 X 200.4..4.....40 X 24 CGA-the
original P11 mode.
5.......320 X 200.4..4.....40 X 24 CGA, but a
different palette.
6.......640 X 200.2..8.....80 X 24 CGA monochrome
mode.
9.......320 X 200.16.2.....40 X 24 PCjr or TECMAR
depending on hardware.
10.......640 X 200.4..4.....80 X 24 TECMAR 4-color
mode.
13.......320 X 200.16.2.....40 X 24 EGA 16-color
low-res mode.
14.......640 X 200.16.2.....80 X 24 TECMAR 16-color
mode.
16.......640 X 350.16.8.....80 X 24 EGA 16-color
high-res mode.
17.......640 X 480.2..8.....80 X 30 MCGA high-
density monochrome mode.
18.......640 X 480.16.8.....80 X 24 VGA 16-color
mode.
19.......320 X 200.2561.....40 X 24 MCGA rainbow
mode.
NOTE 1: With third party software, mode 4 can be run in
monochrome on HERCULES hardware.
NOTE 2: PCjr modes are also called extended CGA and
available from many TANDY machines.
**** SCROLL ****
FORMAT: \SCROLL #{,{AOX},#}
Similar to \OVERLAY and \CRAWL but sets the text
display mode to scroll all text up the screen. The
first parameter sets the speed of the scroll. The
second parameter, if included, will cause text to be
XOR'ed, AND'ed, or OR'ed with the color specified in
the third parameter before it appears on the screen.
Unlike \OVERLAY this will not XOR, AND, or OR with
what is already on the screen--that gets scrolled up
and lost.
AND, OR, and XOR are most useful for fonts designed
with just black (background) and the highest numeric
color available for the screen mode.
As with \CRAWL and \OVERLAY in bitplane modes, you
can only XOR, AND, or OR text with color 1. Use
TEXT PLANES= to get additional colors.
**** SET ****
FORMAT: \SET COLOR=# DOT={# or ?} FRAME=# LOCATION=#,#
MODE={GET or SET}
Lets you manipulate individual dots of a vector
drawing from within a command file. COLOR is the
dot's new color. DOT is the dot number. FRAME is
the frame number the dot belongs in. LOCATION is
the new X-axis and Y-axis values for the dot. MODE
lets you choose to GET information about the current
dot's location and color, or SET it. (SET is the
default. If GET is used it must be specified for
EACH \SET command.)
IF the DOT=? option is used, then the MODE= option
will be ignored, the current dot will be set to dot
1 (the first dot in the file) and the total number
of dots in frame specified in the FRAME=# option
will be placed in variable "A". The vector image
will NOT be changed at all. If you use this command
on a RASTER image it results in an error.
This command does not create a frame or insert or
delete dots. It only changes dots within an
existing frame. Use \FRAME to create a vector
frame. You cannot execute this command if changes
exist to the picture file currently in memory.
You can let values default. Any value not specified
will default to the value in a previous \SET, except
DOT will increment by 1 if not specified explicitly.
**** SHOW ****
FORMAT 1: \SHOW #,#,#,#{,A}{,O}{,X}{,S}
FORMAT 2: \SHOW AND={YES or NO} FRAME=#,# LOCATE=#,#
MOTION=#,# OR={YES or NO} PATH=#{,#} SAVE={YES
or NO} WINDOW=#,#,#,# XOR={YES or NO}
Does animation on the screen, saves a frame whose
space has already been allocated, or AND's, OR's, or
XOR's a frame onto the screen. For raster drawings
accuracy is to the nearest byte boundary on the
horizontal axis. In CGA mode it is every 4 dots, 8
dots in monochrome modes, etc. See \SCREEN for a
table of dots per byte. For vector drawings the
location specified is NOT offset by the first dot's
value. If a disk-based animation file is open,
\SHOW will use it, but any vector paths or timing
frames must be in RAM or EMM.
In format 1, the first two values set the location
on the screen. The next values are the "from" and
"to" frames, and the fifth value if present is A
(and), O (or), X (xor) or S (save). These options
are valid only when the "from" and "to" frames are
the same. See the descriptions in format 2 to
understand how each of these options function.
If you just want to show one frame on the screen
without AND, OR, or XOR you can just use three
numbers (the X and Y locations and the frame
number).
In format 2, parameters are specified with keywords.
Their meanings follow:
AND={YES or NO}
When placing only one frame on the screen (both
FRAME= values are the same) you may use AND. This
is a mathematical function which ANDs the picture
into the screen.
FRAME=#,#
Indicates the "from" and "to" frames, respectively,
to animate. If the second number is less than the
first, the animation will run in reverse order
unless the second number is -1, which means to
animate all frames from the first number to the last
frame in the file.
LOCATE=#,#
The upper left corner of the animation. For raster
frames add the base offset to get the actual
location, rounded to a byte boundary. (In CGA mode,
every 4 dots.)
MOTION=#,#
Indicates X- and Y-axis increments to the beginning
location. Incrementing occurs each cycle.
OR={YES or NO}
When placing only one frame on the screen (both
FRAME= values are the same) you may use OR. This is
a mathematical function which will OR the frame into
the screen.
PATH=#,# or PATH=NO
Indicates a vector frame to use as a path. The
second # indicates a dot to start at. Use NO to
specify no path. This will repeat from the first
active dot (the second dot of the frame) if it gets
to the penultimate dot of the frame.
SAVE={YES or NO}
Saves rather than displays a frame. Only one frame
can be saved at a time: FRAME=#,# must indicate only
one frame--both numbers must be the same. If the
frame dimensions and the location specified cause a
portion to be outside the screen or the current
window, only that portion visible would be saved.
The frame must already exist in the file. This will
overwrite it but will not be considered a change for
editing purposes. It will not execute if changes
exist.
WINDOW=#,#,#,#
Indicates a viewing window. Lower X-axis values are
rounded to byte boundaries.
XOR={YES or NO}
When placing only one frame on the screen (both
FRAME= values are the same) you may use XOR. This
is a mathematical function which will XOR the frame
with the screen. If you XOR the same image into the
screen twice in the same place, the original screen
image will be unchanged.
Animation runs for \ROUNDS number of cycles unless the user
exits by pressing an active \ON KEY or the \KEY NEXT= key.
A parameter of \ROUNDS sets the speed. The user can change
the speed if the FIXED option of \ROUNDS was not issued.
When exited the number of cycles completed will be in
variable "C".
EXAMPLES:
\SHOW 22,88,3,3,X
\SHOW 37,45,4,8
Parameters 1 and 2 are screen position.
Parameter 3 is the beginning frame.
Parameter 4 is the ending frame. This should be the
same as parameter 3 for the ,A ,O, ,X and ,S options.
Parameter 5, if included, is either A for AND, O for
OR, X for XOR or S for SAVE.
\SHOW FRAME=7,-1 MOTION=4,0
This example uses the keyword format of \SHOW. It
would animate from frame seven through the last frame
in the file. These frames would move to the right four
dots for each frame shown.
**** SOUND ****
FORMAT: \SOUND ON or OFF
Toggles the sound capabilities on and off. It does
not produce any noise but will inhibit \BEEP if
\SOUND is set OFF. If you execute \SOUND OFF all
beeps will be inhibited including any you issue with
\BEEP and any the program would issue itself.
**** SPRINT ****
FORMAT \SPRINT #{,# TO #...}
Indicates the frames to be used with current sprite
motion parameters. First, set up the desired motion
parameters with \SPRITE. Then indicate which frames
should follow those parameters with \SPRINT. After
you have set up all the images with their motion
parameters, use \RUN to display the animation
sequence.
The word SPRINT was chosen because the command is
similar to \PRINT in syntax, and because SPRITE
characters can be made to SPRINT across the screen.
To "sprint" animation you must list each frame to be
sprinted or use " TO " to indicate a series of
frames.
EXAMPLES:
\SPRITE TYPE=R ANIMATE=3
\SPRINT 1,2,3,4,5,6,7
\RUN
\SPRITE T=R A=3\SPRINT 1 TO 7\RUN
\SPRITE T=R A=3 \MOVE 1 TO G
\X LOOP1
\SPRINT G
\IF G<7 \ADD 1 TO G \JUMP LOOP1
\ENDIF
\RUN
(These three examples produce the exact same image.)
**** SPRITE ****
FORMAT: \SPRITE AND=YES or NO ANIMATE={# or NO}
CONNECT={YES or NO} INCREMENT=#,# END=#,#,#,#
FAST={Y or anything} MOTION=#,# OPEN=#,#,#,#
TYPE={R or anything} PATH={#,# or NO}
ROUNDS=#,# STRING=#,# WINDOW=#,#,#,# WPATH={#,#
or NO} XOR={N, A or Y} ZING={#,#,# or NO}
Sets up animation parameters for \SPRINT frames to
use.
The keywords are used to control a wide variety of
animation activities. After using \SPRITE and
\SPRINT commands to set up the action use \RUN to
activate everything. Motion will continue for
\ROUNDS number of cycles at a chosen SPEED.
EXAMPLE:
\SPRITE WINDOW=33,22,37,145 ROUNDS=33,76
Would set a display window that would apply to any
frames that are set with subsequent \SPRINT
commands. This would change if you issue another
window value or a \CLEAR SPRITES command. It would
also set the elements to become "active" (be
displayed if in the window) at round 33 and become
inactive after round 76.
Following are the keywords (which can be entered as
just the first letter or letters) and their
meanings:
AND=YES or NO
The image can be ANDed, ORed, or XORed onto the
screen. This will cause it to be ANDed.
ANIMATE=# or NO
The value is the number of cycles to hold each frame
on the screen. Sometimes you do not want a
particular group of animated frames to change as
frequently as other action occurs within a cycle, in
that case you would use a number greater than 1
here. NO sets this option off. Animation frames
must follow one another with no intervening elements
when created with \SPRINT. Other elements can
appear but each animation sequence must run together
and be separated from other animation by at least
one non-animated \SPRINT frame. Only one of the
frames in the sequence is shown per cycle.
If the animation reaches a END= window or the end of
a PATH, then if TYPE is not REPEAT but KEEP=YES, the
animation will continue in place at the end location
until the ROUNDS= ending cycle is reached. MOTION
amounts are added only when an element of the
animation sequence is displayed, NOT necessarily
every round (it depends on the value ANIMATION is
set to.) \CLEAR SPRITES sets animation to OFF (NO).
CONNECT=YES or NO
This turns on the connected dot mode for vector
images. Line segments are drawn between each dot:
the first dot is drawn and subsequent line segments
are the color of their endpoint. Their startpoints
(the previous line segment's endpoints) are not
redrawn. The lines are clipped to the screen edge
then the individual dots are drawn or not drawn
depending on whether they are within an active
window.
END=#,#,#,#
If the sprite reaches the window defined by these
four values the sprite action ends. Values are
X-low, Y-low, X-high, Y-high. (The actual value
stored is offset by the values in the first dot of
the frame (if vector) or 0,0 (if raster).) If
TYPE=R the sprite repeats in place if it gets to the
END window. The END= window is initialized to 5000,
5000, 4999, 4999 by \CLEAR SPRITES, which indicates
NO end area.
FAST=YES or NO
This only affects raster drawings. When set to YES
(or "Y") images are placed on the screen at byte
boundaries for much faster operation. Auto-xor will
be treated as XOR=YES if FAST=YES. FAST must be
equal to YES to use a frame mask. The mask is
automatically ANDed and the image ORed together with
the background screen and the combined image
displayed on the screen. Use this to move an object
across a background image.
INCREMENT=#,#
When using the STRING= option for displaying vector
frames these values will be added to the beginning
and ending string values each round. They represent
the number of bytes to add. Since each dot takes
four bytes in memory a value of four (4) will
increment by one dot each cycle. This allows an
increment of less than one dot per cycle, for
instance a value of 1 will increment by one dot
every four cycles while a value of two will
increment by one dot every other cycle. \CLEAR
SPRITES sets this to 0,0.
KEEP=Y or anything else
When the sprite reaches an end of some sort
(location, round, etc.) it will NOT be xor'ed off if
this is set to Yes, even if Auto-xor is on. If the
sprite is part of an animation sequence (ANIMATE=#)
then the animation will continue to run at the
stopped location until the ending round. If the end
was achieved by reaching the end of a path or an
END= window, animation at the ending location
continues. (If TYPE=REPEAT then animation will
continue at the starting location or at the first
dot of a path.) If not animating, this option is
only useful for auto-xor.
LOCATION=#,#
This sets the starting location. The first dot in
the image (if vector) or 0,0 (if raster) is
subtracted from this value and then all subsequent
dots (if vector) are offset by the resultant amount.
For raster images, add the base offset to get the
actual location. Set to 0,0 by \CLEAR SPRITES.
MOTION=#,#
This sets up values to be added to the location X
and Y values each round. (If animating, each cycle
that an image is changed). With this option things
can move in any direction including onto, off, and
around the screen. \CLEAR SPRITES sets this to 0,0.
OPEN=#,#,#,#
This lets you adjust the corners of a viewing
window; the four values are the X-low, Y-low, X-high
and Y-high amounts to add to the base window values
each time the frame is shown. You may want to use
negative numbers for the X-low and Y-low increment
amounts and positive numbers of the X-high and Y-
high increment amounts. If any value becomes below
0 or greater than the screen size it will cease to
change. If you use a window path (WPATH=) this
option will not be utilized. \CLEAR SPRITES sets it
to 0,0,0,0.
OR=YES or NO
The image can be ANDed, ORed, or XORed onto the
screen. This will cause it to be ORed.
PATH=#,# or NO
This indicates a vector frame to use as a path (or
"track"). If the frame is raster it will be caught
as an error when you use \SPRINT. The first value
is which frame to use as a path. The second value
is which dot within that path to start on. If you
choose the REPEAT option of TYPE=, repetition along
the path will be from the beginning, NOT from the
specified dot. Repeat begins when you reach the
second-to-last dot in the path frame or an END=
window. The second value is ONLY valid for the
first time around the path. The starting location
will be the sum of the values in the LOCATION=
parameters, the current path dot chosen and
additionally, if vector, the first dot (the one NOT
shown) of the frame (NOT of the path). To start the
path at the first active dot (the second dot) of a
vector image code a one (1) in the second parameter
of this option. To turn off this parameter code the
word NO after the equal sign. \CLEAR SPRITES sets
this option off.
ROUNDS=#,#
Sets the starting and ending cycles that a sprite is
to be shown from and until, respectively. No string
incrementing, motion, etc. will occur until the
starting round and the image will not be shown. Once
the starting round is passed values will be adjusted
once each round based on the options that were set
with other \SPRITE keywords. Each \SPRINT frame
will be adjusted unless the frame becomes inactive.
\CLEAR SPRITES sets ROUNDS to 0,-1. -1 will run
forever. If the -1 round is reached it will be
ignored and the sprite will continue to be active.
STRING=#,#
This is only useful for vector drawings. It is the
dots (not including the first and last) that are
actually to be shown on the screen. The first value
is the first dot to show and the second is the
number of dots to show. If these values are changed
with INCREMENT= and reach the next-to-last dot the
string that is shown will work it's way completely
off the screen unless TYPE=REPEAT. In that case it
will repeat from the first active dot in the image
for a length specified, NOT from the initial
starting dot. That dot is only effective for the
first pass. The first active dot (the second actual
dot) is number 1. \CLEAR SPRITES sets this to
0,16384.
TYPE={R or anything else}
Sets up repeat-sequences. Repeat resets to the
beginning values and starts over if the sprinted
frame gets to the position given in END=. If a PATH=
or STRING= option gets to the last active dot it
will reset to the first active dot. Repetition
stops if the ending ROUNDS= value is reached. Any
character except R sets this option off.
WINDOW=#,#,#,#
Sets a window smaller than full screen size. Images
will scroll out of these windows as if they were
scrolling off the screen. Window is reset to the
full screen size with \CLEAR SPRITES.
WPATH=#,# or NO
Sets a path for a window to follow. If you use this
option the WINDOW= values will be the base (initial)
window location and it's size. You cannot use OPEN=
with WPATH. \CLEAR SPRITES sets this to NO.
XOR={A, N, X or Y}
When set to "N" (NO), objects are simply put on the
screen where you say to. If moving, they will leave
a trail unless the edges are the same color as what
they move across--experimentation will explain this
better. When set to "A" (Automatic) the program
will XOR off the last position as it is drawing the
new position. This has the useful effect of leaving
the background image unchanged. When set to "Y"
(Yes) or "X" the drawing will be XOR'ed on, but if
you want to remove it YOU must XOR the frame onto
the screen a second time. XOR=NO is the fastest.
\CLEAR SPRITES sets this to NO.
You can't mix vector and raster XOR=A animation and
get what you might expect. Animation in this mode
can be very useful--images are removed as the new
ones are put on. If you were to manually XOR frames
on and off they will not be XORed concurrently.
Auto-xor works fine for all-vector or all-raster
groups, but if you mix types in an animation
sequence it will XOR off one frame THEN XOR on the
next in AUTO mode.
ZING=#,#,# or ZING=NO
The third value here sets a raster frame to the
location specified by the first two values. The
frame's base values are added to the X- and Y-axis
values specified to determine the actual location of
the upper left corner of the image.
This does not by itself cause the frame to be
displayed--yet. When a subsequent vector frame is
passed over the raster frame, the raster frame is
displayed rather than the vector dots. Works with
XOR but not with AUTO-XOR. ZING works with the FAST
option to display a byte at a time (four dots
horizontally in CGA mode.)
EXAMPLES:
\READ GALLOP.PIC\ROUNDS 50 SPEED 33\CLEAR SPRITES
\SPRITE M=0,4 F=Y A=1\SPRINT 1 TO 15\RUN
This would make a horse gallop across the screen from
left to right.
**** SUBTRACT ****
FORMAT: \SUBTRACT # FROM #
The first value can be an expression that evaluates
to a number. The answer will be placed in the
second value. The first value can be a number,
variable or auxbox but the second must be a variable
or auxbox. Both values must be numeric.
Remember that the maximum and minimum values of a
number or 32767 and -32768 respectively, and that
results of mathematical operations will "wrap
around" in order to stay within this range.
Internal calculations are double-word signed values,
accurate to 31 bits.
EXAMPLES:
\SUBTRACT A FROM B
\SUBTRACT 99 FROM #767
\SUBTRACT (W-55) FROM Q
**** THEN ****
FORMAT: \THEN
Follows an \IF statement and begins the portion that
will be executed when the condition in the \IF
statement evaluates as true. The \ELSE statement,
which can follow the \THEN clause, starts that
portion that will be executed if the \IF statement
proves false. Both the \THEN statement itself
and/or any accompanying commands to execute, or text
to display, are optional. In that case you would
code the \ELSE portion directly following the \IF
statement. The \THEN statement doesn't actually do
anything and is totally ignored, even if it is out
of position, but it can sometimes make your program
a little easier to read.
EXAMPLES:
\IF APPLES=ORANGES
\THEN
\ MOVE "OH MY GOSH!!" TO #21
\ELSE
\ IF PIGS_HAVE_WINGS = "TRUE"
\ THEN
\ MOVE "NO WAY!!" TO #21
\ ELSE
\ MOVE "ALL IS WELL" TO #21
\ENDIF
\DISPLAY #21
In this example APPLES, ORANGES, and PIGS_HAVE_WINGS
are all named auxboxes.
**** TEXT ****
FORMAT: \TEXT {PLANES=1111}
PLANES=is a binary number. It is only applicable to
bitplane modes and should contain as many digits as
bitplanes. By changing active bitplanes the color
of the text will be changed. It is set to all one's
(1111 for four plane mode) whenever the screen mode
is changed.
EXAMPLE:
\TEXT PLANE=1011 ;This will set planes zero, two, and
three active and plane one will be off.
**** WAIT ****
FORMAT: \WAIT LIMIT # or NOW # or RETURN # {"NNNNNN"}
Sets how long the program will wait for the user to
respond (LIMIT), how long to wait for a return key
to be pressed (RETURN), or how long to just WAIT
(NOW). The larger the number specified, the longer
the wait.
For LIMIT and RETURN, the time units are in seconds.
For NOW, it is the same as for the SPEED option of
\ROUNDS--about 1/584th of a second if you have not
reset the clock speed with \CLOCK. A value of -1
will wait forever (until a keypress.)
\WAIT LIMIT # is the amount of time in seconds to
wait for the user to press the return key during
user input with \QUESTION. Unless reassigned to a
different key any mouse button is equivalent to the
RETURN key.
For the \WAIT RETURN # option the value (#) can be
followed by a comma and an alphanumeric "literal" in
single or double quote marks (both quote marks must
be the same). This literal will replace the message
normally displayed (maximum 78 characters). If two
quote marks are coded next to each other, no message
will appear (a cursor will still appear, however.)
The location of the message cannot be changed (it
starts at the left edge of the second line from the
bottom.)
If \WAIT RETURN exceeds the time specified, -1 will
be placed in variable "B", otherwise 7181, the value
of the return key, will be there. Pressing any
mouse button will also end \WAIT RETURN and in that
case variable "F" will hold the mouse button
pressed. (Unless reassigned with \BUTTONS, mouse
buttons are equivalent to the RETURN key.)
WAIT NOW simply suspends all processing for the
specified time or until a key is pressed. Use this
option to give the user a fixed amount of time to
read the screen.
EXAMPLE:
\WAIT RETURN 20 "SHOW BEGINS WHEN YOU PRESS RETURN"
\WAIT NOW 584 ;waits about one second.
**** WIDTH ****
FORMAT: \WIDTH # {DOTS} {LEFT, RIGHT, BOTH, or CENTERED}
{PROPORTIONAL}
Sets the width in either characters or dots that
will be displayed on the screen when text statements
are encountered. Words are wrapped to the next line
for \OVERLAY and \SCROLL. If specified in
characters the actual width of the text as it
appears on the screen will be the product of this
value and the width of the current font.
You can specify justification other than left
justified (the default). When not specified,
justification will be LEFT after this command.
You can specify the width in dots rather than
characters. Proportional font widths should always
be specified this way. The number of dots is
rounded down to a 2-byte (word) boundary (in CGA
mode there are 8 dots per word.)
You can use the proportional option even when using
a non-proportional font. For example when using
BOTH text justification you need to specify
proportional so that it will adjust the spacing
between words correctly. (BOTH option is not
available for non-proportional fonts.)
Proportional text processing can be significantly
slower than non-proportional, but usually looks a
lot better.
As of version 7, justified BOTH will justify LEFT if
it is the last line (or only line.) Thus, just BOTH
only works for lines >1 line.
**** WRITE ****
FORMAT: \WRITE {drive:}{/path/}NNNNNNNN.EXT
The only valid file that can be written with this
command is an auxiliary file so the EXT must always
be AUX. All other files will be ignored. (Print
files are automatically written out 512 bytes at a
time with \PRINT.)
Text, hue, picture and font files that you create
cannot be written to disk this way. They must be
written out manually with function key 6.
As with \READ, \OPEN and \CLOSE you may specify the
filename, path, etc. symbolically. See \READ for
examples and explanations.
**** X ****
FORMAT: \X NNNNNN
NNNNNN is a one (1) to 30 byte name. This is a
place that \CALL, \CALLM and \JUMP go to. The name
must be exactly the same everywhere it is used. \ON
KEY and \ON ERROR also jump or call these places.
This command cannot appear in an \IF sequence
(between the \IF and the \ENDIF).
**** ZING ****
FORMAT: \ZING AXIS={X,Y or B} CORNERS=#,#,#,# FRAME=#
LOCATION=#,# MODE={B, F or X, A, O}
Displays all or a portion of a raster frame to the
active screen. ZING lets you display a single image
with more features than \SHOW or \RUN, but is
slower.
AXIS={X,Y or B}
The area to be shown can be flipped on either or
both (B) axis. This can be combined with all other
ZING options.
CORNERS=#,#,#,#
Specifies the upper left and lower right corners
within the frame to be displayed. The values are the
X-low, Y-low, X-high and Y-high dots.
FRAME=#
The frame to be \ZINGed onto the screen. Frame must
be a raster image. (Before release 7 the parameter
LOCATION was ignored if FRAME followed the LOCATION
parameter.)
LOCATION=#,#
Location is the upper left corner of the screen to
start placing the image. The base X- and Y- axis
values for the frame are added to the location
specified to determine the actual location.
MODE={X,A, O, B or F}
Mode puts this command in XOR mode (X), AND mode
(A), OR mode (O), "background" mode (B), or
"foreground" mode (F). The X, A, O, B, and F options
are exclusive: you may only use one of them at a
time (or none). Background means only the non-zero
dots will be moved, and only to pixels which are 0
on the screen. Foreground means again only the non-
zero dots will be moved, but they will be moved
regardless of what is on the screen.
In XOR mode the image to be placed on the screen is
XOR'ed with whatever is currently on the screen. In
both "foreground" and "background" modes only dots
in the foreground colors (color numbers greater than
color number 0) are transferred to the screen. In
background mode these dots are only transferred if
the current screen dot is the background color (0).
This allows objects to be placed in the foreground
or background of a current image.
**** * (asterisk) ****
FORMAT: \*
Any command that starts with \* is a comment and
does not affect processing. This command must be
the last or only command on the line. Anything
after it (until the CR/LF) will be ignored, even a \
(backslash).
EXAMPLES:
\* this paragraph shows horse gaits.
\READ TROT.PIC
\APPEND CANTER.PIC 1,9
\APPEND GALLOP.PIC 1,13
\APPEND PACE.PIC 1,12
\X NEXT_HORSE
\LOCATE 20,20
\DISPLAY "WHAT GAIT DO YOU WANT TO SEE?"
\CURSOR 10,5
\QUESTION #4,0
\IF #4 = 99
\END
\ENDIF
\IF #4 = 1
\* TROT
\SHOW 80,80,1,12
\ELSE
\IF #4 = 2
\* CANTER
\SHOW 80,80,13,21
\ELSE
\IF #4 = 3
\* GALLOP
\SHOW 80,80,22,34
\ELSE
\* PACE IF NOT 1-3 OR 99
\SHOW 80,80,35,46
\ENDIF
\JUMP NEXT_HORSE
**** " (double quote) ****
FORMAT: \"
The double quote mark allows you to display a blank
line on the screen in \CRAWL, \OVERLAY or \SCROLL
mode. It is preferable to creating a blank line in
the text file, which cannot be done anyway using the
built-in editor. The program will handle blank
lines if it encounters them (presumably created with
another text editor).
Any text appearing after the quote (") WILL BE
DISPLAYED. You can use this command to display any
text with a backslash (\) in the first column. For
this reason this command CANNOT have other commands
following it on the same line. They would be
treated as text. \ON KEY checking for this command
is the same as for text lines. The number of \ON
KEY checks that will occur during execution of this
command will depend on the height in dots of the
current font.
Just blank lines (13, 10) can be used after text
lines or after a \" command, but not after other
command lines. Therefore, use this command.
**** + ((plus sign) ****
FORMAT: \+
Indicates that no keyboard check is to occur between
command lines. This command is only valid as the
last command on a multiple-command line. Therefore
it is not compatible with \" and \* commands on the
same line. This command causes multiple command
lines to "behave" as though they were all on the
same line. No \ON KEY jumps will occur between
lines connected with \+ so you can guarantee that
several processes (commands) will all occur if the
first one occurs. If the line after the \+ command
is a text line (or a \" command line) \ON KEY or
keyboard checking will only be inhibited for the
first row or column (one dot high or wide).
This command is useful when setting up or turning
off multiple \ON KEY specifications. Also it can be
significantly faster, particularly if a mouse is
active, since calls to the mouse manufacturer's
software often take a noticeable amount of time.
\RUN Information Displays
This program can do very complex animation. You can
use combinations of windows, paths, masks, controlled
motion, xor and animation sequences to display raster or
vector pictures, or strings within vector pictures.
\SPRITE information remains set until either you
restart your text file (in the editor, from line 1) or use
\CLEAR SPRITES. For example if you enter a path for sprites
to follow all \SPRINT commands that are executed will be
assigned that path until you either reset to a new or no
path or execute \CLEAR SPRITES, which sets PATH equal to NO
(none).
The program uses over 140 bytes of data for each
\SPRINT'ed character. The program uses a "work area" to set
up the data. This area, called the sprite table, can be
viewed when running the editor when \RUN FACTS {#} is used.
Some data changes with each cycle. Viewing the data can
help you verify that what you want to occur in an animation
sequence is actually occurring--at least mathematically.
FACTS displays values including the current status of
all the parameters you set with \SPRITE. Also, such
information as the address of the sprite in RAM, the current
location, etc..
Most sprite values, including current location, are
"word" (2-byte) values. In the case of location this means
that the "virtual" location can be any value from 0 to 32767
and additionally from -32768 to -1 on each axis. The screen
only occupies a small portion of this range: for CGA 4-color
mode, positive numbers 0-319 on the X-axis and 0-199 on the
Y-axis with 0,0 being the upper left corner. If you scroll
a sprite far enough off the screen in any direction it will
reappear on the opposite edge. You can use the offscreen
area to "store" sprites that are active but not located on
the screen or to scroll sprites off the screen. If the
WINDOW= parameter has been entered for a sprite then the
"active" area is defined by the window rather than the
screen dimensions.
On the following pages is a listing of where the values
for each sprite are kept in the data area. The data can be
shown with the FACTS option of \RUN, when running the editor
version. First the program displays the image (if it is
supposed to) and then it displays the first screen of data,
which may overlay the sprite. Press any key except the HOME
key, the PG DN key, the arrow on the four (left arrow) and
the arrow on the six (right arrow) to advance to the next
sprite (NOT one cycle--unless you only have one sprite in
your table).
Information is displayed for each sprite whether
"active" or not. Press Pg Dn (the three key on the numeric
pad) to see beyond the first screen of data. Pressing it
repeatedly will put you past the current frame and on to the
next one, but it will NOT "wrap around" after the last
sprite-it will just show unrelated areas of memory that
follow the "sprite table". Byte values are displayed both
numerically and as a character if possible. If an ASCII
character cannot be displayed, a period (.) will appear in
the third column. If a word value is at the location to be
displayed only the first two columns are used.
Press the HOME key (the seven key on the numeric pad)
to return to the information at the beginning of the current
sprite. Press the left and right arrow keys (on the four
and the six) to see, respectively, the last and next
sprite's information.
Values at Sprite Table Addresses
Offset Type Meaning
0 Word Offset from RAM base address for this frame.
2 Word X-location of first dot.
4 Word Y-location of first dot.
6 Word X-location of last dot.
8 Word Y-location of last dot.
10 Word X-starting location.
12 Word Y-starting location.
14 Word X-current location.
16 Word Y-current location.
18 Word X-increment amount.
20 Word Y-increment amount.
22 Word picture size.
24 Word X-low ending position (adjusted by first dot
value).
26 Word Y-low ending position (adjusted by first dot
value).
28 Word Starting cycle.
30 Byte Type. R or anything else.
31 Byte Frame type byte.
32 Word Animation cycles limit plus three (3).
34 Word Animation current cycle (>1 is currently active).
36 Word Scroll horizontal recycle amount.
38 Word Scroll vertical recycle amount.
40 Byte Was this frame onscreen last cycle (n, y)?
41 Byte Is this an animation frame (A or not A)?
42 Word Ending Cycle.
44 Byte Does this frame follow a path (P)?
45 Byte Xor? (not capitalized--is a, o, x, or R for AUTO
REMOVE, or n or y).
46 Word Path offset of first dot.
48 Word Path offset of last dot.
50 Word Path offset of current dot.
52 Word Screen address of first byte for Auto-xor (X16).
54 Word Offset of first byte from 52 (Auto-xor).
56 Word RAM base address of frame (X16).
58 Word Frame number for this sprite.
60 Word Window lower-right X-value.
62 Word Window upper-left Y-value.
64 Word Window lower-right Y-value.
66 Word Starting vector string dot number position.
68 Word Ending vector string dot number position.
70 Word Address of path frame (X16).
72 Word Path frame number.
74 Word Window upper-left X-value.
76 Word Previous cycle X-location.
78 Word Previous cycle Y-location.
80 Word Add-amount for vector string starting dot.
82 Word Previous cycle starting position for string
display.
84 Word Add-amount for vector string ending dot.
86 Word Previous cycle ending position for string display.
88 Word Height of image to be Auto-XOR'ed off.
90 Word If raster, Auto-XOR bytes to skip (not shown).
If vector starting string dot address.
92 Word If raster, Auto-XOR source address of first byte.
If vector, ending address for string repeat.
94 Byte Auto-XOR bit mask for the left edge. (Raster.)
95 Byte Auto-XOR bit mask for the right edge (Raster.)
96 Byte Auto-XOR number of bits to shift image.(Raster.)
97 Byte Unused.
98 Word Address of last "active" dot (next-to-last dot).
100 Word X-high end window value (adjusted if vector).
102 Word Y-high end window value (adjusted if vector).
104 Byte Keep? (Y).
105 Byte Connect line segments? (Y) (Vector).
106 Byte Fast display? (Y) (Raster).
107 Byte Zing? (Y).
108 Word Zing offset address.
110 Word Zing base address.
112 Word X-location for Zing.
114 Word Y-location for Zing.
116 Word X-low increment for OPEN or WPATH current dot
address.
118 Word Y-low increment for OPEN or WPATH first dot
address.
120 Word X-high increment for OPEN or WPATH last dot
address.
122 Word Y-high increment for OPEN or WPATH base address.
124 Word WPATH path frame number.
126 Word WPATH X-width of window.
128 Word WPATH Y-width of window.
130 Word WPATH X base window location.
132 Word WPATH Y base window location.
134 Word ZING word width of image.
136 Word ZING dot width of image.
138 Word ZING dot height of image.
140 Word Auto-XOR bytes to show (raster).
142 Word Sprite ZING frame.
144 Byte Pattern-foreground mode (F) or not F.
145 Byte Not used. Reserved.
146 Word Sprite ZING bitplane size.
148 WORD Bitplane size.
Picture and Font File Formats
Picture and font files are designed with a "header
record" of at least 26 bytes followed by the data for the
frames themselves. Each picture frame has a sixteen-byte
frame header. Proportional fonts have a ten-byte header.
Standard fonts have no frame header at all.
The font file header is 26 bytes. The picture file
header is 26 bytes plus 2 bytes per frame. These additional
bytes hold the size of each frame: \APPEND reads this and
then calculates the locations in the file of the frames you
ask for. If the file is compressed, whether font or picture
format, the header will have an additional 2 bytes per frame
containing the frame's compressed size. A value greater
than or equal to the non-compressed size means the frame is
not compressed. Vector frames are not compressed.
The format of the 26-byte file header is as follows.
Bytes not used are reserved for future use.
Offset Type Meaning
0 Word Unsigned low-order word for the total size of this
file. If non-proportional font this is the frame
X width.
2 Word Unsigned high-order word for the total size of
this file. Always zero prior to release 6.00. If
non-proportional font this is the Y height.
4 Word Width in words of the last frame used.
6 Word Picture size of the last frame used.
8 Word Total frames in the file.
10 Byte Total number of "sectors" in the file. (This value
is not used after release 3.46).
11 Word Size of this header record.
13 Word Size of each frame header record.
15 Byte Bytes per dot for vector frames.
16-19 Bytes Release number of program that wrote the
file.
20 Byte Graphics mode the picture file is for. CGA is
represented by a 4 and is the only valid mode
before release 6.00.
21 Byte Compressed? ("h" before release 4.80, 0 (no) or 1
(yes) after.)
22 Byte Palette for this picture file.
23 Byte Background for this picture file.
24 Byte Dots per byte for raster images.
25 Byte Picture bitplanes.
The format of the frame header is as follows:
Offset Type Meaning
0 Word Width in dots (0=1 so one less than actual).
2 Word Height in dots (0=1 so one less than actual).
4 Word Width in words (dots per word depends on frame
resolution).
6 Word Picture size in bytes (less than approximately
64016).
8 Byte This is a bit-mapped field. The lowest (0th or
rightmost) bit is the image type, Vector (1) or
Raster (0). The next bit to the left is the mask
bit if raster. Next, a bit indicating whether the
mask was manually edited. (1 if it was, 0 if it
wasn't.) Next is a bit indicating whether the
frame is an onion skin frame (1) or not (0). Then
a bit
which is currently unused but reserved--set to 0.
Then, two
bits which are also currently not used except by
SCRNSAVE--
They indicate that the frame should be a
continuation frame
or a base frame. The low order bit is set to 1 if
a base frame and the high order of these two is
set to 0, then the
continuation frames are both 1's, then the LAST
continuation
frame is a 1 in the high order and a 0 in the low
order bit.
Lastly is a bit used in RAM, indicating that the
frame has
been changed in the editor. Normally this bit is
set to 0.
9 Byte Header size for the individual frames. (16 for
pictures, 10 for proportional fonts.)
10 Word Base X-location coordinate. (If picture file.)
12 Word Base Y-location coordinate. (If picture file.)
14 Word Base timing value. (If picture file.)
For a vector frame the total size is the number of dots
times the bytes per dot, plus the header. For a raster
frames with a mask the mask immediately follows the actual
frame data. Thus the frame size is the header, plus the
picture data size (calculated from the horizontal word value
and the vertical height), plus the mask if a mask exists
(same size as the picture data).
Raster images are normally compressed when written to
disk. The program calculates the bytes that can be saved (if
any) and if the value is significant it recommends
compression. You need not compress but the disk savings can
be substantial. Decompression usually takes less time than
reading the larger file so it is seldom desirable not to
compress if the program recommends it.
The compression format is a standard algorithm: If the
top two bits (high-order or left-most) of the first byte are
both ON (11xxxxxx) then the other six bits indicate the
number of bytes that the next byte is repeated. In CGA mode
each byte represents four dots.
The six bits that indicate the number of times that the
next byte is repeated is one less than the actual count.
The binary value 11000000 would indicate one byte of data
(use the following data byte one time) while 11000001 would
indicate two bytes that are the same.
If the top two bits are not both on then the byte is an
actual data byte. In this case the following byte would
then be checked to see if its top two bits are both on.
The header portion of each frame and the header for
the entire file are never compressed.
Format for the Auxiliary File
The auxiliary file has a 9 byte header and then the
individual auxboxes. Each auxbox also has a header
containing the number of the auxbox, it's type and length.
The last auxbox is always #32767 and contains the time and
date that the auxfile was written out to disk. This auxbox
must be included in the auxfile.
The format of the header record is as follows:
Offset Type Meaning:
0 Word Size in bytes of the auxfile.
2 Word Size of this header record (always 9).
4 Byte Not used in release 6.00. Set to 0.
5 Byte Major release number of program that wrote file.
6 Byte A period (.).
7 Byte Tenth's digit of minor release number.
8 Byte Hundredth's digit of minor release number.
The individual auxboxes are stored in the following
format:
Offset Type Meaning:
0 Word Number of this auxbox (auxboxes are always stored
in numerical order).
2 Byte Type of this auxbox. Either # or L in release
6.00.
3 Byte Size of this auxbox. For numeric auxboxes (type
#) this is always 2. For alphanumeric auxboxes,
it is the length of the data within the auxbox.
4 .... The data follows the 4-byte header info for each
auxbox. For numeric auxboxes (type #), this is a
signed binary word value. For alphanumeric
auxboxes it is the ASCII characters that are
stored.
Format for the Hue File
The hue file (extension .HUE) contains a sequence of
hue color definitions. It is specifically for a particular
screen mode, and it's maximum size is dependent on the
number of colors in that screen mode. The header contains
the "from" and "to" colors that the hue file contains.
The format of the header record is as follows:
Offset Type Meaning:
0 Word Size in bytes of the hue file.
2 Word Size of this header record (always 16).
4 Byte Not used (reserved). Set to 0.
5 Byte Major release number of program that wrote file.
6 Byte A period (.).
7 Byte Tenth's digit of minor release number.
8 Byte Hundredth's digit of minor release number.
9 Byte Screen mode this hue file is for.
10 Byte Dot mask for above screen mode (maximum color
number).
11 Byte Palette.
12 Byte Background color.
13 Byte Hue low-color.
14 Byte Hue high-color.
15 Byte Reserved. Set to 0.
The individual hues are stored in the following format:
Offset Type Meaning:
0 Byte Red component of color.
1 Byte Green component.
2 Byte Blue component.
Each component should be between 0 and 63. If any
value is greater than 63 that component value will be
ignored.
Space Considerations
When using RAM for pictures, this program uses space
for pictures "as needed." When a picture file is read all
previously allocated RAM memory is returned to DOS.
Whatever amount of memory is needed for the new file is then
requested from DOS. Whenever space is requested DOS
allocates an additional 16 bytes for it's own use. Also it
rounds the request for space up to the nearest 16 byte
boundary in RAM. The effect is simply that allocating
memory for a lot of frames at once is more efficient than
allocating one chunk at a time. When you \APPEND frames to
a picture file the frames that are to be appended will be
put in as few requests to DOS for space as possible, so you
may save a few bytes by appending all the frames you will
want at once. You also reduce disk access by not having to
access the file as frequently. When
creating/inserting/deleting frames in the picture editor the
program will return memory to DOS if possible, but if the
frame was part of a group of frames the memory will be
"lost" until a new picture file is read in, or until all of
the frames in that allocation block are deleted.
Since the program can use as much memory as DOS can
give it (up to 640K), it can take a long time to use up
memory in a "loaded" machine. If you start running into
errors whose explanation is that you have run out of memory,
try writing out your picture file and reading it back in
because any changes to the frame count may have wasted
space.
If EMM memory is available and it's use by the program
has not been inhibited though the use of startup variables,
the memory is always used in 16K (16384 byte) chunks called
pages. Again it is worthwhile to read as many frames at a
time as possible to conserve space.
Disk-based animation uses two 64K-byte areas to read
and decompress the frames.
You can use the startup variables to set the maximum
font size to the minimum,3K bytes, but then you may not be
able to read larger fonts into RAM. (For many screen modes
3K is not enough to read even a very small font.)
When the program initially loads the total amount of
RAM available for pictures is in variable "A" (in K), and
the amount of EMM (if any) is in variable "O" (in 16,384
byte "pages"). You can get some information about how much
is still available at any time using \MEMORY.
If you still can't get enough memory for the program to
run properly, there are several third-party software
packages such as QEMM from QUARTERDECK OFFICE SYSTEMS, Santa
Monica, CA, which will maximize RAM usage.
Tips On Making Your Program Faster
Text file design can have a significant effect on how
fast a program runs--or appears to run. There are many
things to consider. In order to make the program run fast
at the right times you might try reading disk files while
the user is looking at text or non-moving images on the
screen. If you set the text pause length to something other
than zero that pause occurs between each line (one dot high)
during display of text.
\ON KEY commands store the actual address in the text
or macro area that the keypress should bring you to and
therefore execute very rapidly--except for the "human
element" of course!
Variables can be evaluated a little faster than
auxboxes. Single-digit auxbox numbers (#1, #2, etc.) will
evaluate faster than named or high-number auxboxes.
Use \+ commands often. The keyboard and input device
check can take a noticeable amount of time, especially if a
mouse, joystick, or digitizer is active. Turning the input
device off when not in use can speed you program
significantly. Some mouse software (usually supplied with
the mouse) is notoriously slow.
\SHOW is generally faster than \RUN.
If raster frame widths are evenly divisible into word
boundaries they can be displayed especially fast. \SHOW
automatically places such frames on the screen at maximum
speed. Use \SPRITE FAST=YES to speed \RUN. Masked frames
are substantially slower than non-masked images.
The speed of animation is largely dependent on the size
of the pictures being shown. To increase the speed be sure
to use as small an image as possible for the portion being
animated.
For maximum speed set \CLOCK SPEED= to 1, which is
about 18.2 times per second. This will give very coarse
speed control but if that's okay, it will use less processor
time for the asynchronous clock interrupts because they will
occur less often than at the default (584 times per second)
or some other speed. The minimum is 18.2.
Uses of the "escape" key
The escape key performs many related functions. When a
text file is running in the editor version or at any time in
the runtime version ESCAPE allows you to end the execution
of the text file. In the runtime version this will return
you to DOS. In the editor version you are given the option
of single-stepping the file or you can return to the text
editor. The messages displayed are non-destructive of the
screen.
If you choose to restart the program nothing is
changed. Variable "B", which holds the last keystroke, will
NOT be changed and no \ON KEY jumps or calls will have
occurred. If you choose "single-step" in the editor the
program will pause for input before each line is executed.
Whatever key you press is treated as a regular keystroke.
To stop "single-step" mode press ESCAPE and do not select
single-step as the option.
In the editor ESCAPE lets you get out of text lines
unchanged or resets picture frames.
Functions that require answering additional prompts let
you use ESCAPE to leave the option unused. While
transferring between text and draw mode ESCAPE substitutes
the default answer (usually "Y").
In the editor version ESCAPE is for stopping, giving
up, changing your mind, backing out, etc.
F10-"Instant" commands & DOS functions
In the editor version function key 10 gives you access
to "instant" commands. Most commands such as \DRAW, \LINE
and so on are allowed. Since only one command will be
executed, commands that send you to different areas of the
program are not valid (\CALL, \JUMP, etc.). Invalid
commands will produce an error message. Certain "powerful"
commands such as \DELETE are also inhibited.
If you press F10 twice in a row you will get a choice
of DOS options including Rename a file, Copy a file, change
the current drive or path (P), Erase a file, check Space on
disk drives, take a directory of a drive, or execute a
second copy of COMMAND.COM. Copy, Directory, Erase and
Rename can all be stopped before execution by pressing
ESCAPE. Directory can also be stopped during execution with
ESCAPE.
When a directory is being displayed pressing any key
will freeze the display. Pressing another key will
continue. ? and * ("global" characters) are valid in file
names here. When all entries for the current directory have
been displayed the total number of files and the total bytes
used by those files are displayed.
The Copy function copies only one file at a time. The
name must be completely specified without "global"
characters (* and ?). (Asterisks (*) and question marks (?)
may be used in the output file name.) Drive and path
specifications may be included.
You can change both the current path and drive with
'P'.
For the COPY, DIRECTORY, and RENAME commands you can
specify ,H (Hidden) ,R (Read Only) and ,S (System) options.
This will set or search for these attributes. To include
these options separate them from the filename by a comma
with no intervening spaces. ,H ,R ,HRS and ,RH are all
valid. For input files and directory searches the ,H option
will allow the handling of "hidden" files, which normally
are not displayable or copyable. If these attributes are
not specified for output files they will not be applied
regardless of the input file's attributes.
Future Enhancements
This product continues to evolve. Your suggestions are
the most important input for future enhancements. Some
expected, or possible, future enhancements include:
Decimal numbers are certainly an important future
enhancement. The variables and default types of numeric
auxboxes will undoubtedly remain whole numbers between -32K
and +32K to maintain speed of operation.
Greater than 64K pictures. This is partially
implemented in the SCRNSAVE utility but then not used in the
main program in release 7.
Three-dimensional vector images, and object-oriented
images.
Better mouse cursors. (Mask capabilities for cursor
crosshairs.)
What would YOU like to see in future versions of this
program? Send a letter to the author! (S.A.S.E. preferred.)
All requests will be considered plus you'll get on the
company mailing list, useful for learning about additional
products that may be of interest to our users.
Of Mice and Joysticks and Digitizers
This program will use any of these devices for input
while drawing or for \MOUSE. Even if an input device is
active the eight cursor direction keys around the 5 key on
the numeric keypad can be used (on PC and XT type machines
the 5 key can also be used.) The numeric keys above the
QWERTY portion of the keyboard can also be used for faster
travel around the screen. If you have installed the mouse
software prior to loading this program it will utilize the
mouse automatically.
Only one input device can be "active" at a time, except
that the MOUSE and JOYSTICK can both be used together,
although this can require significant amounts of time
(overhead.)
The mouse uses Microsoft compatible software calls to
accomplish it's job. This software should be loaded before
loading this program. It can be loaded after processing
starts with \EXECUTE but shouldn't be. See your mouse
documentation for how to load your mouse "driver" software.
In the editor, you cannot initialize the mouse for the first
time if changes exist to any files in RAM. The following
example would load the mouse software named mouse.com from
drive "A":
\EXECUTE >A:MOUSE.COM
The entire name including the extension has to be
specified. Again, mouse software should be loaded first!
The reason it is not a good idea to load mouse software
from within this program is because mouse software is
usually "TSR" (Terminate, Stay Resident) software. Such
software will (probably) load in the first available spot in
memory and stay there. Thus it will probably divide your
computer memory into two chunks if loaded from within this
program (until you reboot).
Timing Considerations
This program utilizes the system clock at an enhanced
rate for most timed activities. This way the timings you
set will be approximately the same on any machine of any
speed. Not all functions are timed. Timing values of 0 and
-1 have special meaning. 0 (zero) means "as fast as
possible" and will run at different speeds on machines with
different speeds. -1 generally means "run forever" (or
until ESCAPE or "any key" is pressed).
The values you code for timing have different meanings
for different commands. Specifically those that are in
effect during user input are in seconds, and those that are
for animation and other graphics are in small fractions of a
second (approximately 584 "beats" per second). In the SPEED
parameter of \ROUNDS, and in \OVERLAY, \SCROLL and \WAIT NOW
a value of 584 would be about one second. For \WAIT RETURN
# and \WAIT LIMIT # the value coded refers to seconds to
wait. -1 is forever.
Remember two things about creating animation for a wide
range of machine speeds: First, when setting up artwork on
a fast machine remember to consider how it will look on a
slower machine. Second, if creating on a slow machine don't
forget that some things will go TOO FAST on a fast machine
unless you limit their speed with the various timing
controls. For example if a \ROUNDS # SPEED 10 value looks
good on a plain PC find out if \ROUNDS # SPEED 20 looks
exactly the same. If it does then on a fast machine the
action might be twice as fast! This is because you are
displaying something that can't be done (on a slow machine)
in less than 20 ticks of the timer (each tick is
approximately 1/584th of a second.)
The speed control values you choose should be the one's
you actually want. 0, which is "as fast as possible" may
look fine on a PC, but on an AT or 80386 type machine it may
be too fast.
Converting Images Between Screen Modes
Conversion is done by reading a picture of one mode
into the program while in another mode. You can specify the
mode to become in the P11FLAGS= SCREEN:#,#,# environmental
variable or on the command line as [SCREEN:#,#,#]. When
moving "down" in number of colors, you can chose the
"clipped" or "modulo" method. Clipped makes all colors
higher than the maximum color equal to the maximum color,
while modulo makes the highest+1=0, highest+2=1, and so on.
When converting, the new picture will, as the old one was in
it's screen mode, be on a byte boundary on the left edge.
Therefore, when going to a higher X-axis resolution, some
frames may not match up correctly with other frames and will
need to be manually adjusted afterwards.
Only frames up to screen size will be converted
completely. Vector frames will not be converted, so colors
may be unusual when moving "down" from more colors to less
colors.
Executing DOS from within the program
This feature gives you a lot of power, but can cost you
dearly if misused. It is best NEVER to use it when you have
changes in RAM, especially with earlier (2.X) versions of
DOS. You can do anything you have the memory (RAM)
available for. You can run any program, execute any DOS
command, format disks, etc. etc. etc.. There is NO limit--
you can even run a second copy of this program. (If it will
fit.)
From DOS, return to this program either by typing EXIT
at the DOS prompt or by having that word in a "BATCH" file
that DOS executes. You cannot execute a batch file without
loading the command processor so you must use the DOS>
option of \EXECUTE for batch files. You can also exit to a
second copy of the command processor by typing F10 (function
key 10) twice from the editor and then pressing "X" (EXIT).
When processing returns to this program it will reset
the screen mode if necessary. However if some other program
changed the palette and/or background, or the hues, the
program will not be aware of this change. If this command
fails variable "A" will normally contain -1 and variable "C"
may contain an error code.
The clock, which is speeded up to about 584 ticks per
second (or some other value you set with \CLOCK SPEED=), is
temporarily reset to normal for \EXECUTE.
Any program you run that destroys the current screen
memory area would also have destroyed your screen.
Therefore you may want to execute \CLEAR SCREEN immediately
upon return in those instances.
Although you can "theoretically" execute any program
with this command you should avoid certain types of programs
known as "TSR" (Terminate, Stay Resident) programs. When
loaded these programs usually take the next available chunk
of memory and remain there until you reboot. The result is
that when you return to this program, and evermore until you
reboot, you will have your memory divided into two pieces.
Keyboard enhancement programs are generally TSR programs, as
are most mouse utilities. They should be loaded BEFORE this
program.
The DOS command FORMAT may act much like a TSR program,
dividing memory if executed. FORMAT should not be used from
within this program unless you plan to reboot afterwards.
Of course, if your only other choice is to loose valuable
work, by all means format a disk, save your files, and
reboot!
About the Author
Version 1.0 of Russell Hoffman was released in August
of 1956. He has been involved with microcomputers since
1980. In 1984 he started writing P11 in response to a
client request for an interactive tutorial about the human
heart.
Prior to starting P11 he designed randomized computer
art programs that create two-dimensional artwork on digital
plotters. Each drawing is different from every other. He
claims they are examples of "imitation intelligence." By
using random numbers to vary the sizes, colors, and other
aspects of each drawing, an infinite artistic variation is
possible. The software concept behind this art is
applicable to engineering, physics, architecture, etc.. For
example, row-style housing developments need not all be the
same. Random variation-within-a-range can make it more
likely that a purchaser will find the exact house they want.
About 20,000 random art drawings have been created and
given away at computer trade shows throughout the Northeast
as of this writing. Completing this project required
writing an interactive drawing program (thus it was the
precursor to P11) for the NEC 8201-A (a lap-top computer
similar to the TANDY 100) as well as many display routines
for driving both the LCD display on the NEC and a PANASONIC
VP-6801 P30 six-pen plotter. This led to other assignments
creating artwork for various devices including monitors,
printers, plotters, lasers, oscilloscopes, LED-matrix, etc.
etc.
In his spare time (something he had a lot more of
before starting P11), Russell creates comedy radio routines,
which have been played on the Dr. Demento Show and elsewhere
(1979, 1986). He is an avid aviation buff and is learning
to fly a Cessna 172 Skyhawk, having soloed in 1988. He
likes ocean and lake swimming, reading, photography and loud
music. Also quiet music, dancing and chocolate. He likes
watching Jai Alai, listening to baseball, and playing
softball. It goes without saying that he likes playing
video games!
Over 200 of his commentaries, humorous essays and
letters have been published in and out (mostly out) of the
computer field. He lectures to computer user groups, as
many as 50 lectures/year.
He has several listings in various biographical titles
for his work, and is a member of the Boston Computer Society
and the Connecticut Computer Society. He is also a member
of the International Platform Association, WINGS fun club,
Debbie Gibson fan club, and The Demento Society.
Russ attended the Computer Processing Institute in
Bridgeport, CT. in 1980, Connecticut School Of Broadcasting
in Stratford, CT in 1979, County School of Tractor Trailer
Driving in Bridgeport in 1978, and Penn State University,
State College, PA in 1974. (P.S.U. was the only one he
didn't graduate from.) He attended (and graduated from)
Greens Farms Academy in Greens Farms, CT, where he first
made contact with a computer via a Teletype machine.
He has dabbled extensively in electronics but claims
that everything he builds either smokes, or shocks him, or
doesn't work.