





                   ------------------------------------------
                    RIPscrip Graphics Protocol Specification
                           "Remote Imaging Protocol"

                            Copyright (c) 1992-1994
                        TeleGrafix Communications, Inc.
                              All Rights Reserved

                                  REVISION 2.00
                                   REVISION A1

                             (proposed enhancements)

                               ===================
                               == CONFIDENTIAL! ==
                               ===================

                                 April 1st, 1994
                   ------------------------------------------

===================================================================== > v2.A1
==                    CHANGES IN THIS REVISION                     == > v2.A1
===================================================================== > v2.A1
                                                                      > v2.A1
     REVISION 2.A1                                                    > v2.A1
     -------------                                                    > v2.A1
                                                                      > v2.A1
     - Added the ability to embed raw UU-Encoded data blocks inside   > v2.A1
       RIPscrip encoded files.  This allows you to transmit bitmaps,  > v2.A1
       sound files, and other raw generic binary data over 7-bit      > v2.A1
       ASCII text connections (like Internet, CompuServe, etc).       > v2.A1
                                                                      > v2.A1
     - Added some extra text variables for the purpose of extended    > v2.A1
       vendor determination.  Variables for determining the name      > v2.A1
       of the manufacturer, name of the terminal program, actual      > v2.A1
       version number of the terminal, and arbitrary vendor specific  > v2.A1
       data have been supplied for the most flexibility.  This        > v2.A1
       method of determining vendor information is more generic       > v2.A1
       and easier to work with than the vendor-codes used in the      > v2.A1
       $RIPVER$ text variable and the Query RIPscrip version ANSI     > v2.A1
       command.  In effect, the old method of determining vendor      > v2.A1
       codes is obsolete.                                             > v2.A1
                                                                      > v2.A1
     - Added a new command for the creation and manipulation of       > v2.A1
       scroller-type user interface objects.  The reason this was     > v2.A1
       added was due to popular demand.  The command for this new     > v2.A1
       object is RIP_SCROLLER.  Using this command really involves    > v2.A1
       some custom programming on the host system to process the      > v2.A1
       selections of a scroller.  We added this so that there's a     > v2.A1
       standardized way of performing scroller operations in          > v2.A1
       RIPscrip.                                                      > v2.A1
                                                                      > v2.A1
     - Added the ability to refresh (redraw) any buttons that exist   > v2.A1
       in a particular button style slot number.  This lets you       > v2.A1
       draw a bunch of buttons, alter the button style, then refresh  > v2.A1
       the buttons thus altering their appearance (possibly           > v2.A1
       highlighting all buttons in a group by changing their          > v2.A1
       colors, etc).                                                  > v2.A1
                                                                      > v2.A1
     - Added a new command (RIP_SET_REFRESH) which allows the host    > v2.A1
       to define a refresh sequence that, when transmitted, will      > v2.A1
       instruct the host to refresh (redisplay) the current screen.   > v2.A1
       This is defined as a host definable sequence because every     > v2.A1
       host may be different in the ways it refreshes screens and     > v2.A1
       menus, and even different sub-sections of a host may use       > v2.A1
       different refresh methods.  Also, text variables for           > v2.A1
       disabling refresh expressions and to force a refresh           > v2.A1
       operation have been added to round out the refresh feature.    > v2.A1
                                                                      > v2.A1
     - Added a RIP_HEADER command which is used to both identify      > v2.A1
       the revision of RIPscrip code that follows and also to         > v2.A1
       allow for widespread flexibility in performing reset           > v2.A1
       operations at the beginning of scenes (above and beyond        > v2.A1
       the RIP_RESET_WINDOWS) command.                                > v2.A1
                                                                      > v2.A1

     - Extended the specification where simple graphical primitives   > v2.A1
       are concerned.  In 1.xx versions of RIPscrip, raster           > v2.A1
       operations for simple graphics primitives were limited to      > v2.A1
       COPY and XOR modes.  XOR was only available for simple line    > v2.A1
       based primitives, not for curves like circles, ovals, and      > v2.A1
       various pie slices.  In addition, filled-in areas were not     > v2.A1
       qualified for XOR operations.  In RIPscrip 2.0, these          > v2.A1
       limitations are being lifted.  XOR applies to all primitives.  > v2.A1
       In addition, line patterns and thicknesses are also allowed    > v2.A1
       for the various primitives.  Thickness limitations are no      > v2.A1
       longer constrained to 1 pixel or 3 pixel thicknesses either.   > v2.A1
       Bitmap operations offered raster operations of COPY, XOR,      > v2.A1
       NOT, OR and AND.  In RIPscrip 2.0, these operations are        > v2.A1
       available for all primitives now.                              > v2.A1
                                                                      > v2.A1
     - Added an extended font system to the specification.  This      > v2.A1
       provides for the original font systems covering pre-defined    > v2.A1
       font sizes for the default bit-mapped font and simple vector   > v2.A1
       fonts.  This new command provides the ability to draw text     > v2.A1
       in high qualith outline fonts like TrueType (tm).  See the     > v2.A1
       RIP_EXTENDED_FONT command for further details on this command. > v2.A1
                                                                      > v2.A1
     - Added a "local audio playback" text variable command.  This    > v2.A1
       is a variant on the local RIPscrip file playback command.      > v2.A1
       Since you cannot be certain solely from a filename or a        > v2.A1
       file extension if the file is truly a sound file, we have      > v2.A1
       introduced this command to perform sound playback from         > v2.A1
       within host commands or query expressions.                     > v2.A1
                                                                      > v2.A1
       NOTE:  Formal sound file and music file formats have not       > v2.A1
              been established yet for RIPscrip 2.0.  They will       > v2.A1
              be shortly.  This command was added into the spec       > v2.A1
              because its format isn't limited to whatever format     > v2.A1
              is finally chosen.                                      > v2.A1
                                                                      > v2.A1
     - Added a "local bitmap playback" text variable command so that  > v2.A1
       you can place icons on the screen from within a host command.  > v2.A1
                                                                      > v2.A1
     - Added a "local image playback" text variable command so that   > v2.A1
       you can add photo-quality compressed images onto the screen    > v2.A1
       from within a host command (eg, JPEG files).                   > v2.A1
                                                                      > v2.A1
     - Formally defined a convention for defining command block       > v2.A1
       groupings using a certain type of formatted RIPscrip comment.  > v2.A1
       This will be useful for paint programs when they wish to do    > v2.A1
       block copy and move operations of whole series of related      > v2.A1
       RIPscrip commands.                                             > v2.A1
                                                                      > v2.A1
     - Added rule #16 which defines exactly what should be done if    > v2.A1
       a RIPscrip command has too much information or too little.     > v2.A1
                                                                      > v2.A1
     - Documented what should happen if multiple viewports overlap    > v2.A1
       or if text windows overlap, or viewports and text windows      > v2.A1
       overlap.                                                       > v2.A1
                                                                      > v2.A1
     - Expanded the pop-up picklist feature to support up to 64       > v2.A1
       individual picklist entries instead of the previously defined  > v2.A1
       maximum limit of 20.                                           > v2.A1
                                                                      > v2.A1
     - Added a RIP_SET_MOUSE_CURSOR command which allows you to       > v2.A1
       alter the currently defined mouse cursor style.  This lets     > v2.A1
       you change the mouse cursor to something like an hourglass,    > v2.A1
       a pointer, cross-hairs, etc.                                   > v2.A1
                                                                      > v2.A1
     - Added a new command, RIP_BACK_COLOR.  This command             > v2.A1
       affects the fill operations.  When you set the fill style or   > v2.A1
       custom user-defined fill pattern, you specify the foreground   > v2.A1
       color for fill operations.  Use this command to set a          > v2.A1
       background color for the fills so you can do two-toned fill    > v2.A1
       operations.  This color may or may not be used for the drawing > v2.A1
       of dashed lines for the odd-dash spaces (see RIP_LINE_STYLE).  > v2.A1
                                                                      > v2.A1
     - The RIP_LINE_STYLE command has been altered to support the     > v2.A1
       ability to turn on or off background color drawing for odd     > v2.A1
       dash sequences.  Also, the line thickness parameter of this    > v2.A1
       command has been generalized so that it can support any        > v2.A1
       arbitrary line thickness other than 1 or 3 pixel wide          > v2.A1
       lines.                                                         > v2.A1
                                                                      > v2.A1

     - Added a RIP_SET_COORDINATE_SIZE command which allows the       > v2.A1
       alteration of X/Y parameter byte widths.  By default, all      > v2.A1
       X or Y coordinates are 2-byte MegaNums (or UltraNums in        > v2.A1
       2.0).  For situations where a world coordinate system gets     > v2.A1
       very large (greater than 4096 wide), then you will need to     > v2.A1
       increase the size of the coordinates.  This command allows     > v2.A1
       you to make these parameters say, 3 bytes wide, or 4 bytes     > v2.A1
       wide.  In practice, this command probably won't be used        > v2.A1
       much - not until we start seeing very high resolution          > v2.A1
       video devices.                                                 > v2.A1
                                                                      > v2.A1
     - Extensive enhancements have been added to text variables.      > v2.A1
       Specifically, text variable "parameters" have been allowed     > v2.A1
       to alter the functionality of text variables.  This applies    > v2.A1
       to built-in text variables and to user-defined text            > v2.A1
       variables.                                                     > v2.A1
                                                                      > v2.A1
     - Data Entry Form generation has been added to one of the types  > v2.A1
       of host command data types.  This is a special case of data    > v2.A1
       text variables.                                                > v2.A1
                                                                      > v2.A1
     - All SAVE and RESTORE type text variables now adhere to three   > v2.A1
       different mechanisms (up to 10 slots for saving, a slot-less   > v2.A1
       save area and push/pop stack like operations).  In prior       > v2.A1
       releases each type of save/restore had different mechanisms.   > v2.A1
       Now, a uniform methodology has been added which is fully       > v2.A1
       backward compatible and totally identical in nature for all    > v2.A1
       of the various save/restore data types (screen, mouse fields,  > v2.A1
       text windows and clipboards).                                  > v2.A1
                                                                      > v2.A1
     - Added a new mechanism to the save/restore areas that allows    > v2.A1
       slot-less and slot-based save regions to be protected.  A      > v2.A1
       protected slot cannot be erased, copied over or modified       > v2.A1
       by anything other than an unprotect operation or a hard        > v2.A1
       reset operation.  Push and pop operations skip over protected  > v2.A1
       slots.  Also, the ability to move data from slot-less areas    > v2.A1
       to particular slots, and vice versa have been added.           > v2.A1
                                                                      > v2.A1
     - Added protection facilities to viewport slots, text window     > v2.A1
       slots, clipboard page slots, graphical style slots and to      > v2.A1
       button style slots.  This allows you to protect an entry so    > v2.A1
       that nothing can overwrite or delete it short of a hard        > v2.A1
       reset operation or an unprotect command.                       > v2.A1
                                                                      > v2.A1
     - Button styles now have button style slots - up to 36 separate  > v2.A1
       button style slots can be defined simultaneously.  This can    > v2.A1
       reduce data transmission for heavy button applications.        > v2.A1
                                                                      > v2.A1
     - The RIP_ANIMATE command has been altered so that there is      > v2.A1
       only one animation channel instead of 36.                      > v2.A1
                                                                      > v2.A1
     - An enhanced load icon command has been added which supports    > v2.A1
       scaling and dithering.  This is intended to replace the older  > v2.A1
       RIP_LOAD_ICON command because it does the same thing, and much > v2.A1
       more!                                                          > v2.A1
                                                                      > v2.A1
     - Formally defined what a "clipboard" is under 2.0               > v2.A1
                                                                      > v2.A1
     - Officially defined the file format specification for 2.0 icon  > v2.A1
       bitmap files.  The official file format is BMP files (device   > v2.A1
       independent bitmaps).  See the end of this document for a      > v2.A1
       technical file format specification.                           > v2.A1
                                                                      > v2.A1

     - Altered the default palette in 256 color modes.  The new       > v2.A1
       palette is a uniform distribution of Red, Green and Blue       > v2.A1
       for purposes of image reproduction.  A uniform distribution    > v2.A1
       of RGB values provides colors in all parts of the spectrum     > v2.A1
       for as accurate image display as possible without color        > v2.A1
       palette changes.                                               > v2.A1
                                                                      > v2.A1
     - Added another syntax rule (#14) to the language definition.    > v2.A1
       This new rule covers the inability in previous releases to     > v2.A1
       use special command characters in text parameters in the       > v2.A1
       language (eg, "$", "[", etc).                                  > v2.A1
                                                                      > v2.A1
     - Added the ability to embed comments inside a RIPscrip file.    > v2.A1
       This is syntax rule #15.                                       > v2.A1
                                                                      > v2.A1
     - Cropping rectangles for the RIP_IMAGE_STYLE command have       > v2.A1
       been eliminated.  The complexity of cropping sub-area of the   > v2.A1
       image hamper the open development of RIPscrip for v2.0.        > v2.A1
       This may be changed in future versions.                        > v2.A1
                                                                      > v2.A1
     - Dynamic image pan/zoom operations have been eliminated from    > v2.A1
       this revision.  Since cropping rectangles are no longer part   > v2.A1
       of the specification, pan and zoom operations aren't really    > v2.A1
       necessary.                                                     > v2.A1
                                                                      > v2.A1
     - TIFF files have been removed from the 2.0 specification for    > v2.A1
       image file displaying.  We will be using JPEG and BMP files    > v2.A1
       exclusively for all bitmap image reproductions.                > v2.A1

     REVISION 2.A0                                                    > v2.A1
     -------------                                                    > v2.A1
     - Defined the resolution independent coordinate system nature of > v2.A1
       RIPscrip 2.0 (device coordinate frame, world coordinate frame  > v2.A1
       and local [viewport] coordinate frames).                       > v2.A1
                                                                      > v2.A1
     - Defined 24-bit color encoding vs. color palette coding         > v2.A1
       methods.                                                       > v2.A1
                                                                      > v2.A1
     - Defined 36 separate text window slots                          > v2.A1
                                                                      > v2.A1
     - Defined 36 separate graphical viewport slots                   > v2.A1
                                                                      > v2.A1
     - Defined 36 separate graphical drawing style slots              > v2.A1
                                                                      > v2.A1
     - Defined multiple clipboards                                    > v2.A1
                                                                      > v2.A1
     - Defined an animation command using multiple clipboard objects  > v2.A1
                                                                      > v2.A1
     - Added a Delay command                                          > v2.A1
                                                                      > v2.A1
     - Added a Baud Rate Emulation command for local RIP playback     > v2.A1
                                                                      > v2.A1
     - Enhanced the button style definitions to support some extra    > v2.A1
       display effect flags                                           > v2.A1
                                                                      > v2.A1
     - Enhanced the vector text font styles to support other text     > v2.A1
       font alignments (center, left, right, top, bottom)             > v2.A1
                                                                      > v2.A1
     - Defined default color palettes for various modes               > v2.A1
                                                                      > v2.A1
     - Defined rectangular fill operation rules for proper resolution > v2.A1
       independent viewing                                            > v2.A1
                                                                      > v2.A1
     - Added the ability to change the base math of parameters from   > v2.A1
       base 36 (meganums) to base 64 (ultranums).  This was so we     > v2.A1
       can accomodate larger numbers in the same space.               > v2.A1
                                                                      > v2.A1
     - Added ability to switch from one text window, viewport or      > v2.A1
       graphical drawing style to another.                            > v2.A1
                                                                      > v2.A1
     - Added another file transfer protocol to the                    > v2.A1
       RIP_ENTER_BLOCK_MODE command.  The new protocol is Zmodem      > v2.A1
       without crash recovery.                                        > v2.A1
                                                                      > v2.A1
     - Added facilities for display of JPEG photo-realistic images.   > v2.A1
                                                                      > v2.A1
     - Altered some of the RIP_ENTER_BLOCK_MODE dynamic modes.  Some  > v2.A1
       of the modes that were originally defined in v1.5x were not    > v2.A1
       defined well enough and were never used in the real world.     > v2.A1
       Those values have been recycled into more realistic uses.      > v2.A1




=====================================================================
==                           INTRODUCTION                          ==
=====================================================================

As system operators of many bulletin board systems, we've often
wished for some form of Graphical User Interface for our boards. Like
most Sysops, we've come across many solutions.  But they all seemed
to fall short in one way or another:  inadequate for THIS system,
incomplete, difficult to implement, too complex, or lacking in
graphics development tools.  In short, we became frustrated.

So, we decided to write our own Graphical Script Language.

RIPscrip stands for "Remote Imaging Protocol Script" language.  This
graphical language is our answer to the graphics needs of the BBS
community and has serious tools for implementation and practical use.

For more information on RIPaint, RIPdraw, RIPterm or RIPscrip
development tools (RIP2C, RIP2PAS, etc), contact:

     TeleGrafix Communications, Inc.
     16458 Bolsa Chica #15
     Huntington Beach, CA  92649

     VOICE: (714) 379-2131
     FAX  : (714) 379-2132
     BBS  : (714) 379-2133

     Internet:rip.support@telegrafix.com




=====================================================================
==                   USE OF THE RIPscrip LANGUAGE                  ==
=====================================================================

The RIPscrip language is made publicly available and is freely
licensed by TeleGrafix Communications, Inc.  By freely licensed, we
mean that the language can be used in the creation of other products.
It does not mean that RIPscrip is public domain.  TeleGrafix
maintains the copyright of the RIPscrip language.

RIPscrip, RIPaint, RIPdraw, and RIPterm are trademarks of TeleGrafix
Communications, Inc.  If you make a product that uses RIPscrip, you
must state in your program's "About Box" and documentation that this
product uses RIPscrip and the trademark statement.  You may not use
RIPterm, RIPaint, RIPdraw, or RIPterm in the name of your product.

If you have any questions regarding these issues, contact TeleGrafix
Communications, Inc. at (714) 379-2131.





=====================================================================
==                            DEFINITION                           ==
=====================================================================

RIPscrip is a text based Script language for displaying online
graphics.  The script language conforms to 7-bit ASCII, avoiding the
use of Extended ASCII characters.  This allows transmission over X.25
networks and other carriers that do not support full 8-bit binary
transfers easily.  RIPscrip allows RIPscrip graphical statements to
be mixed with printable ASCII text and [de facto standard]
ANSI/VT-100 directives.  RIPscrip can dynamically determine what is
graphics and what is text and display them appropriately in separate
windows (a graphics window and a text window).  And if you must have
your own proprietary commands, RIPscrip has room for that too.





=====================================================================
==                     HOW DOES RIPscrip WORK?                     ==
=====================================================================

RIPscrip uses a flexible, and very efficient script language for its
graphical statements.  Its efficiency stems from its compactness and
developmental planning.  It is entirely Object Oriented instead of
Raster Oriented for efficient transmission of data and powerful
editing capabilities (using RIPaint or RIPdraw for example).  The
language is open ended enough so that literally billions of different
graphics commands can be implemented as needed.  RIPscrip is not a
proprietary protocol standard, otherwise you wouldn't be reading this
document.  It is open to suggestion from the rest of the world.

Earlier Graphical Script Languages (Avatar and Skypix among others),
utilize special command characters to indicate which graphics command
is to be executed.  This allowed for their use on systems that are
limited to ASCII printable text.  Traditional script languages use
English words to accomplish things (eg, "BOX 0,0 100,50").  This kind
of thing is incredibly bulky, especially when you consider that
pictures are usually not simple things, but comprised of hundreds or
thousands of individual graphical operations (eg, lines, circles,
curves, text, etc.).  With this in mind, a human-readable script
language was completely inappropriate for the relatively limited
bandwidth of conventional modems.

So, one of our main strategies for this language was to make it as
efficient as possible without going completely binary.  This allows
the immediate installation of the protocol onto any ASCII text-based
host system -- because the language consists entirely of ASCII
printable characters.  We justify the unreadability of the language
by pointing out the limitations of today's modems and phone lines --
the language must be compact.




=====================================================================
==                    REVISION HISTORY NOTATION                    ==
=====================================================================

This document is a historical document.  Periodically throughout the  > v1.54
text are things that were added to the specification at specific      > v1.54
revisions.  These additions/changes can be easily pinpointed by       > v1.54
looking for notation symbols in the right margin of the document.  If > v1.54
you notice to the right of this paragraph are the symbols "> v1.54"   > v1.54
which indicate that this section was added in the v1.54 revision of   > v1.54
the RIPscrip Protocol Specification.  This notational convenience was > v1.54
added to make quick determination of new changes fast and easy.       > v1.54

THIS VERSION OF THE RIP 2.0 SPECIFICATION IS AN ONGOING CULMINATION   > v2.A0
OF THINGS AND IDEAS FROM MANY PEOPLE.  WITH THAT IN MIND, THERE ARE   > v2.A0
GOING TO BE NUMEROUS REVISIONS REVISIONS OF THE DOCUMENT, SO WE ARE   > v2.A0
USING A SPECIAL NOTATIONAL CONVENTION IN THE RIGHT MARGIN FOR THIS    > v2.A0
REVISION OF THE SPECIFICATION.  THE FIRST REVISION OF THE DOCUMENT    > v2.A0
WILL HAVE "v.2A0" TO INDICATE V2.0 REVISION A0 (ALPHA 0).  EACH       > v2.A0
SUB-REVISION OF THIS DOCUMENT WILL INCREMENT THE 0 TO A HIGHER        > v2.A0
VALUE.  IF WE GO BEYOND 9 (WE HOPE NOT), THEN WE'LL CHANGE "A" TO     > v2.A0
"B", AND SO ON, AND SO ON...                                          > v2.A0

===================================================================== > v2.A1
==             DIFFERENCES FROM 1.54 and 2.00 FORMATS              == > v2.A1
===================================================================== > v2.A1
                                                                      > v2.A1
In previous versions of RIPscrip, we used a simple Icon file format   > v2.A1
for its disk based bitmap icons.  In 2.00 we introduce a newer, more  > v2.A1
superior file format (the BMP/DIB file format).  This is a device     > v2.A1
independent bitmap format that accomodates monochrome images, 16      > v2.A1
color images, 256 color images and 24 bit images.  There is no real   > v2.A1
forms of compression internally but the capability for compression    > v2.A1
exists for future expandability.  The reason for changing file        > v2.A1
formats was a very important one because the older format did not     > v2.A1
have the built-in facilities for resolution and color palette         > v2.A1
independence.  This new format does.  We chose the BMP file format    > v2.A1
because it is truly a device independent bitmap format.  For details  > v2.A1
about the actual file format specification, see the end of this       > v2.A1
document.                                                             > v2.A1
                                                                      > v2.A1
Any place in the RIPscrip specification that used to refer to .ICN    > v2.A1
files now will use .BMP files.  Any 2.0 RIPscrip software should be   > v2.A1
intelligent with this change.  If it sees a .ICN file it should       > v2.A1
realize that it is the older format and translate the extension to    > v2.A1
.BMP instead.  How those packages deal with .ICN files may vary from  > v2.A1
vendor to vendor but the recommended solution would be to convert the > v2.A1
older .ICN to a 16 color .BMP file "on the fly".  Reallistically,     > v2.A1
when a 2.0 package is installed, some conversion utility should be    > v2.A1
run on the icon(s) at boot-up time to convert all the existing files  > v2.A1
to the new format.  Files that are received via RIP_ENTER_BLOCK_MODE  > v2.A1
should do dynamic file format conversion to the new format.  The      > v2.A1
older .ICN file format will no longer be supported in 2.0 and later   > v2.A1
revisions.                                                            > v2.A1

===================================================================== > v2.A1
==                   BACKWARD COMPATIBILITY TOPICS                 == > v2.A1
===================================================================== > v2.A1
                                                                      > v2.A1
With this release, XOR write modes now apply to all graphical         > v2.A1
primitives (also fill patterns).  Overall this shouldn't pose any     > v2.A1
problems for 99% of all RIPscrip 1.54 files out there, but there      > v2.A1
might be a few that are affected - if in RIPaint, you enable XOR      > v2.A1
write mode and do a couple lines and rectangles, then do a circle or  > v2.A1
filled rectangle, the circle or filled rectangle will be drawn in     > v2.A1
COPY mode even though XOR mode is active.  In a 2.0 terminal, this    > v2.A1
would cause the circles and filled in areas to be XOR'ed as well.  In > v2.A1
this regard, 2.0 is not 100.0% fully backward compatible.             > v2.A1
                                                                      > v2.A1
Also with this release, the world coordinate/resolution independent   > v2.A1
aspect of the language handles filled-in areas a bit differently (see > v2.A1
the world coordinate system section below).  Filled-rectangles don't  > v2.A1
fill all the way to the right or bottom borders of the rectangle -    > v2.A1
they are inset by one pixel from the right and up one line from the   > v2.A1
bottom.  The reasons for this are described in the world coordinate   > v2.A1
section of this document.  This can cause one pixel gaps in 1.54      > v2.A1
files that wouldn't happen in 2.0 related files.                      > v2.A1

===================================================================== > v2.A1
==              SLOT AREAS - A FUNDAMENTAL 2.0 CONCEPT             == > v2.A1
===================================================================== > v2.A1
                                                                      > v2.A1
RIPscrip 2.0 introduces is different from its previous versions       > v2.A1
architecturally on a number of levels.  One of the key fundamental    > v2.A1
differences is the introduction of slot areas.  A slot area is a      > v2.A1
combination of 36 separately definable data elements, each of which   > v2.A1
is considered a unique slot entry.  Slot entries can all be defined   > v2.A1
differently.  There are a number of different types of slot groups,   > v2.A1
each having a different purpose.  Fundamentally though, their concept > v2.A1
is similar.  Generally, only one slot in a slot group can be active   > v2.A1
at any one time.  This means that when operations are performed that  > v2.A1
refer to data in a slot group, they pull their data from the active   > v2.A1
slot.                                                                 > v2.A1
                                                                      > v2.A1
Data can be moved from one slot entry to another (in effect, making a > v2.A1
copy of one slot to another).  Also, slot entries can be protected so > v2.A1
that the contents of a particular slot cannot be modified or deleted  > v2.A1
until either an unprotect slot function is executed, or a hard reset  > v2.A1
is performed (a hard reset completely resets the entire RIPscrip      > v2.A1
environment to ground zero).                                          > v2.A1
                                                                      > v2.A1
There are five different slot groups for general data storage.  They  > v2.A1
are: graphical style slots, viewport slots, text window slots,        > v2.A1
clipboard page slots and button style slots.  There are also data     > v2.A1
save slot areas and data save slot-less areas, but these are not the  > v2.A1
same as normal data slots.  These special save areas are for          > v2.A1
temporary data backup purposes and are discussed in a section         > v2.A1
entitled "SAVE/RESTORE TEXT VARIABLES:  SLOTS" near the end of this   > v2.A1
document.                                                             > v2.A1
                                                                      > v2.A1
The five general data slot groups are described in more detail as     > v2.A1
follows:                                                              > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
GRAPHICAL STYLE SLOTS                                                 > v2.A1
---------------------                                                 > v2.A1
There are 36 separate graphical style slot.  Initially, slot number 0 > v2.A1
is active and is initialized to default values.  A graphical style    > v2.A1
slot defines a number of currently active graphical attributes.  A    > v2.A1
graphical style slot defines the following values (each slot has all  > v2.A1
of these attributes):                                                 > v2.A1
                                                                      > v2.A1
     - Current drawing color                                          > v2.A1
     - Current background drawing color                               > v2.A1
     - Current fill pattern number (or user-defined fill pattern)     > v2.A1
     - Current fill color                                             > v2.A1
     - Current line pattern number (or user-defined line pattern)     > v2.A1
     - Line pattern odd drawing rule (see RIP_LINE_STYLE)             > v2.A1
     - Current mouse cursor style number                              > v2.A1
     - Current font number (or font name for extended fonts)          > v2.A1
     - Current font size, orientation and horizontal/vertical         > v2.A1
       alignment                                                      > v2.A1
     - Current write mode (raster/transfer operation)                 > v2.A1
     - Current color mode (palette or direct RGB)                     > v2.A1
     - Current X/Y location (used with RIP_TEXT commands)             > v2.A1
     - Current image mode settings (see RIP_IMAGE_STYLE)              > v2.A1
                                                                      > v2.A1

With the ability of having multiple graphical style slots defined     > v2.A1
simultaneously, you can setup an entire graphical environment, then   > v2.A1
with a single command, switch to a completely different configuration > v2.A1
in only a couple of bytes of RIPscrip code.  This can greatly reduce  > v2.A1
the amount of RIPscrip code that needs to be transmitted after the    > v2.A1
style slots are initially setup.  See below under Protected Data      > v2.A1
Slots for even more powerful aspects of the slot system.              > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
VIEWPORT SLOTS                                                        > v2.A1
--------------                                                        > v2.A1
Each viewport slot contains a definition for a complete viewport      > v2.A1
configuration.  A viewport is simply a graphical window on the        > v2.A1
screen.  Any general graphical drawing operation (simple primitives,  > v2.A1
buttons, clipboards, etc) are drawn into the current graphical        > v2.A1
viewport.  If a portion of the graphical object would extend beyond   > v2.A1
the confines of the viewport, the portion outside the viewport is     > v2.A1
discarded, showing only what was inside the viewport.  A viewport can > v2.A1
also be disabled, which means that any graphical operation is ignored > v2.A1
while the current viewport is disabled.                               > v2.A1
                                                                      > v2.A1
Initially, viewort 0 is the current viewport and it is set to be      > v2.A1
full-screen.                                                          > v2.A1
                                                                      > v2.A1
A complete viewport definition simply defines the upper-left corner   > v2.A1
of the viewport and the lower right corner of the viewport (specified > v2.A1
in world coordinates).  Also, local viewport coordinate frame sizes   > v2.A1
are stored as part of the viewport definition (this is a local        > v2.A1
viewport coordinate system).  All of this information is saved in a   > v2.A1
single viewport slot.                                                 > v2.A1
                                                                      > v2.A1
Having multiple viewport slots allows you to quickly switch from one  > v2.A1
graphical window viewport to another with a simple, short command.    > v2.A1
This can facilitate multiple graphical windows fairly easily.  See    > v2.A1
below under Protected Data Slots for even more powerful features with > v2.A1
the slot system.                                                      > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
TEXT WINDOW SLOTS                                                     > v2.A1
-----------------                                                     > v2.A1
A text window is simply a region on the screen where raw,             > v2.A1
non-RIPscrip text is routed once it is received from the host.        > v2.A1
Initially, the text window is full screen, using the MicroANSI font   > v2.A1
#2 (80x25).  This is different than previous versions of RIPscrip in  > v2.A1
that the initial setting was full screen using font #0 which          > v2.A1
corresponds to an 80x43 text configuration.  80x25 is more            > v2.A1
aesthetically pleasing to the most people so it was made the default  > v2.A1
font configuration.                                                   > v2.A1
                                                                      > v2.A1
A text window typically supports ANSI screen control codes to support > v2.A1
foreground and background colors, and other formatting options.  This > v2.A1
information is all part of a text window.  Each text window slot      > v2.A1
stores a number of pieces of information that define what a text      > v2.A1
window is.  The information stored in each text window slot is as     > v2.A1
follows:                                                              > v2.A1
                                                                      > v2.A1

     - The upper-left and lower-right corner definitions for the      > v2.A1
       text window (coordinates are in text coordinates, not          > v2.A1
       graphical screen coordinates).                                 > v2.A1
     - The MicroANSI screen font number for the given window.         > v2.A1
     - The current ANSI color attributes                              > v2.A1
     - The current cursor X/Y location                                > v2.A1
     - The status of the cursor (is it on or off)                     > v2.A1
     - The current vertical scrolling margins (ANSI formatting)       > v2.A1
                                                                      > v2.A1
A text window can also be disabled.  If the current text window slot  > v2.A1
is disabled then any raw text that is received by the host will be    > v2.A1
discarded (ie, not shown on screen at all).                           > v2.A1
                                                                      > v2.A1
Having multiple defined text windows allows you to quickly switch     > v2.A1
from one text window configuration to another without having to lose  > v2.A1
any previously used information (color, location, cursor, etc).  Note > v2.A1
that the text contained inside the current text window is not stored  > v2.A1
as part of the text window definition - only the window's raw         > v2.A1
definition is preserved.                                              > v2.A1
                                                                      > v2.A1
Refer below to the section on Protected Data Slots for more powerful  > v2.A1
insights into the data slot system.                                   > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
CLIPBOARD PAGE SLOTS                                                  > v2.A1
--------------------                                                  > v2.A1
Clipboard page slots are similar in nature to the previous data       > v2.A1
slots, but are different in a fundamental way.  There is no such      > v2.A1
thing as a current clipboard data slot (page).  We interchangably use > v2.A1
the term "clipboard slot" and "clipboard page" because technically a  > v2.A1
clipboard page is actually a slot in the data slot system.  The       > v2.A1
concept of a clipboard page though lends itself to the idea that you  > v2.A1
can have different images on each "page".  Bear this in mind when     > v2.A1
these terms are used interchangably.                                  > v2.A1
                                                                      > v2.A1
The entire clipboard data slot area is a region of memory large       > v2.A1
enough to store one full-screen graphical image.  This memory area    > v2.A1
may be sub-divided into multiple clipboard pages (up to 36 maximum).  > v2.A1
All 36 clipboard pages may contain separate images.  All combined,    > v2.A1
they must add up to a byte-size memory storage equal to or less than  > v2.A1
the requirements to store an entire graphical screen.                 > v2.A1
                                                                      > v2.A1
With this in mind, it is quite possible to attempt to store a piece   > v2.A1
of information onto a clipboard page only to find that there is       > v2.A1
insufficient memory for the operation.  To determine if a clipboard   > v2.A1
image can be saved successfully, you would use the $CLIPSAVEOK$ text  > v2.A1
variable to ask the terminal if it can store the image onto the       > v2.A1
clipboard page successfully.  This text variable is useful to         > v2.A1
determine if enough memory exists to perform the operation.           > v2.A1
                                                                      > v2.A1
Clipboard pages can be cleared (erased) as well.  When a page is      > v2.A1
cleared, its memory is released so that it can be used for subsequent > v2.A1
clipboard storage operations.                                         > v2.A1
                                                                      > v2.A1
Clipboard pages do not need to be used sequentially.  For example,    > v2.A1
clipboard pages 0, 10 and 20 could all contain data and none of the   > v2.A1
others could be in use.                                               > v2.A1
                                                                      > v2.A1
The internal structure of the clipboard system is unimportant to the  > v2.A1
end-user of a RIPscrip system, even to the graphic artist designing   > v2.A1
screens.  Some implementation details should be discussed here though > v2.A1
to alleviate some technical implementation concerns.                  > v2.A1
                                                                      > v2.A1

If an attempt is made to store an image onto a clipboard page and     > v2.A1
there isn't a continguous area of memory inside the entire clipboard  > v2.A1
memory block that can satisfy the request, the terminal should check  > v2.A1
to see if all the unallocated regions in the clipboard memory region  > v2.A1
added together can satisfy the request.  If the request can be        > v2.A1
satisfied by a combination of smaller blocks, then the internal       > v2.A1
memory blocks comprising the already allocated blocks and the         > v2.A1
unallocated blocks are re-organized so that the necessary free blocks > v2.A1
are made adjacent in memory so the request can be finally satisfied.  > v2.A1
                                                                      > v2.A1
See the section below on Protected Data Slots for some powerful       > v2.A1
aspects of the slot system.                                           > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
BUTTON STYLE SLOTS                                                    > v2.A1
------------------                                                    > v2.A1
Button style slots contain a complete button style definition as      > v2.A1
defined by a RIP_BUTTON_STYLE command.  This RIPscrip command has a   > v2.A1
parameter to specify which button style slot is to contain the newly  > v2.A1
defined button style.  The RIPscrip command RIP_BUTTON_STYLE also has > v2.A1
a parameter to specify which button style slot is to be used for the  > v2.A1
button definition.                                                    > v2.A1
                                                                      > v2.A1
Having multiple button style slots defined at the same time allows    > v2.A1
you to have many commonly used button styles defined at once, so that > v2.A1
you can simply reference an already defined button style rather than  > v2.A1
having to transmit a rather length button style command each and      > v2.A1
every time you wish to define a button.                               > v2.A1
                                                                      > v2.A1
See the next section on Protected Data Slots for some powerful        > v2.A1
aspects of the slot system.                                           > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
===================================================================== > v2.A1
==                   PROTECTED DATA SLOT ENTRIES                   == > v2.A1
===================================================================== > v2.A1
                                                                      > v2.A1
Data slots by themselves have quite a bit of usefulness in short-term > v2.A1
situations where a lot of different configurations need to be         > v2.A1
switched between fairly often.  Their usefulness becomes even more    > v2.A1
powerful with the concept of protected data slots.  A protected slot  > v2.A1
is one that cannot be cleared by a normal reset operation or a clear  > v2.A1
slot operation until the slot is unprotected, or until a "hard reset" > v2.A1
operation is performed.                                               > v2.A1
                                                                      > v2.A1
A "hard reset" is a complete reset of the RIPscrip environment.       > v2.A1
Typically, a hard reset should only be performed immediately after    > v2.A1
connection to a RIPscrip compatible host system to clear the slate so > v2.A1
to speak.  Other uses for a hard reset are when the RIPscrip          > v2.A1
environment is hopelessly corrupted due to line noise, or when a      > v2.A1
complete re-synchronization of the enviornment is about to commence.  > v2.A1
                                                                      > v2.A1

Protected slots become quite powerful when you look at a larger       > v2.A1
host system.  For example, let's say that throughout your system you  > v2.A1
use five different graphical style configurations all over the place, > v2.A1
all of which require quite a bit of transmitted RIPscrip code.  If    > v2.A1
you define each of these styles as separate slots and then protect    > v2.A1
them, you don't need to re-transmit those blocks of data again unless > v2.A1
a hard reset operation is performed!  This can mean quite a bit of    > v2.A1
saved data transmission, and consequently faster transmission times.  > v2.A1
The same concept applies to text windows, viewports, button styles,   > v2.A1
and clipboard pages.  When taken from a system-wide perspective,      > v2.A1
where many sections of the system may be made by other manufacturers  > v2.A1
(eg, doors, BBS modules, etc), you may not be able to count on        > v2.A1
whether a section of the system uses one style or another, or does    > v2.A1
one kind of reset or another.  Having protected slots gives you the   > v2.A1
ability to protect your data configurations so that these             > v2.A1
sub-sections do not destroy your data.  When you return from the      > v2.A1
sub-section, simply re-activate your slot configuration(s) and away   > v2.A1
you go.                                                               > v2.A1




===================================================================== > v2.A0
==                     WORLD COORDINATE SYSTEMS                    == > v2.A0
===================================================================== > v2.A0
                                                                      > v2.A0
Starting with the v2.0 specification of RIPscrip, we have introduced  > v2.A0
a "world coordinate system".  This means that you can alter the base  > v2.A0
coordinate system used to address the video's physical device         > v2.A0
coordinate system.  This is the first step in achieving device        > v2.A0
independence.  Each coordinate system is called a "Coordinate Frame". > v2.A0
There are actually three distinct levels of coordinate systems.  From > v2.A0
the lowest (least abstract) to the highest level (the drawing board)  > v2.A0
you have the following coordinate systems:                            > v2.A0
                                                                      > v2.A0
     1) DEVICE COORDINATE FRAME - the resolution of the actual        > v2.A0
        display device.  This is not determined as part of the        > v2.A0
        RIPscrip language itself, it is actually determined by        > v2.A0
        the terminal - based upon whatever type of video              > v2.A0
        hardware is present (and what mode the user has chosen).      > v2.A0
                                                                      > v2.A0
     2) WORLD COORDINATE FRAME - This is the master coordinate        > v2.A0
        system.  This is the global set of coordinates.  Ideally,     > v2.A0
        it should be higher in dimensions than the Device Frame       > v2.A0
        so that you do not lose resolution when "mapping"             > v2.A0
        X/Y coordinates from the world coordinate system to the       > v2.A0
        device coordinate system.  If the dimensions of the           > v2.A0
        World Frame are the same as the Device Frame then the         > v2.A0
        mapping operation between World and Device Frames are         > v2.A0
        identical and can be skipped entirely since an X/Y            > v2.A0
        coordinate in the World Frame directly corresponds to         > v2.A0
        a pixel location in the Device Frame.                         > v2.A0
                                                                      > v2.A0
     3) DRAWING/LOGICAL COORDINATE FRAME - This is the actual         > v2.A0
        coordinate system that is used for the drawing surface.       > v2.A0
        The dimensions of the Drawing Frame govern the                > v2.A0
        resolution of graphics primitives that are actually           > v2.A0
        rendered on the Device Frame.  The Drawing Frame              > v2.A0
        loosely corresponds to the concept of the RIPscrip            > v2.A0
        RIP_VIEWPORT command which allows you to define a             > v2.A0
        drawing "sub-region" on the actual screen.  A Drawing         > v2.A0
        Frame can be full-screen (in the World Coordinate Frame)      > v2.A0
        or can be a sub-section of the screen which would             > v2.A0
        correspond conceptually to a drawing Window.                  > v2.A0
                                                                      > v2.A0
        There can be multiple Drawing Frames defined at the           > v2.A0
        same time, but only one of them can be the active             > v2.A0
        Drawing Frame at any given moment.  You may have up           > v2.A0
        to 36 different Frames defined (0-9, A-Z).  You may           > v2.A0
        easily switch between defined Drawing Frames with the         > v2.A0
        RIP_SWITCH_FRAME command which specifies which Frame          > v2.A0
        to switch to.  If you are switching to a Frame that           > v2.A0
        hasn't been defined yet, then the coordinates from            > v2.A0
        the current Drawing Frame are "copied" to the new             > v2.A0
        Frame and used verbatim (creating a duplicate Drawing         > v2.A0
        Frame overlapping the first one).                             > v2.A0
                                                                      > v2.A0
        If two or more Drawing Frames overlap, then whatever          > v2.A0
        was drawn "behind" one of the Frames is lost.  The            > v2.A0
        only exception to this is when you use a Button command       > v2.A0
        where the act of clicking on the Hot Mouse Region will        > v2.A0
        refresh the image of the button, thus restoring its           > v2.A0
        image to what it was before it was drawn over.                > v2.A0
                                                                      > v2.A0

Since versions of the RIPscrip specification prior to v2.0 were based > v2.A0
on a 640x350 resolution without any World Frame, a suitable set of    > v2.A0
defaults need to be assumed for the World Frame and the Logical       > v2.A0
Frame.  The World Frame would be set to a dimension of 640 across and > v2.A0
350 high.  The Drawing Frame would have its coordinates on a 1:1      > v2.A0
ratio with the World Frame, thus making a pixel location in the       > v2.A0
Drawing Frame correspond directly to a pixel in the World Frame       > v2.A0
without any kind of scaling being required.  The offsets for any      > v2.A0
Viewport commands would be in World Coordinates in the 640x350        > v2.A0
drawing space used in the pre-2.0 specification.                      > v2.A0





===================================================================== > v2.A0
==           THE MATHEMATICS OF GRAPHICS AND COORDINATES           == > v2.A0
===================================================================== > v2.A0
                                                                      > v2.A0
Mathematics, unlike graphics, is abstract in nature.  Graphics on the > v2.A0
other hand, is very discrete in nature.  A pixel in graphics is the   > v2.A0
smallest displayable element (Picture Element) on a graphics screen.  > v2.A0
The corresponding concept in mathematics is a single point.  A pixel  > v2.A0
has a discrete size and shape in graphics whereas in mathematics, a   > v2.A0
point is infinitely small and occupies no physical space in the       > v2.A0
cartesian coordinate system in which it exists.                       > v2.A0
                                                                      > v2.A0
In graphics we use the concept of coordinates and points to specify   > v2.A0
where a pixel is located.  If graphics were like mathematics where a  > v2.A0
pixel was infinitely small, a graphics monitor wouldn't show anything > v2.A0
other than black because a pixel would be infinitely small surrounded > v2.A0
by blackness.  But this is not the case.  Graphics hardware has to    > v2.A0
have pixels defined as discrete areas of the screen - addressable     > v2.A0
areas of the screen that can be set to a particular color.  This is   > v2.A0
how we see things on the screen, as individual pixels of data used    > v2.A0
together to represent some kind of image.                             > v2.A0
                                                                      > v2.A0
Just like the point in mathematics, a line is infinitely thin, but    > v2.A0
has length.  A line is composed of an infinite number of points       > v2.A0
between the beginning and ending locations of the line.               > v2.A0
                                                                      > v2.A0
Relating these two distinctly different concepts to each other though > v2.A0
doesn't always lend itself to a simple situation to understand.  On   > v2.A0
the surface, a pixel's coordinate location appears to be the same     > v2.A0
thing as it is in mathematics.  But, when you get into deeper issues  > v2.A0
of graphics theory this isn't truly the case because of the           > v2.A0
difference in sizes of a point compared to a pixel.  In math, points  > v2.A0
don't have to be on even integer boundaries - they can be fractional. > v2.A0
A point can be at (2.53,1.295), whereas in graphics, a pixel cannot   > v2.A0
be at a fractional location - there's no such thing as a part of a    > v2.A0
pixel!                                                                > v2.A0
                                                                      > v2.A0
A graphics screen is designed so that every pixel location on the     > v2.A0
screen has a unique location specified (in human terms) as an X/Y     > v2.A0
coordinate pair.  This is called the Cartesian Coordinate System.  It > v2.A0
is by far one of the easiest ways of representing a coordinate in a   > v2.A0
two-dimensional world like a monitor.  If you zoom in closely on a    > v2.A0
monitor and look at the layout of pixels and their relationships to   > v2.A0
coordinates, you might see something like this:                       > v2.A0
                                                                      > v2.A0

                          (X DIMENSION)                               > v2.A0
                                                                      > v2.A0
                             1 1 1 1 1 1 1 1 1 1 2 2 2 2              > v2.A0
         0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3              > v2.A0
        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+             > v2.A0
       0| | | | | | | | | | | | | | | | | | | | | | | | |             > v2.A0
        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+             > v2.A0
       1| | | | | | | | | | | | | | | | | | | | | | | | |             > v2.A0
        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+             > v2.A0
  Y    2| | | | | | | | | | | |#|#| | | | | | | | | | | |             > v2.A0
        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+             > v2.A0
  D    3| | | | | | | | | | | |#|#| | | | | | | | | | | |             > v2.A0
  I     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+             > v2.A0
  M    4| | | | | | | | | | | | | | | | | | | | | | | | |             > v2.A0
  E     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+             > v2.A0
  N    5| | | | | | | | | | | | | | | | | | | | | | | | |             > v2.A0
  S     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+             > v2.A0
  I    6| | | | | | | | | | | | | | | | | | | | | | | | |             > v2.A0
  O     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+             > v2.A0
  N    7| | | | | | | | | | | | | | | | | | | | | | | | |             > v2.A0
        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+             > v2.A0
       8| | | | | | | | | | | | | | | | | | | | | | | | |             > v2.A0
        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+             > v2.A0
       9| | | | | | | | | | | | | | | | | | | | | | | | |             > v2.A0
        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+             > v2.A0
                                                                      > v2.A0
If you look at the previous diagram, you can see that there is a grid > v2.A0
of pixels that is 24 pixels wide (the X direction) and 10 pixels high > v2.A0
(the Y direction).  Each of the dark squares is a black pixel.  The   > v2.A0
pixels that are white (containing a "#") are considered white pixels. > v2.A0
There are four pixels that are ON in this diagram, at locations       > v2.A0
(11,2), (12,2), (11,3) and (12,3).  This is how graphics hardware     > v2.A0
addresses graphics pixels, by specifying an X/Y coordinate location   > v2.A0
for a pixel to turn it on or off (or more generally, to set it to a   > v2.A0
particular color).                                                    > v2.A0
                                                                      > v2.A0
If you look closely at the locations of the coordinates in the        > v2.A0
previous diagram, the X/Y coordinates address the physical pixel      > v2.A0
cells themselves.  Each pixel cell is separated by infinitely thin    > v2.A0
lines - the pixel cells' borders so to speak.  Now, each pixel is     > v2.A0
physically adjacent to the ones next to it and there are no gaps      > v2.A0
between them.  This is the way graphics hardware works.               > v2.A0
                                                                      > v2.A0
Now that we've described the way graphics hardware addresses pixel    > v2.A0
locations, let's look at why it's not really the best way of          > v2.A0
describing graphics mathematically.  For the hardware, this is the    > v2.A0
best way of handling things, but mathematically, it's not.            > v2.A0
                                                                      > v2.A0
The world of graphics hardware has many different facets.  One        > v2.A0
graphics display device can often times display graphics at different > v2.A0
resolutions.  A typical video card on the IBM-PC can display graphics > v2.A0
at 320x200, 640x350, 640x400, 640x480, 800x600, 1024x768 and even as  > v2.A0
high as 1280x1024 and higher.  That's quite a bit of difference in    > v2.A0
pixel grids (like the one shown earlier).  Not only can the number of > v2.A0
pixels change horizontally and vertically, but when the resolutions   > v2.A0
get higher, the pixels get smaller and harder to see.  When graphics  > v2.A0
hardware can achieve a resolution of infinity by infinity, then we    > v2.A0
will have achieved perfect sight (like what we see around us).  But   > v2.A0
obviously, this will probably never happen in our lifetimes (or our   > v2.A0
great granchildren's for that matter).                                > v2.A0
                                                                      > v2.A0

What would happen if you had a line drawn on a graphics screen from   > v2.A0
coordinates (0,0) to (639,349) at 640x350 resolution?  You would      > v2.A0
have a nice little line on the screen that stretches from the upper-  > v2.A0
left corner to the lower-right corner.  Now, if you drew the same     > v2.A0
line at 800x600 resolution?  Your line would no longer go all the way > v2.A0
to the bottom of the screen or to the far right of the screen.  It    > v2.A0
would stop about 2/3'rds of the way down and over.                    > v2.A0
                                                                      > v2.A0
The problems start to come up with mathematics and graphical          > v2.A0
representations when we try to make something look the same at one    > v2.A0
resolution as it does in another (resolution independence).  Sure     > v2.A0
you can translate a coordinate in one resolution to some other        > v2.A0
coordinate in a different resolution.  All you need to know are the   > v2.A0
dimensions of each resolution and a bit of algebra.  But pixels       > v2.A0
aren't the same thickness!  The line described previously could still > v2.A0
be drawn properly to the lower-right of the screen, but it would      > v2.A0
appear a lot thinner.  You could try drawing two lines offset by one  > v2.A0
pixel location and you would come "close" to the original thickness   > v2.A0
of the line at 640x350 resolution, but it wouldn't be a perfect       > v2.A0
match.  A perfect match is a rare thing when dealing with different   > v2.A0
resolutions.                                                          > v2.A0
                                                                      > v2.A0
Now, on to the real issue at hand here: translation of coordinates.   > v2.A0
We won't worry about the size of pixels, but will concentrate on      > v2.A0
getting the locations of points correct at different resolutions.     > v2.A0
Let's say you have a screen at 640x350 resolution with two filled     > v2.A0
rectangles drawn on it.  The first rectangle is drawn from (2,1) to   > v2.A0
(4,3) and the second one is drawn from (5,1) to (7,3) like this:      > v2.A0
                                                                      > v2.A0
                                                                      > v2.A0
                       0 1 2 3 4 5 6 7 8 9                            > v2.A0
                      +-+-+-+-+-+-+-+-+-+-+                           > v2.A0
                     0| | | | | | | | | | |       1st: (2,1) - (4,3)  > v2.A0
                      +-+-+-+-+-+-+-+-+-+-+       2nd: (5,1) - (7,3)  > v2.A0
                     1| | |#|#|#|*|*|*| | |                           > v2.A0
                      +-+-+-+-+-+-+-+-+-+-+                           > v2.A0
                     2| | |#|#|#|*|*|*| | |                           > v2.A0
                      +-+-+-+-+-+-+-+-+-+-+                           > v2.A0
                     3| | |#|#|#|*|*|*| | |                           > v2.A0
                      +-+-+-+-+-+-+-+-+-+-+                           > v2.A0
                     4| | | | | | | | | | |                           > v2.A0
                      +-+-+-+-+-+-+-+-+-+-+                           > v2.A0
                                                                      > v2.A0
Now, you notice that both rectangles are right next to each other.    > v2.A0
There are no gaps between them.  Now, if you tried to draw these same > v2.A0
two rectangles on a graphics screen that was 1280x700 pixels in size, > v2.A0
and tried to make it appear in the exact same location and size on    > v2.A0
the monitor, you would have to translate the corners of the           > v2.A0
rectangles to the new resolution and re-plot the rectangles.  Now,    > v2.A0
640x2 is 1280 and 350x2 is 700 so our new resolution is exactly twice > v2.A0
as large in both the X and Y directions (this is RARELY the case!).   > v2.A0
So, in order to translate our original coordinates to this resolution > v2.A0
we simply multiply the numbers by 2.  Pretty simple.  Our previous    > v2.A0
rectangles in their old untranslated state and the newly translated   > v2.A0
ones would be:                                                        > v2.A0
                                                                      > v2.A0
                 UNTRANSLATED        TRANSLATED                       > v2.A0
                --------------------------------                      > v2.A0
   RECTANGLE 1   (2,1) - (4,3)       (4,2) - (8,6)                    > v2.A0
   RECTANGLE 2   (5,1) - (7,3)      (10,2) - (14,6)                   > v2.A0
                                                                      > v2.A0
Now, let's plot these two rectangles on our new graphics screen at    > v2.A0
the newly translated coordinates:                                     > v2.A0
                                                                      > v2.A0

                            (X DIMENSION)                             > v2.A0
                                                                      > v2.A0
                                      1 1 1 1 1 1 1                   > v2.A0
                  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6                   > v2.A0
                 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+                  > v2.A0
                0| | | | | | | | | | | | | | | | | |                  > v2.A0
                 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+                  > v2.A0
                1| | | | | | | | | | | | | | | | | |                  > v2.A0
                 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+                  > v2.A0
           Y    2| | | | |#|#|#|#|#| |*|*|*|*|*| | |                  > v2.A0
                 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+                  > v2.A0
           D    3| | | | |#|#|#|#|#| |*|*|*|*|*| | |                  > v2.A0
           I     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+                  > v2.A0
           M    4| | | | |#|#|#|#|#| |*|*|*|*|*| | |                  > v2.A0
           E     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+                  > v2.A0
           N    5| | | | |#|#|#|#|#| |*|*|*|*|*| | |                  > v2.A0
           S     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+                  > v2.A0
           I    6| | | | |#|#|#|#|#| |*|*|*|*|*| | |                  > v2.A0
           O     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+                  > v2.A0
           N    7| | | | | | | | | | | | | | | | | |                  > v2.A0
                 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+                  > v2.A0
                8| | | | | | | | | | | | | | | | | |                  > v2.A0
                 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+                  > v2.A0
                                                                      > v2.A0
Whoa!  What happened?  We now have a black line in between the two    > v2.A0
rectangles.  That's definitely not what we wanted to happen.  Why did > v2.A0
this happen?  It's partly because of the nature of graphics hardware  > v2.A0
in the way they address pixels, and partly the way we humans think of > v2.A0
pixels mathematically from a programming standpoint.  What we need is > v2.A0
a better mathematical representation of pixels and graphics           > v2.A0
coordinates so that when we translate coordinates these things don't  > v2.A0
happen.                                                               > v2.A0
                                                                      > v2.A0
As we mentioned earlier, the lines on the above diagram represent the > v2.A0
borders around each pixel.  Each of these lines, like their           > v2.A0
mathematical counterparts, are infinitely thin.  The only thing in    > v2.A0
the above diagram that has any size (or area) physically are the      > v2.A0
pixels themselves.  Since the boundary lines around the pixels are    > v2.A0
defining the area that the pixel will occupy, it makes sense that we  > v2.A0
should think of those lines as the actual coordinates.  If we think   > v2.A0
of the areas in between the pixels as the actual coordinates, we can  > v2.A0
think of pixels as the areas in between coordinates that are filled   > v2.A0
in with color.  So, if we said to draw a filled in rectangle like we  > v2.A0
did earlier, we would actually be saying "fill in this rectangle's    > v2.A0
interior".  Just like coloring books as a child, you have to stay     > v2.A0
inside the lines (or at least were supposed to).  Think about pixels  > v2.A0
as spots between the lines that get filled in with color just like a  > v2.A0
coloring book - the only difference is, a pixel cannot go outside the > v2.A0
lines (don't you wish you were a pixel when you were younger?).       > v2.A0
                                                                      > v2.A0
Using this new way of thinking of graphics is not very difficult, it  > v2.A0
just seems a bit odd -especially if you've been working with graphics > v2.A0
for awhile.  To draw the previous two rectangles properly the         > v2.A0
coordinates for them would have to be changed somewhat - like this:   > v2.A0
                                                                      > v2.A0

                          (old method)                                > v2.A0
                                                                      > v2.A0
                 UNTRANSLATED        TRANSLATED                       > v2.A0
                --------------------------------                      > v2.A0
   RECTANGLE 1   (2,1) - (4,3)       (4,2) - (8,6)                    > v2.A0
   RECTANGLE 2   (5,1) - (7,3)      (10,2) - (14,6)                   > v2.A0
                                                                      > v2.A0
                                                                      > v2.A0
                          (new method)                                > v2.A0
                                                                      > v2.A0
                 UNTRANSLATED        TRANSLATED                       > v2.A0
                --------------------------------                      > v2.A0
   RECTANGLE 1   (2,1) - (5,4)       (4,2) - (10,8)                   > v2.A0
   RECTANGLE 2   (5,1) - (8,4)      (10,2) - (16,8)                   > v2.A0
                                                                      > v2.A0
Notice that the untranslated rectangles' coordinates are almost the   > v2.A0
same.  In fact, the upper-left coordinates haven't changed at all.    > v2.A0
The only coordinates that have changed are the lower-right            > v2.A0
coordinates, and only by one pixel location.  Now, if we draw these   > v2.A0
two rectangles using our new mathematical model for graphics, we      > v2.A0
would get the following (in both resolution examples:                 > v2.A0
                                                                      > v2.A0
                                                   1 1 1 1 1 1 1 1    > v2.A0
                               0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7    > v2.A0
                              0+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+    > v2.A0
                        1      | | | | | | | | | | | | | | | | | |    > v2.A0
    0 1 2 3 4 5 6 7 8 9 0     1+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+    > v2.A0
   0+-+-+-+-+-+-+-+-+-+-+      | | | | | | | | | | | | | | | | | |    > v2.A0
    | | | | | | | | | | |     2+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+    > v2.A0
   1+-+-+-+-+-+-+-+-+-+-+      | | | | |#|#|#|#|#|#|*|*|*|*|*| | |    > v2.A0
    | | |#|#|#|*|*|*| | |     3+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+    > v2.A0
   2+-+-+-+-+-+-+-+-+-+-+      | | | | |#|#|#|#|#|#|*|*|*|*|*| | |    > v2.A0
    | | |#|#|#|*|*|*| | |     4+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+    > v2.A0
   3+-+-+-+-+-+-+-+-+-+-+      | | | | |#|#|#|#|#|#|*|*|*|*|*| | |    > v2.A0
    | | |#|#|#|*|*|*| | |     5+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+    > v2.A0
   4+-+-+-+-+-+-+-+-+-+-+      | | | | |#|#|#|#|#|#|*|*|*|*|*| | |    > v2.A0
    | | | | | | | | | | |     6+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+    > v2.A0
   5+-+-+-+-+-+-+-+-+-+-+      | | | | |#|#|#|#|#|#|*|*|*|*|*| | |    > v2.A0
                              7+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+    > v2.A0
                               | | | | |#|#|#|#|#|#|*|*|*|*|*| | |    > v2.A0
                              8+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+    > v2.A0
                               | | | | | | | | | | | | | | | | | |    > v2.A0
                              9+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+    > v2.A0
                                                                      > v2.A0
If you look closely at the two graphs above you may notice a subtle   > v2.A0
difference in the numbering of the coordinates.  The numbers are all  > v2.A0
there, but instead of labeling the cells themselves with coordinates, > v2.A0
we have labeled the lines in between as the coordinates.  When we say > v2.A0
to draw a rectangle from (2,1) to (5,4) we are saying to draw a       > v2.A0
filled in area "between" coordinate lines 2 and 5 in the X direction  > v2.A0
and 1 and 4 in the Y direction.  If you look closely at the upper     > v2.A0
left diagram, you will notice that is exactly what we have done.  Now > v2.A0
look closely at the upper right diagram.  There are no gaps between   > v2.A0
the rectangles now.  Also if you look at the translated coordinates,  > v2.A0
the right edge of the first rectangle is at X coordinate 10, and the  > v2.A0
left edge of the second rectangle is also at X coordinate 10.  But    > v2.A0
they don't overlap each other.  That's the part about this new way of > v2.A0
thinking about things that gives people the hardest time.             > v2.A0
                                                                      > v2.A0
So far so good.  Let's look at another example - one which draws the  > v2.A0
same two rectangles but this time, let's not fill them in.  The       > v2.A0
diagram below shows the two at both example resolutions:              > v2.A0
                                                                      > v2.A0

                                                   1 1 1 1 1 1 1 1    > v2.A0
                               0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7    > v2.A0
                              0+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+    > v2.A0
                        1      | | | | | | | | | | | | | | | | | |    > v2.A0
    0 1 2 3 4 5 6 7 8 9 0     1+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+    > v2.A0
   0+-+-+-+-+-+-+-+-+-+-+      | | | | | | | | | | | | | | | | | |    > v2.A0
    | | | | | | | | | | |     2+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+    > v2.A0
   1+-+-+-+-+-+-+-+-+-+-+      | | | | |#|#|#|#|#|#|*|*|*|*|*| | |    > v2.A0
    | | |#|#|#|*|*|*| | |     3+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+    > v2.A0
   2+-+-+-+-+-+-+-+-+-+-+      | | | | |#| | | | | |*| | | |*| | |    > v2.A0
    | | |#| | |*| |*| | |     4+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+    > v2.A0
   3+-+-+-+-+-+-+-+-+-+-+      | | | | |#| | | | | |*| | | |*| | |    > v2.A0
    | | |#|#|#|*|*|*| | |     5+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+    > v2.A0
   4+-+-+-+-+-+-+-+-+-+-+      | | | | |#| | | | | |*| | | |*| | |    > v2.A0
    | | | | | | | | | | |     6+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+    > v2.A0
   5+-+-+-+-+-+-+-+-+-+-+      | | | | |#| | | | | |*| | | |*| | |    > v2.A0
                              7+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+    > v2.A0
                               | | | | |#|#|#|#|#|#|*|*|*|*|*| | |    > v2.A0
                              8+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+    > v2.A0
                               | | | | | | | | | | | | | | | | | |    > v2.A0
                              9+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+    > v2.A0
                                                                      > v2.A0
Not what you thought would happen, huh?  This example illustrates a   > v2.A0
key point in our mathematical model of graphics: that there is a      > v2.A0
difference in filled objects and outlined objects.  Filled objects    > v2.A0
fill everything inside an enclosed area whereas an outline (one or    > v2.A0
more lines) uses pixels to approximate an infinitely thin line.       > v2.A0
When lines and points are plotted on the video device, they are       > v2.A0
"rounded up" to the next highest pixel location.  So, a point at      > v2.A0
(4,2) would not be on the intersecting lines at (4,2), it would be a  > v2.A0
pixel activated between 4 and 5 on the X axis and 2 and 3 on the Y    > v2.A0
axis.  Look at the upper right diagram to convince yourself this is   > v2.A0
the case.  Filled-in areas on the other hand, do not round up to the  > v2.A0
next highest pixel locations.  They always fill in an area in between > v2.A0
the boundary lines.  This means that in a filled-in rectangle, the    > v2.A0
right and bottom edges are "off by one" so to speak.                  > v2.A0
                                                                      > v2.A0
To better illustrate these two different situations, we will draw a   > v2.A0
filled-in rectangle and a non-filled rectangle both using the same    > v2.A0
dimensions at the same resolution:                                    > v2.A0
                                                                      > v2.A0
                             1                          1             > v2.A0
         0 1 2 3 4 5 6 7 8 9 0      0 1 2 3 4 5 6 7 8 9 0             > v2.A0
        0+-+-+-+-+-+-+-+-+-+-+     0+-+-+-+-+-+-+-+-+-+-+             > v2.A0
         | | | | | | | | | | |      | | | | | | | | | | |             > v2.A0
        1+-+-+-+-+-+-+-+-+-+-+     1+-+-+-+-+-+-+-+-+-+-+             > v2.A0
         | | |*|*|*|*|*|*| | |      | | |#|#|#|#|#|#|#| |             > v2.A0
        2+-+-+-+-+-+-+-+-+-+-+     2+-+-+-+-+-+-+-+-+-+-+             > v2.A0
         | | |*|*|*|*|*|*| | |      | | |#| | | | | |#| |             > v2.A0
        3+-+-+-+-+-+-+-+-+-+-+     3+-+-+-+-+-+-+-+-+-+-+             > v2.A0
         | | |*|*|*|*|*|*| | |      | | |#| | | | | |#| |             > v2.A0
        4+-+-+-+-+-+-+-+-+-+-+     4+-+-+-+-+-+-+-+-+-+-+             > v2.A0
         | | |*|*|*|*|*|*| | |      | | |#| | | | | |#| |             > v2.A0
        5+-+-+-+-+-+-+-+-+-+-+     5+-+-+-+-+-+-+-+-+-+-+             > v2.A0
         | | | | | | | | | | |      | | |#|#|#|#|#|#|#| |             > v2.A0
        6+-+-+-+-+-+-+-+-+-+-+     6+-+-+-+-+-+-+-+-+-+-+             > v2.A0
         | | | | | | | | | | |      | | | | | | | | | | |             > v2.A0
        7+-+-+-+-+-+-+-+-+-+-+     7+-+-+-+-+-+-+-+-+-+-+             > v2.A0
           Filled rectangle           Unfilled rectangle              > v2.A0
            (2,1) - (8,5)               (2,1) - (8,5)                 > v2.A0
                                                                      > v2.A0

Notice that the two rectangles are not the exact same size.  Both the > v2.A0
left and top edges are at the exact same locations, but in the case   > v2.A0
of the unfilled rectangle, the right and bottom edges are one pixel   > v2.A0
over and down.  This shows that lines and points are rounded up to    > v2.A0
the next highest pixel location (the first pixel after the            > v2.A0
coordinate), but filled areas area between the boundary lines.  This  > v2.A0
seemingly odd way of doing things becomes extremely important when    > v2.A0
you deal with one image at different resolutions - as you saw with    > v2.A0
the case of translating two filled-in rectangles earlier from one     > v2.A0
resolution to another.                                                > v2.A0
                                                                      > v2.A0
In a very real sense, you could easily think about coordinates and    > v2.A0
graphics in two different ways.  The way to think about them depends  > v2.A0
on the type of graphics operation being performed.  If you are        > v2.A0
dealing with a fill operation of some kind, then you think about the  > v2.A0
drawing surface with coordinate lines "in between" the physical pixel > v2.A0
cells.  If you are dealing with a line drawing situation (or drawing  > v2.A0
points, circles, etc), then you can think of coordinates directly     > v2.A0
addressing the pixel cells themselves (just like when we began this   > v2.A0
conversation at the beginning of this section).  When dealing with    > v2.A0
line drawing operations, there is no difference in mathematical       > v2.A0
models - there's only a difference when you get into filling areas    > v2.A0
in.  Whichever method of thinking of things works best for you, use.  > v2.A0





===================================================================== > v2.A0
==        COLOR PALETTES AND HARDWARE - THE DESKTOP PALETTE        == > v2.A0
===================================================================== > v2.A0
                                                                      > v2.A0
With versions of RIPscrip prior to v2.0, the color palette was        > v2.A0
limited to 16 colors maximum out of a total of 64 colors in the       > v2.A0
Master Color Palette.  This was due to the EGA basis for the language > v2.A0
in the initial releases.  With the popularity of higher color video   > v2.A0
sub-systems, RIPscrip needs to grow to accomodate these advancing     > v2.A0
trends. In addition, it needs to be open-ended enough to accomodate   > v2.A0
yet unknown hardware environments that might provide for even higher  > v2.A0
color resolution.                                                     > v2.A0
                                                                      > v2.A0
The 1.xx RIPscrip specification provided for 16 colors out of a       > v2.A0
palette of 64 colors.  This 64 color palette corresponds to 2-bits of > v2.A0
Red, Green and Blue information each, giving you four levels of color > v2.A0
saturation in each of the three categories.  Unlike typical RGB       > v2.A0
implementations the color palette entry numbers are not sequentially  > v2.A0
ordered based on the R, G and B components, but are directly          > v2.A0
associated with the hardware registers of the IBM-PC Enhanced         > v2.A0
Graphics Adapter (EGA) video sub-system.  The bit-layouts of the      > v2.A0
color registers are as follows:                                       > v2.A0
                                                                      > v2.A0
                       Primary    Secondary                           > v2.A0
                     ___________ ___________                          > v2.A0
             ___ ___ ___ ___ ___ ___ ___ ___                          > v2.A0
            |   |   |   |   |   |   |   |   |                         > v2.A0
            | - | - | R | G | B | R | G | B |                         > v2.A0
            |___|___|___|___|___|___|___|___|                         > v2.A0
              80  40  20  10  8   4   2   1  (hex)                    > v2.A0
              7   6   5   4   3   2   1   0  (position)               > v2.A0
                                                                      > v2.A0
Notice that each of the R, G and B sections are broken up into two    > v2.A0
separate bit sections in the color palette entry number.  Also, the   > v2.A0
bits are reversed when they are encoded.  Let's look at four separate > v2.A0
colors of Red, Green and Blue to see how the bit patterns correspond  > v2.A0
to the actual Palette entries:                                        > v2.A0
                                                                      > v2.A0
 RED   PALETTE ENTRY    GREEN  PALETTE ENTRY     BLUE  PALETTE ENTRY  > v2.A0
 -------------------     -------------------     -------------------  > v2.A0
         xxRGBrgb                xxRGBrgb                xxRGBrgb     > v2.A0
         --------                --------                --------     > v2.A0
 00      00000000        00      00000000        00      00000000     > v2.A0
 01      00100000        01      00010000        01      00001000     > v2.A0
 10      00000100        10      00000010        10      00000001     > v2.A0
 11      00100100        11      00010010        11      00001001     > v2.A0
                                                                      > v2.A0
In the RIPscrip v2.00 specification, this base-level 16 color palette > v2.A0
will be from here on out referred to as the Desktop Palette.  It will > v2.A0
still be limited to a possible set of 64 colors to choose from, based > v2.A0
on two bits for each Red, Green and Blue.  The actual R/G/B values    > v2.A0
that they "map to" in the video hardware will be pro-rated based upon > v2.A0
the true number of bits-per-pixel used.  For example, if you were     > v2.A0
using this on a VGA video adapter in 256 color mode, you would be     > v2.A0
dealing with 6 bits for each color component in the color palette     > v2.A0
giving you a master color palette of 18 bits or 262,144 possible      > v2.A0
color combinations.  Since you have 6 bits for Red, Green and Blue    > v2.A0
respectively, you must choose your R/G/B values very carefully when   > v2.A0
working with the Desktop Palette.  The Desktop Palette has two bits   > v2.A0
for each color component.  These should be "mapped" to the true color > v2.A0
palette.  In the above example, you would sub-divide the 6 bit color  > v2.A0
space into four distinct sub-sections paying close attention that a   > v2.A0
color value of "00" is no color, and "11" is maximum saturation of    > v2.A0
that color.  Breaking the color space down, you would have the        > v2.A0
following mapping:                                                    > v2.A0

                                                                      > v2.A0
          RED   TRUE COLOR (0-63)                                     > v2.A0
          -----------------------                                     > v2.A0
          00     0 - no color                                         > v2.A0
          01    21                                                    > v2.A0
          10    42                                                    > v2.A0
          11    63 - max color                                        > v2.A0
                                                                      > v2.A0
Since 6 bits gives you a maximum value of 64, your color space ranges > v2.A0
from 0-63.  A color value of 00 in the Desktop Palette corresponds to > v2.A0
a color value of 0 in the Real Palette.  A value of 11 in the Desktop > v2.A0
Palette corresponds to the highest value in the Real Palette (63).    > v2.A0
This leaves two values in the middle that haven't been accounted for  > v2.A0
yet.  Taking the maximum value possible in the Real Palette (63) and  > v2.A0
dividing that by three gives us the value 21, which are the           > v2.A0
threshold levels for each of the two remaining values (01 and 10).    > v2.A0
With this in mind, we have found our values for 01 and 10, which are  > v2.A0
21 and 42 respectively.                                               > v2.A0
                                                                      > v2.A0
In a Real Palette where 8 bits are used for each Red, Green and Blue  > v2.A0
section, you have a total of 256 distinct levels of Red, Green and    > v2.A0
Blue.  The Desktop Palette mappings in this case would be (for the    > v2.A0
example of Red - Green and Blue would be identical mappings):         > v2.A0
                                                                      > v2.A0
          RED   TRUE COLOR (0-255)                                    > v2.A0
          ------------------------                                    > v2.A0
          00      0 - no color                                        > v2.A0
          01     85                                                   > v2.A0
          10    170                                                   > v2.A0
          11    255 - max color                                       > v2.A0
                                                                      > v2.A0
So, when dealing with the color palette commands to alter the Desktop > v2.A0
Palette, you are still dealing with the same interface in the 2.0     > v2.A0
specification as you were in the 1.xx specification - you still have  > v2.A0
two bits of precision for the Red, Green and Blue color components.   > v2.A0
Even though they map to a higher set of color numbers, that is        > v2.A0
unimportant - the interface is the same, leaving full backward        > v2.A0
compatibility.                                                        > v2.A0





===================================================================== > v2.A0
==        COLOR PALETTES AND HARDWARE - THE DRAWING PALETTE        == > v2.A0
===================================================================== > v2.A0
                                                                      > v2.A0
Since the Desktop Palette can only address 16 separate colors, a new  > v2.A0
scheme must be devised to accomodate other color configurations like  > v2.A0
256 colors (8-bits-per-pixel) and 24-bit color.  Like some other      > v2.A0
operating environments like Microsoft Windows, we will introduce      > v2.A0
another Color Palette system, called the Drawing Palette.  This       > v2.A0
palette is much more flexible than the Desktop Palette because it can > v2.A0
handle many more colors.                                              > v2.A0
                                                                      > v2.A0
The bare-minimum number of colors supported by the RIPscrip language  > v2.A0
is 16 colors (4 bits).  The maximum number of colors will be open     > v2.A0
ended leaving room for future hardware to be used.                    > v2.A0
                                                                      > v2.A0
The Drawing Palette is formally defined as a color palette with N     > v2.A0
entries, each of which can have their own Red, Green and Blue         > v2.A0
component colors specified independently.  The total number of values > v2.A0
allowable for each R/G/B are dependent on the actual video hardware   > v2.A0
in use on the Client Terminal System.  If a discrepency exists        > v2.A0
between the number of bits specified and the number requested, a      > v2.A0
"mapping" operation will be performed to translate the requested      > v2.A0
values to something usable by the video device.                       > v2.A0
                                                                      > v2.A0
There are two distinct color palette schemes, each will be handled in > v2.A0
a similar syntactical method, but distinctly different in nature:     > v2.A0
                                                                      > v2.A0
     1) COLOR PALETTE MAPPING - Mapping is like the Desktop           > v2.A0
        Palette where a color index is used to "map" into a           > v2.A0
        Master Color Palette.  Each of the actual colors are          > v2.A0
        determined by some indexing scheme (RGB in the case           > v2.A0
        of RIPscrip).  This allows you to alter the lower             > v2.A0
        level color mappings, thus changing the colors                > v2.A0
        already on screen instantly.  Any drawing primitives          > v2.A0
        which specify a "color" are actually specifying a             > v2.A0
        color index.  Whatever real color that "maps" to is           > v2.A0
        unimportant - the drawing primitive simply knows              > v2.A0
        that it is drawing in color #5 - this could map to            > v2.A0
        some shade of Green, Orange or anything else.  The            > v2.A0
        true color is determined by the Red, Green and Blue           > v2.A0
        component colors that are used to define the color            > v2.A0
        mapping.                                                      > v2.A0
                                                                      > v2.A0
     2) DIRECT RGB COLORS - This mode is typically used in            > v2.A0
        24-bit color mode.  In 24-bit color mode, you have            > v2.A0
        16,777,216 total colors possible.  It would be                > v2.A0
        totally inconceivable to maintain 16 million separate         > v2.A0
        color palette index mapping registers in memory in an         > v2.A0
        application - that's more memory than most computers          > v2.A0
        have ever - even at one byte per entry, there would           > v2.A0
        be insufficient memory storage to perform any color           > v2.A0
        mapping.  In this case, there is no "mapping"                 > v2.A0
        performed.  Color Index numbers in this case are              > v2.A0
        actually directly related to the real RGB value used.         > v2.A0
                                                                      > v2.A0
        In a 24-bit world, let's say you specify a color              > v2.A0
        value (in binary) of the following:                           > v2.A0
                                                                      > v2.A0
                 RED     GREEN     BLUE                               > v2.A0
               --------------------------                             > v2.A0
               00000100 00010100 00001100 - binary                    > v2.A0
                 04h       14h      0Dh   - hexadecimal               > v2.A0
                                                                      > v2.A0

        When you actually set a drawing color, in direct RGB          > v2.A0
        mapping, the number you specify will actually be the          > v2.A0
        encoded RGB value you wish to use.  In the above case,        > v2.A0
        setting a color number of 04140Dh hexadecimal would           > v2.A0
        correspond to values of RED=04h, GREEN=14h and BLUE=0Dh.      > v2.A0
                                                                      > v2.A0
Now on to the way that RIPscrip will handle these two totally         > v2.A0
different situations.  We already have the Desktop Palette which has  > v2.A0
a total of 16 separate color palette indices.  These map to some      > v2.A0
arbitrary color in the video hardware.  We will now introduce a new   > v2.A0
color palette, the Drawing Palette which encompasses the Desktop      > v2.A0
Palette inside it.  Combined, they make up the entire Color Palette   > v2.A0
used in RIPscrip.  This color palette is used solely for color        > v2.A0
mapping to some arbitrary RGB colors.  The Indexable color palette in > v2.A0
RIPscrip, better known as the Drawing Palette has 256 different       > v2.A0
entries, all of which map to a given RGB color.  The actual number of > v2.A0
bits for each Red, Green and Blue component is unimportant at this    > v2.A0
time - only the fact that a Color Mapping is performed whenever a     > v2.A0
color index from 0-255 is specified.                                  > v2.A0
                                                                      > v2.A0
As previously mentioned, the Desktop Palette is part of the master    > v2.A0
Drawing Palette.  The correspondance of entries is as follows:        > v2.A0
            __________________                                        > v2.A0
         000 \                \                                       > v2.A0
         001  \                \                                      > v2.A0
          :    \ Desktop        \                                     > v2.A0
          :    / Palette         \                                    > v2.A0
         014  /  (16 entries)     \                                   > v2.A0
         015_/                     \ DRAWING                          > v2.A0
         016 \                     / PALETTE                          > v2.A0
         017  \                   /  (256 entries)                    > v2.A0
          :    \ Extended        /                                    > v2.A0
          :    / Palette        /                                     > v2.A0
         254  /  (240 entries) /                                      > v2.A0
         255_/________________/                                       > v2.A0
                                                                      > v2.A0
As you can see, the master Drawing Palette is broken down into two    > v2.A0
separate palette regions - the Desktop Palette with its 16 color      > v2.A0
entries, and an Extended Palette with 240 entries.  Any of these 256  > v2.A0
entries can be mapped to arbitrary RGB color combinations.  The       > v2.A0
Desktop Palette is a special case in that it has TWO ways of setting  > v2.A0
the RGB mapping values.                                               > v2.A0
                                                                      > v2.A0
The first method of setting the Desktop Palette's mappings is based   > v2.A0
on the 1.xx version of RIPscrip.  These Set Palette commands use only > v2.A0
two bits per pixel for their "color space".  In reality, in the       > v2.A0
abitrary world, these will map to some other RGB combination based    > v2.A0
upon the actual video hardware in use as mentioned in preceding       > v2.A0
sections.                                                             > v2.A0
                                                                      > v2.A0
The second method of setting the Desktop Palette would be in the      > v2.A0
exact same way as setting the Extended Palette - in fact, if you      > v2.A0
completely ignore the 1.xx version of RIPscrip's Set Palette          > v2.A0
commands, the Desktop Palette plus the Extended Palette are identical > v2.A0
in nature to the master Drawing Palette.  What this means is, in the  > v2.A0
2.xx specification, both the Extended and Desktop palettes can        > v2.A0
contain arbitrary RGB color mappings (6-bits-per-pixel,               > v2.A0
8-bits-per-pixel, etc).  In the 1.xx specification, using those       > v2.A0
versions of the Set Palette commands, you can only have two-bits for  > v2.A0
R, G and B.                                                           > v2.A0
                                                                      > v2.A0

With all this in mind, you could actually have two set palette        > v2.A0
commands in a row like this:                                          > v2.A0
                                                                      > v2.A0
     SET PALETTE (1.xx) - Set entry #5 to     01     11     01 (RGB)  > v2.A0
     SET PALETTE (2.xx) - Set entry #5 to 101011 100110 001100 (RGB)  > v2.A0
                                                                      > v2.A0
If you notice, both commands are setting entry #5.  The first command > v2.A0
though is a v1.xx version of the Set Palette function - this only     > v2.A0
allows for 2 bits for R, G and B.  This only gives you 64             > v2.A0
combinations of RGB values.  The second command however, uses the     > v2.A0
extended RGB settings allowing you to address any of the 256 colors   > v2.A0
in the Drawing Palette to an arbitrary RGB combination - the total    > v2.A0
number of bits for R, G or B is dependent on the video system         > v2.A0
actually in use.                                                      > v2.A0





===================================================================== > v2.A0
==               COLOR MAPPING VS. DIRECT RGB COLORS               == > v2.A0
===================================================================== > v2.A0
                                                                      > v2.A0
We've already discussed the Drawing Palette and how it is used to map > v2.A0
a color index into some arbitrary RGB combination.  This doesn't      > v2.A0
address the concept of direct RGB colors though, like 24-bit imaging  > v2.A0
where it is infeasible to do color palette mapping.  This is where    > v2.A0
the Direct RGB mode of RIPscrip comes in.  Most every location in the > v2.A0
RIPscrip language that accepts a color number can handle Direct RGB   > v2.A0
Colors.  When and where Direct RGB is used or not is dependent on a   > v2.A0
mode switch.  There are two color modes:                              > v2.A0
                                                                      > v2.A0
                         MODE_COLOR_MAP                               > v2.A0
                         MODE_DIRECT_RGB                              > v2.A0
                                                                      > v2.A0
The default mode is Color Map mode where the 256 color Drawing        > v2.A0
Palette is used for all drawing primitives.  You can switch modes to  > v2.A0
the Direct RGB mode.  Any command that can accept Direct RGB Color    > v2.A0
values will interpret their color numbers as RGB encoded "raw" colors > v2.A0
instead of a Color Index Number.  In other words, if you are in       > v2.A0
Direct RGB mode, any color number you specify in a drawing primitive  > v2.A0
is the actual raw RGB color value for that primitive, not the color   > v2.A0
index number used in the Drawing Palette.                             > v2.A0
                                                                      > v2.A0
When setting Direct RGB mode, another piece of information needs to   > v2.A0
be supplied to RIPscrip - how many bits are used for each R, G and B  > v2.A0
color component.  Without that, you cannot determine whether you are  > v2.A0
dealing with 18-bit color codes, 24-bit color, 32-bit color, etc.     > v2.A0
                                                                      > v2.A0
Both modes may be used interchangably in RIPscrip - however, if the   > v2.A0
Client Terminal is in a video mode where direct RGB mode is NOT in    > v2.A0
use (eg, EGA or VGA graphics), then a dynamic "best match" approach   > v2.A0
must be used.  When this is done, RIPscrip must look at the RGB color > v2.A0
you specify and look through its Drawing Palette for the closest      > v2.A0
match it can find and use that color instead.  In this way, RGB       > v2.A0
colors can be used in any situation - but only the closest colors in  > v2.A0
the active Drawing Palette will truly be used for the drawing         > v2.A0
primitives.                                                           > v2.A0





===================================================================== > v2.A0
==                    COLOR PALETTE INDEPENDENCE                   == > v2.A0
===================================================================== > v2.A0
                                                                      > v2.A0
Now that we've discussed Color Palette Mapping and Direct RGB Color   > v2.A0
modes, we need to discuss the concept of Color Palette Independence   > v2.A0
(CPI).  Color Palette Independence is a term used to indicate that no > v2.A0
matter what "type" of color combination is requested, the Client      > v2.A0
Terminal has to handle it as best it can.  For example, if a scene is > v2.A0
received by the terminal that is setup for 256 colors, but it is      > v2.A0
displayed on a terminal in 16 color mode, RIPscrip has to determine   > v2.A0
the best color combinations possible to approximate the 256 color     > v2.A0
picture as closely as it can in 16 colors.  This is called Color      > v2.A0
Palette Independence.                                                 > v2.A0
                                                                      > v2.A0
CPI can be easily accomodated in Direct RGB Color mode by simply      > v2.A0
checking through the active Drawing Color Palette and choosing the    > v2.A0
color index that is as close to the requested RGB color as possible.  > v2.A0
It is distinctly possible, and in fact probable that the requested    > v2.A0
RGB color will not match another color in the Drawing Palette         > v2.A0
identically.  A "best match" approach must be taken to find the       > v2.A0
closest match.  If the terminal is running in 16 color mode, only the > v2.A0
lowest 16 colors (the Desktop Palette) are checked for exactness.     > v2.A0
But if the terminal is running in 256 color or higher mode, then the  > v2.A0
entire Drawing Palette is checked for a close color.                  > v2.A0
                                                                      > v2.A0
When dealing with Color Mapping Mode however, more care must be taken > v2.A0
to ensure that the palette is setup properly based on the Client      > v2.A0
Terminal's actual hardware configuration.  In 256 and higher color    > v2.A0
modes, this isn't a problem as there at least as many color entries   > v2.A0
as there are actual simultaneously displayable colors.  In 16 color   > v2.A0
mode however, the world gets a bit more complicated.                  > v2.A0
                                                                      > v2.A0
16 color graphics mode must examine the entire 256 color Drawing      > v2.A0
Palette and make an "educated guess" as to which 16 colors are the    > v2.A0
best ones to use for the Desktop Palette.  An internal re-mapping     > v2.A0
table must be maintained which indicates which of the 256 color       > v2.A0
values map to which Desktop Palette entry.  In this way, the RIPscrip > v2.A0
scene being received may still use its normal 256 color index         > v2.A0
numbers, but when used, they are "looked up" in a translation table   > v2.A0
to determine which Desktop Palette color to use instead.  In this     > v2.A0
method, compatibility can be maintained, and colors will be as close  > v2.A0
as possible.                                                          > v2.A0
                                                                      > v2.A0
Determining the 16-color translation table is the tricky part.  The   > v2.A0
entire 256 color Drawing Palette must be analyzed, determining what   > v2.A0
colors are the dominant ones, taking into consideration color         > v2.A0
distribution and color variations.  For example, if a Drawing Palette > v2.A0
was comprised of 75% shades of Blues, and the remainder various       > v2.A0
Grays, Greens and Reds, then the final Desktop Palette would have to  > v2.A0
consist of the same proportions of colors.  In this manner, the total > v2.A0
distribution of colors in the Desktop Palette is as closely identical > v2.A0
to the color distribution in the Drawing Palette as possible - thus   > v2.A0
leaving roughly equivalent colors in the remaining palette to choose  > v2.A0
from.  The details of this analysis and color choosing will be        > v2.A0
determined at a later time.                                           > v2.A0





===================================================================== > v2.A0
==              DEFAULT RGB VALUES OF DRAWING PALETTE              == > v2.A0
===================================================================== > v2.A0
                                                                      > v2.A0
When the Drawing Palette is used fully (in 256 color or higher mode), > v2.A0
it will contain certain default RGB values.  These values will be     > v2.A0
restored whenever a RIP_RESET_WINDOWS command is issued as well as    > v2.A0
when the software initializes the first time.                         > v2.A0
                                                                      > v2.A0
Given 6 bits for Red, Green and Blue (18 bits total), the following   > v2.A0
table defines the RGB definitions for the default Drawing Palette     > v2.A0
in Decimal form:                                                      > v2.A0


Num    R  G  B    R  G  B    R  G  B    R  G  B    R  G  B    R  G  B > v2.A1
===================================================================== > v2.A1
  0 |  0  0  0    0  0 42    0 42  0    0 42 42   42  0  0   42  0 42 > v2.A1
  6 | 42 21  0   42 42 42   21 21 21   21 21 63   21 63 21   21 63 63 > v2.A1
 12 | 63 21 21   63 21 63   63 63 21   63 63 63    0  0  0    4  4  4 > v2.A1
 18 |  8  8  8   13 13 13   17 17 17   21 21 21   25 25 25   29 29 29 > v2.A1
 24 | 34 34 34   38 38 38   42 42 42   46 46 46   50 50 50   55 55 55 > v2.A1
 30 | 59 59 59   63 63 63    0  0  0    0  0 21    0  0 42    0  0 63 > v2.A1
 36 |  0  9  0    0  9 21    0  9 42    0  9 63    0 18  0    0 18 21 > v2.A1
 42 |  0 18 42    0 18 63    0 27  0    0 27 21    0 27 42    0 27 63 > v2.A1
 48 |  0 36  0    0 36 21    0 36 42    0 36 63    0 45  0    0 45 21 > v2.A1
 54 |  0 45 42    0 45 63    0 54  0    0 54 21    0 54 42    0 54 63 > v2.A1
 60 |  0 63  0    0 63 21    0 63 42    0 63 63   10  0  0   10  0 21 > v2.A1
 66 | 10  0 42   10  0 63   10  9  0   10  9 21   10  9 42   10  9 63 > v2.A1
 72 | 10 18  0   10 18 21   10 18 42   10 18 63   10 27  0   10 27 21 > v2.A1
 78 | 10 27 42   10 27 63   10 36  0   10 36 21   10 36 42   10 36 63 > v2.A1
 84 | 10 45  0   10 45 21   10 45 42   10 45 63   10 54  0   10 54 21 > v2.A1
 90 | 10 54 42   10 54 63   10 63  0   10 63 21   10 63 42   10 63 63 > v2.A1
 96 | 21  0  0   21  0 21   21  0 42   21  0 63   21  9  0   21  9 21 > v2.A1
102 | 21  9 42   21  9 63   21 18  0   21 18 21   21 18 42   21 18 63 > v2.A1
108 | 21 27  0   21 27 21   21 27 42   21 27 63   21 36  0   21 36 21 > v2.A1
114 | 21 36 42   21 36 63   21 45  0   21 45 21   21 45 42   21 45 63 > v2.A1
120 | 21 54  0   21 54 21   21 54 42   21 54 63   21 63  0   21 63 21 > v2.A1
126 | 21 63 42   21 63 63   31  0  0   31  0 21   31  0 42   31  0 63 > v2.A1
132 | 31  9  0   31  9 21   31  9 42   31  9 63   31 18  0   31 18 21 > v2.A1
138 | 31 18 42   31 18 63   31 27  0   31 27 21   31 27 42   31 27 63 > v2.A1
144 | 31 36  0   31 36 21   31 36 42   31 36 63   31 45  0   31 45 21 > v2.A1
150 | 31 45 42   31 45 63   31 54  0   31 54 21   31 54 42   31 54 63 > v2.A1
156 | 31 63  0   31 63 21   31 63 42   31 63 63   42  0  0   42  0 21 > v2.A1
162 | 42  0 42   42  0 63   42  9  0   42  9 21   42  9 42   42  9 63 > v2.A1
168 | 42 18  0   42 18 21   42 18 42   42 18 63   42 27  0   42 27 21 > v2.A1
174 | 42 27 42   42 27 63   42 36  0   42 36 21   42 36 42   42 36 63 > v2.A1
180 | 42 45  0   42 45 21   42 45 42   42 45 63   42 54  0   42 54 21 > v2.A1
186 | 42 54 42   42 54 63   42 63  0   42 63 21   42 63 42   42 63 63 > v2.A1
192 | 52  0  0   52  0 21   52  0 42   52  0 63   52  9  0   52  9 21 > v2.A1
198 | 52  9 42   52  9 63   52 18  0   52 18 21   52 18 42   52 18 63 > v2.A1
204 | 52 27  0   52 27 21   52 27 42   52 27 63   52 36  0   52 36 21 > v2.A1
210 | 52 36 42   52 36 63   52 45  0   52 45 21   52 45 42   52 45 63 > v2.A1
216 | 52 54  0   52 54 21   52 54 42   52 54 63   52 63  0   52 63 21 > v2.A1
222 | 52 63 42   52 63 63   63  0  0   63  0 21   63  0 42   63  0 63 > v2.A1
228 | 63  9  0   63  9 21   63  9 42   63  9 63   63 18  0   63 18 21 > v2.A1
234 | 63 18 42   63 18 63   63 27  0   63 27 21   63 27 42   63 27 63 > v2.A1
240 | 63 36  0   63 36 21   63 36 42   63 36 63   63 45  0   63 45 21 > v2.A1
246 | 63 45 42   63 45 63   63 54  0   63 54 21   63 54 42   63 54 63 > v2.A1
252 | 63 63  0   63 63 21   63 63 42   63 63 63                       > v2.A1
                                                                      > v2.A1

The first 16 entries in the above color table correspond to the       > v2.A1
default color palette used in v1.xx of RIPscrip and corresponds       > v2.A1
directly to the color palette used for ANSI text and EGA/VGA graphics > v2.A1
(first 16 colors).  The next 16 colors in the color table above is a  > v2.A1
16 level gray-scale used for gray-scale image output and to provide a > v2.A1
basic spectrum of grays.                                              > v2.A1
                                                                      > v2.A1
The remaining 216 entries is a "uniform distribution" of RGB colors.  > v2.A1
The actual organization of the colors is mathematically based such    > v2.A1
that an arbitrary RGB color value can be mapped to a color value in   > v2.A1
the default palette with a simple calculation (instead of searching   > v2.A1
through the entire palette for the closest entry).  This block tries  > v2.A1
to cover as many colors in the color spectrum as possible.            > v2.A1
                                                                      > v2.A1
There are four levels of Blue, eight levels of green and seven        > v2.A1
levels of red.  Each block is organized with Blue the color that      > v2.A1
changes every entry, green the next most changing, and red the        > v2.A1
least frequently changing.  If you have a RED value from 0-6, a       > v2.A1
GREEN value from 0-7 and a BLUE value from 0-3, you can easily        > v2.A1
calculate the correct palette index entry with the following          > v2.A1
equation:                                                             > v2.A1
                                                                      > v2.A1
            INDEX = 32 + BLUE + GREEN*4 + RED*32                      > v2.A1
                                                                      > v2.A1
Or in C with bit-shifting, you could do it like this:                 > v2.A1
                                                                      > v2.A1
            INDEX = 32 + BLUE + GREEN<<2 + RED<<5                     > v2.A1
                                                                      > v2.A1
The main reason for choosing this color palette was to facilitate the > v2.A1
ability to display many color images onto the screen at the same time > v2.A1
in 256 color mode without having to alter the color palette for each  > v2.A1
image.  The color representation may not be 100% exact, but it would  > v2.A1
be close enough with dithering to accurately represent the original   > v2.A1
image.                                                                > v2.A1






===================================================================== > v2.A1
==                  AUDIO (SOUND & MUSIC) FORMATS                  == > v2.A1
===================================================================== > v2.A1
                                                                      > v2.A1
This section of the RIPscrip 2.0 specification is currently under     > v2.A1
research and will be completed shortly.                               > v2.A1






=====================================================================
==              RIPscrip PROTOCOL - GENERAL STRUCTURE              ==
=====================================================================

RIPscrip is organized into 10 levels of graphical commands (low
Level-0 to high Level-9).  Level-0 commands are the building blocks
of RIPscrip.  The basic graphics primitives of the system are all
Level-0, including the commands Line, Rectangle, Circle, Color, Font,
etc.  Each level of RIPscrip gets progressively higher-level in
concept.  For example, Level-1 commands use Mouse Regions, Icons, and
Formatted Text Regions.

The basic syntax rules are as follows:

1.  A RIPscrip command line starts at the beginning of a line of
    text.  A RIPscrip command line moved to the middle of a line of
    text is treated as literal text. This prevents people inserting
    mischievous things in teleconference messages, or similar pranks.
    The only exceptions to this rule is stated below under item 6,
    "continuation of long lines", and item 12 "alternate RIPscrip
    starting sequences".

2.  A RIPscrip command line begins with an exclamation mark (!).

3.  Every RIPscrip command is preceded by the universal RIPscrip
    delimiter, vertical-bar (|)

4.  Individual RIPscrip commands may be combined on the same line
    providing they are separated by the vertical bar delimiter.
    There are some exceptions to this (RIP_ENTER_BLOCK_MODE, and      > v2.A1
    a few others).  See individual command descriptions for           > v2.A1
    exceptions.                                                       > v2.A1

5.  RIPscrip commands or command lines may be split across multiple
    lines with a backslash (\) just before each split.  This helps
    RIPscrip commands conform to right margins and escape word
    wrapping.

          An example:

               !|c02|L02030405|P0901020102010201020102\
               0102010201020102

6.  RIPscrip must allow for normal text to be intermixed with
    RIPscrip commands.  If unrecognized text appears after a RIPscrip
    command, on the same line, the text is ignored (the command is
    not ignored).  A line that does not begin with "!|" is considered
    raw text and is routed to the TTY text window (see "8" below).

7.  RIPscrip makes provisions for multiple Graphical Windows and      > v2.A1
    multiple Text Windows.  A Graphical Window is where all RIPscrip  > v2.A1
    graphics appear.  A Text Window is where raw text appears.  Raw
    Text includes ANSI color and cursor movement codes (a subset of
    VT-100 terminal emulation).


8.  The vertical bar (|) of a RIPscrip command can be followed by a
    level number.  If the 1st character after (|) is a numeric digit
    (1-9), then that's the RIPscrip Command Level.  If the very 1st
    character is NOT a digit 1-9, then it is the command type
    character and the command is a Level-0 command.  If the 1st
    character is a digit 1-9, and the second character is also a
    digit, then that defines a sub-level of a RIPscrip level.  For
    example:

          !|L     RIPscrip Level-0 Command "L"
         !|1L     RIPscrip Level-1 Command "L"
        !|15L     RIPscrip Level-1, sub-level 5 Command "L"

    Each of the above examples are unique commands not to be confused
    with each other.  You may continue the sub-levels up to a maximum
    level of 9 (e.g., !|123456789<cmd>").

9.  Every RIPscrip command includes a command type character.  In
    Level-0 commands, this character immediately follows the vertical
    bar.  At all other levels, it follows the level digits.  The
    command type character may be any of the following characters:    > v2.A0
                                                                      > v2.A0
        ABCDEFGHIJKLMNOPQRSTUVWXYZ                                    > v2.A0
        abcdefghijklmnopqrstuvwxyz                                    > v2.A0
        @#$&*()[]{}<>:;'",.?-_=+                                      > v2.A0

10. Following the command type character are 0 or more parameters.
    If the command requires a text-string, it is always the LAST
    parameter.  Numeric parameters DO NOT have any delimiters
    (commas, dashes, spaces, etc.).  A variable width numeric
    parameter may be used as the last parameter.  This allows for
    maximum efficiency.

    Numbers are normally represented in base-36 (unless altered by    > v2.A0
    a RIPscrip command).  This compacts numbers down to roughly 3/5   > v2.A0
    of their decimal form.  This numbering system, technically called > v2.A0
    "Hexa-Tri-Decimal", "MegaNums".  Unlike Hexadecimal which uses    > v2.A0
    0-9, A-F, MegaNums take advantage of the entire alphabet, using   > v2.A0
    characters 0-9 and A-Z.

    See the next section about Base Math variations.                  > v2.A0

11. An exclamation mark (!) or vertical bar (|) character can appear
    in a RIPscrip text parameter by preceding it with a backslash(\).
    A literal backslash is represented with a double-backslash (\\).

12. A RIPscrip sequence CAN begin in a column other than column #0,
    if the exclamation mark prefix is replaced with a Ctrl-A (Start
    Of Header [SOH]) character, or Ctrl-B (STX) character.  Since
    99.9% of all BBS' do not allow users to enter most control
    characters, users will be unable to begin RIPscrip sequences in
    the middle of a command line.  Only the host should be able to
    do this.  This prevents people from cluttering teleconference,
    or other areas of a host with spurious RIPscrip sequences.


13. If the last couple of bytes on a RIPscrip text line are           > v1.54
    backslashes, special care must be taken to make sure that they    > v1.54
    are not interpretted as a line-continuation.  If a literal        > v1.54
    backslash is desired as the last position on the line, it must    > v1.54
    be specified as a double-backslash (eg, "\\").  If a line-        > v1.54
    continuation is used then there would have to be three            > v1.54
    backslashes used on the line as in the following example:         > v1.54
                                                                      > v1.54
        !|@2233this is a text line with a literal \\\                 > v1.54
        used in the message                                           > v1.54
                                                                      > v1.54
    This would text output at (22,33) [meganum] the message:          > v1.54
                                                                      > v1.54
       this is a text line with a literal \used in the message        > v1.54

14. Some character sequences in text parameter strings can be         > v2.A1
    misinterpreted as RIPscrip command sequences (eg, $, <>,          > v2.A1
    ((, )), [, ], [], etc).  To avoid syntax confusion these          > v2.A1
    sequences can be "escaped" to indicate that they are actually     > v2.A1
    literal sequences, not to be confused with a RIPscrip command     > v2.A1
    sequence identifier.  For example, the sequence:                  > v2.A1
                                                                      > v2.A1
          $Name$                                                      > v2.A1
                                                                      > v2.A1
    would normally be interpretted as a RIPscrip text variable that   > v2.A1
    requires the user's response.  If however, you wanted this        > v2.A1
    sequence to be interpretted as literal text, you should perform   > v2.A1
    the following escape sequences:                                   > v2.A1
                                                                      > v2.A1
          \$Name\$                                                    > v2.A1
                                                                      > v2.A1
    This makes it so a RIPscrip terminal doesn't misinterpret the     > v2.A1
    dollar signs as text variable delimiters.                         > v2.A1
                                                                      > v2.A1
15. A comment may be embedded inside a RIPscrip file.  A comment is   > v2.A1
    one line or longer in length.  A comment is a special case of a   > v2.A1
    RIPscrip command letter.  In this case, it is the command         > v2.A1
    letter "!".  If a "!" is encountered right after a "!|", a        > v2.A1
    "SOH |" or an "STX |" sequence, then the remainder of the         > v2.A1
    command line is a comment.  Comments may be line-continued        > v2.A1
    with backslashes just like regular RIPscrip commands can.  Some   > v2.A1
    examples of comments might be:                                    > v2.A1
                                                                      > v2.A1
          !|!This is a comment                                        > v2.A1
          !|c0F|!Set the color to white                               > v2.A1
          !|c0F|!this is a very long, continued\                      > v2.A1
          comment line.  Line-continued comments\                     > v2.A1
          adhere to standard RIPscrip line continuation rules         > v2.A1
                                                                      > v2.A1
    Note that the second example shows a comment starting after       > v2.A1
    a legitimate RIPscrip command (set color).  This is valid.        > v2.A1
                                                                      > v2.A1
16. Extraneous information.  If too much data is encountered for a    > v2.A1
    particular RIPscrip command, or too little information is found   > v2.A1
    (aside from a short last parameter) then the command is           > v2.A1
    considered "hopelessly corrupted" and discarded.  The RIPscrip    > v2.A1
    parser should synchronize to the next vertical bar delimiter      > v2.A1
    to begin the next command.                                        > v2.A1
                                                                      > v2.A1
17. There is no rule #17                                              > v2.A1

===================================================================== > v2.A1
==                    COMMAND GROUPING COMMENTS                    == > v2.A1
===================================================================== > v2.A1
                                                                      > v2.A1
Comments have one special usage, that is to group blocks of commands  > v2.A1
together into logical groupings.  This has no functional use to a     > v2.A1
terminal program, but to a paint program, can be used to perform      > v2.A1
block moves of commands from one area in a scene to another.  In      > v2.A1
order to accomodate this, a standardized method of doing group        > v2.A1
definitions should be defined.  A Block Group is specified with two   > v2.A1
comments, one before the command block and one immediately after.     > v2.A1
                                                                      > v2.A1
To begin a command block, specify a comment formatted like the        > v2.A1
following:                                                            > v2.A1
                                                                      > v2.A1
     !|! BEGINBLOCK(0001)                                             > v2.A1
                                                                      > v2.A1
       ...                                                            > v2.A1
       ... RIPscrip commands                                          > v2.A1
       ...                                                            > v2.A1
                                                                      > v2.A1
     !|! ENDBLOCK(0001)                                               > v2.A1
                                                                      > v2.A1
Additional comments may be added to either command and the space      > v2.A1
between the comment delimiter and the BEGINBLOCK/ENDBLOCK are not     > v2.A1
necessary.  Here's another example with additional comments:          > v2.A1
                                                                      > v2.A1
     !|! BEGINBLOCK(0001) - block of colored squares                  > v2.A1
                                                                      > v2.A1
       ...                                                            > v2.A1
       ... RIPscrip commands                                          > v2.A1
       ...                                                            > v2.A1
                                                                      > v2.A1
     !|! ENDBLOCK(0001) - end of colored square block                 > v2.A1
                                                                      > v2.A1
Additional comments are not required but are recommended for          > v2.A1
readability.  When putting RIPscrip data files online on a host, you  > v2.A1
would typically want to remove any comments for efficiency.           > v2.A1
                                                                      > v2.A1
Note that we used four-digit numbers for our block identification     > v2.A1
values.  This isn't a requirement - you could use one, two or ten     > v2.A1
eight digit identification values - the choice is up to you.          > v2.A1

===================================================================== > v2.A1
==         VIEWPORTS AND TEXT WINDOWS - OVERLAPPING ISSUES         == > v2.A1
===================================================================== > v2.A1
                                                                      > v2.A1
Since there are multiple text windows and viewports allowed in the    > v2.A1
specification, some elaboration needs to be made on what happens if   > v2.A1
any overlap each other.  Very simple, they do what they have always   > v2.A1
done - draw text, or draw graphics.  For example, if a viewport       > v2.A1
overlaps a text window and you draw some graphics (say a circle) over > v2.A1
the top of some text in a text window, and the text window            > v2.A1
subsequently scrolls, all or part of the circle could scroll with it! > v2.A1
Now, of course, from the viewport's standpoint, the graphics are no   > v2.A1
longer what you originally sent to the viewport, but that doesn't     > v2.A1
matter - you don't preserve any of the commands you used to create    > v2.A1
the graphics - you simply draw the graphics and that's it.  So with   > v2.A1
this in mind, even if multiple viewports overlap each other it        > v2.A1
doesn't matter because the final result is what's on the screen -     > v2.A1
doing things in one viewport might do some overlapping graphics in    > v2.A1
another viewport but that is alright.                                 > v2.A1
                                                                      > v2.A1
If a text window overlaps another text window, the same thing         > v2.A1
happens.  To a RIPscrip terminal, text is simply just a piece of      > v2.A1
graphical information that is being placed on the screen in a         > v2.A1
formatted fashion.  If two text windows overlap and text is placed on > v2.A1
an area that overlap the other window, then you will be drawing       > v2.A1
graphics (essentially) on top of another text window.  The same thing > v2.A1
as the circle example above would happen if that text window          > v2.A1
scrolled.                                                             > v2.A1

===================================================================== > v2.A1
==              DESCRIPTION OF RIPscrip COMMAND LEVELS             == > v2.A1
===================================================================== > v2.A1
                                                                      > v2.A1
As previously described, RIPscrip is composed of ten different levels > v2.A1
of commands.  The distribution of commands over different levels is   > v2.A1
done in a rather organized fashion based on command type.  Each level > v2.A1
of command in general, is progressively higher level in concept.  For > v2.A1
example, level 0 commands are the most basic building blocks of       > v2.A1
RIPscrip (eg, graphical primitives, protocol setup, etc).  Level one  > v2.A1
commands are simple user interface objects.  Level 2 commands are     > v2.A1
higher level still in that they deal with context swapping issues.    > v2.A1
At the highest level, level-9, we deal with binary transfer modes     > v2.A1
like file transfer protocols, etc.  A more formal definition of the   > v2.A1
currently used levels are:                                            > v2.A1
                                                                      > v2.A1
     Level     Description                                            > v2.A1
     -------------------------------------------------------------    > v2.A1
       0       Lowest-level RIPscrip primitives.  Simple graphical    > v2.A1
               drawing primitives, low-level RIPscrip protocol        > v2.A1
               mode settings, etc.                                    > v2.A1
       1       Simple user interface objects (buttons, mouse          > v2.A1
               fields, clipboards, formatted text regions).  This     > v2.A1
               level consolidates one or more simple building         > v2.A1
               blocks from level 0 and also introduces more           > v2.A1
               abstract user interface objects (eg, mouse fields).    > v2.A1
       2       Basic context switching information (switching         > v2.A1
               styles, and other window or context senstive           > v2.A1
               commands.                                              > v2.A1
       3       Basic time-related commands (baud rate emulations,     > v2.A1
               delay related commands, and animation facilities).     > v2.A1
                                                                      > v2.A1
       4       Open for future development                            > v2.A1
                                                                      > v2.A1
       5       Open for future development                            > v2.A1
                                                                      > v2.A1
       6       Open for future development                            > v2.A1
                                                                      > v2.A1
       7       Open for future development                            > v2.A1
                                                                      > v2.A1
       8       Open for future development                            > v2.A1
                                                                      > v2.A1
       9       Binary related data transfer functions (ie, block      > v2.A1
               protocol modes, UU-encoding, etc).                     > v2.A1

===================================================================== > v2.A0
==                       BASE MATH VARIATIONS                      == > v2.A0
===================================================================== > v2.A0
                                                                      > v2.A0
Throughout the RIPscrip specification, numeric parameters are used    > v2.A0
extensively to indicate where to draw things, how to draw things and  > v2.A0
various other pieces of information.  For compactness, we do not use  > v2.A0
numbers that are normal decimal numbers (base-10).  By default,       > v2.A0
RIPscrip uses base-36 numbers (Hexa-Tri-Decimal or more fondly,       > v2.A0
MegaNums) which use the digits 0-9 followed by A-Z.  This was the     > v2.A0
original numbering system used in the 1.xx specification.             > v2.A0
                                                                      > v2.A0
In the 2.xx specification, the base math can be altered to something  > v2.A0
other than base-36!  With v2.xx, we are introducing a new numbering   > v2.A0
scheme that is base-64, otherwise known as Quadra-Hexa-Decimal, or    > v2.A0
more fondly known as UltraNums.  UltraNums use the following digits:  > v2.A0
                                                                      > v2.A0
                         0-9  A-Z  a-z  #  @                          > v2.A0
                                                                      > v2.A0
With this numbering scheme, you can squeeze larger numbers into an    > v2.A0
even smaller space than MegaNums!  Here is a table showing how big of > v2.A0
a number can be contained with X number of digits:                    > v2.A0
                                                                      > v2.A0
            Decimal   Hexa-Decimal     MegaNums       UltraNums       > v2.A0
           +----------------------------------------------------+     > v2.A0
          1|      9 |           15 |         35 |            63 |     > v2.A0
Total     2|     99 |          255 |       1295 |          4095 |     > v2.A0
Digits    3|    999 |         4095 |     46,655 |       262,143 |     > v2.A0
          4|   9999 |       65,535 |  1,679,615 |    16,777,216 |     > v2.A0
          5| 99,999 |    1,048,576 | 60,466,176 | 1,073,741,824 |     > v2.A0
           +----------------------------------------------------+     > v2.A0
                                                                      > v2.A0
A RIPscrip Header command can be used to specify the global base math > v2.A0
used throughout the command sets.  By altering the base math, you can > v2.A0
make a single numeric parameter accept larger values without          > v2.A0
expanding the parameter in the specification.  A couple of the        > v2.A0
RIPscrip commands utilize specific base math values (eg, UltraNums,   > v2.A0
etc) under certain circumstances.  Any commands that are exceptions   > v2.A0
like this will be clearly documented as being exceptions to the rule. > v2.A0
                                                                      > v2.A0

The following is a basic table of Decimal, MegaNum and UltraNum       > v2.A0
values:                                                               > v2.A0
                                                                      > v2.A0
    Decimal   MegaNum   UltraNum      Decimal   MegaNum   UltraNum    > v2.A0
    ----------------------------      ----------------------------    > v2.A0
      00          0        0            32          0W       W        > v2.A0
      01          01       1            33          0X       X        > v2.A0
      02          02       2            34          0Y       Y        > v2.A0
      03          03       3            35          0Z       Z        > v2.A0
      04          04       4            36          10       a        > v2.A0
      05          05       5            37          11       b        > v2.A0
      06          06       6            38          12       c        > v2.A0
      07          07       7            39          13       d        > v2.A0
      08          08       8            40          14       e        > v2.A0
      09          09       9            41          15       f        > v2.A0
      10          0A       A            42          16       g        > v2.A0
      11          0B       B            43          17       h        > v2.A0
      12          0C       C            44          18       i        > v2.A0
      13          0D       D            45          19       j        > v2.A0
      14          0E       E            46          1A       k        > v2.A0
      15          0F       F            47          1B       l        > v2.A0
      16          0G       G            48          1C       m        > v2.A0
      17          0H       H            49          1D       n        > v2.A0
      18          0I       I            50          1E       o        > v2.A0
      19          0J       J            51          1F       p        > v2.A0
      20          0K       K            52          1G       q        > v2.A0
      21          0L       L            53          1H       r        > v2.A0
      22          0M       M            54          1I       s        > v2.A0
      23          0N       N            55          1J       t        > v2.A0
      24          0O       O            56          1K       u        > v2.A0
      25          0P       P            57          1L       v        > v2.A0
      26          0Q       Q            58          1M       w        > v2.A0
      27          0R       R            59          1N       x        > v2.A0
      28          0S       S            60          1O       y        > v2.A0
      29          0T       T            61          1P       z        > v2.A0
      30          0U       U            62          1Q       #        > v2.A0
      31          0V       V            63          1R       @        > v2.A0
                                                                      > v2.A0
The following C code fragment provides you with a way of converting   > v2.A0
decimal numbers to an UltraNum format:                                > v2.A0
                                                                      > v2.A0
     char ultra_num_table[64] = {                                     > v2.A0
          '0', '1', '2', '3', '4', '5', '6', '7',                     > v2.A0
          '8', '9', 'A', 'B', 'C', 'D', 'E', 'F',                     > v2.A0
          'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N',                     > v2.A0
          'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V',                     > v2.A0
          'W', 'X', 'Y', 'Z', 'a', 'b', 'c', 'd',                     > v2.A0
          'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l',                     > v2.A0
          'm', 'n', 'o', 'p', 'q', 'r', 's', 't',                     > v2.A0
          'u', 'v', 'w', 'x', 'y', 'z', '#', '@'                      > v2.A0
     };                                                               > v2.A0
                                                                      > v2.A0

     char *Dec2Ultra(long value)                                      > v2.A0
     {                                                                > v2.A0
          static char buf[8];                                         > v2.A0
          int    part, pos=0;                                         > v2.A0
                                                                      > v2.A0
          setmem(buf, 0, 8);                                          > v2.A0
                                                                      > v2.A0
          while (value >= 64L) {                                      > v2.A0
               part       = value & 0x003Fl;                          > v2.A0
               value      = value >> 6;                               > v2.A0
               buf[pos++] = ultra_num_table[part];                    > v2.A0
          }                                                           > v2.A0
                                                                      > v2.A0
          if (value) {                                                > v2.A0
               buf[pos++] = ultra_num_table[value];                   > v2.A0
          }                                                           > v2.A0
                                                                      > v2.A0
          strrev(buf);                                                > v2.A0
          return(buf);                                                > v2.A0
     }                                                                > v2.A0

=====================================================================
==                   ANSI SEQUENCES (AUTO-SENSING)                 ==
=====================================================================

RIPscrip predominantly uses non-ANSI command sequences.  In a couple
of situations though, an ANSI sequence is allowed to perform a
specific function.  There are currently three separate ANSI sequences
defined in the RIPscrip protocol to perform various actions.  They
are as follows:

ESC[!     Query RIPscrip version number.  RIPterm will respond with   > v1.54
          RIPSCRIPxxyyvs where "xx" is equal to the major version     > v1.54
          number (zero padded), "yy" is equal to the minor version    > v1.54
          number (zero padded), "v" is the vendor code of the         > v1.54
          terminal program (see below), and "s" is the vendor's       > v1.54
          sub-version code for their software.  For v1.54, the        > v1.54
          returned sequence for RIPterm (Vendor Code "1") would be    > v1.54
          RIPSCRIP015410.  Another example, v1.23 with a Vendor Code  > v1.54
          of "2" and a sub-revision code of "5" would return          > v1.54
          RIPSCRIP012325.                                             > v1.54
                                                                      > v1.54
          Valid Vendor Codes are:                                     > v1.54
                                                                      > v1.54
               CODE   VENDOR                                          > v1.54
               =================================================      > v1.54
                 0    Generic RIPscrip terminal (vendor unknown)      > v1.54
                 1    RIPterm (from TeleGrafix Communications)        > v1.54
                 2    Qmodem Pro (from Mustang Software, Inc)         > v1.54
                 3    deltaComm Development (Telix)                   > v2.A1
                 4    Qmodem Pro for Windows (Mustang Software)       > v2.A1
                                                                      > v1.54
          This ANSI sequence is often used for "Auto-Sensing" if a    > v1.54
          RIPscrip terminal exists on the remote end of the           > v1.54
          connection.  If a non-RIPscrip terminal receives this       > v1.54
          ANSI sequence, it will ignore it.                           > v1.54

          NOTE:  This method of vendor determination is obsolete      > v2.A1
                 in RIPscrip 2.0.  See the section Pre-Defined        > v2.A1
                 Text variables for Vendor specific text variables    > v2.A1
                 which can be used more generically to determine      > v2.A1
                 a specific terminal vendor (eg, $TERMVEND$,          > v2.A1
                 $TERMVER$, $TERMMFG$ and $TERMDATA$).                > v2.A1

ESC[0!    Same as ESC [ ! (see above)

ESC[1!    Disables all RIPscrip processing.  Any RIPscrip sequences
          are interpreted as raw text.

ESC[2!    Enabled RIPscrip processing.  Any RIPscrip sequences will
          be parsed and processed.

=====================================================================
==                 MISCELLANEOUS NOTES/INFORMATION                 ==
=====================================================================

Later in this document, references are made to Mouse Fields and Mouse > v1.54
Buttons.  Specifically, it is noted that up to 128 of these types of  > v1.54
commands may exist simultaneously on-screen.  This means that you can > v1.54
have 128 mouse fields, 128 mouse buttons, or any combination of the   > v1.54
above, but combined, their total number cannot exceed 128.            > v1.54

When the user clicks his/her mouse on the screen, all mouse regions   > v1.54
(whether mouse fields or mouse buttons) are scanned from most recent  > v1.54
to the least recent.  This means that if a mouse region is received   > v1.54
that overlaps another mouse region, that one would be clicked first   > v1.54
if the user clicked in that region.                                   > v1.54

If you are implementing a client terminal to support RIPscrip         > v1.54
graphics and you do not intend on supporting 100% of all pre-defined  > v1.54
text variables, you SHOULD at least recognize them and do nothing.    > v1.54
This makes it so that if a particular text variable is used to make   > v1.54
a sound (for example), then if you don't support it, you just ignore  > v1.54
it instead of popping up a dialog box on your user's screen asking    > v1.54
them to enter data for the variable $MUSIC$ for example!              > v1.54

NOTE:  Many of the text variables like $PCB$ and other key variables  > v2.A1
       are very important to GUI design and should be implemented!    > v2.A1
       If you are going to omit any of the text variable, do not      > v2.A1
       omit any of the active text variables - these are CRITICAL     > v2.A1
       to implementing a full GUI system using RIPscrip 2.0!!!        > v2.A1

=====================================================================
==                    RIPscrip COMMAND REFERENCE                   ==
=====================================================================

The remainder of this document details the RIPscrip command set.
Each command has these aspects:

    SYMBOL - the symbolic constant that is referenced in the
             RIPscrip API Library code.  This is  the universal
             name for the command.

     LEVEL - The Command Level.  Sub-levels are represented
             with decimal points (eg, 1.3.5 for Level-1,
             Sub-level 3, Sub-Sub-level 5).  This is for
             discussion purposes only.  The decimal points
             are never part of the actual command.

   COMMAND - The command type character identifying the
             command

 ARGUMENTS - The arguments or parameters for the command.
             Commands that do not require any arguments
             after the command type character are shown
             here as "<none>".  Each argument is shown in
             the order it appears in the command, and is
             represented by a name.  If an argument is
             numeric, it is followed by a width specifier
             indicating how many MegaNum digits the
             argument consists of.  (eg, ":2" means a
             2-digit MegaNum, or a value between 0 and
             1295).  If an argument does not have a width
             specifier, it is by default a text argument,
             and should be the last argument on the line.
             If a command is variable length (see POLYGON),
             then it will appear with ellipses (...)

    FORMAT - This represents the format of the command, with
             the starting "!|", the level digits, the
             command type character, and the argument list,
             with the argument names in angle brackets.
             (These arguments are spaced apart, but these
             spaces never appear in the physical commands.)

   EXAMPLE - An actual example of the RIPscrip command.

DRAW COLOR - If YES, then this command uses or affects the
             current Drawing Color.

BACK COLOR - If YES, then this command uses (or can use) the          > v2.A1
             current background pen drawing color.                    > v2.A1

LINE PATRN - If YES, then this command uses or affects the
             current Line Style Pattern.

LINE THICK - If YES, then this command uses or affects the
             current Line Style Thickness

FILL COLOR - If YES, then this command uses or affects the
             current Fill Color.

FILL PATRN - If YES, then this command uses or affects the
             current Fill Pattern.


WRITE MODE - If YES, then this command will take advantage
             of the current Write Mode (eg, COPY, or XOR).

FONT SIZES - If YES, then this command uses or affects the
             current Font Size.

VIEWPORT   - If YES, then this command adheres to the                 > v1.54
             graphical viewport (draws inside it).  Any               > v1.54
             RIPscrip command that adheres to the graphical           > v1.54
             viewport will be drawn (when received) only              > v1.54
             if the viewport is defined.  If the viewport             > v1.54
             is not defined (0,0,0,0), then the command is            > v1.54
             parsed, but completely ignored.                          > v1.54





=====================================================================
==                          LEVEL-0 COMMANDS                       ==
=====================================================================

--------------------------------------------------------------------- > v2.A1
RIP_HEADER                                                            > v2.A1
--------------------------------------------------------------------- > v2.A1
         Function:  Header command for subsequent RIPscrip sequence   > v2.A1
            Level:  0                                                 > v2.A1
          Command:  h                                                 > v2.A1
        Arguments:  flags:4 revision:2 res:2                          > v2.A1
           Format:  !|h <flags> <revision> <res>                      > v2.A1
          Example:  !|h000A0100                                       > v2.A1
  Uses Draw Color:  NO                                                > v2.A1
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO                                                > v2.A1
  Uses Line Thick:  NO                                                > v2.A1
  Uses Fill Color:  NO                                                > v2.A1
Uses Fill Pattern:  NO                                                > v2.A1
  Uses Write Mode:  NO                                                > v2.A1
  Uses Font Sizes:  NO                                                > v2.A1
    Uses Viewport:  NO                                                > v2.A1
                                                                      > v2.A1
This command was introduced in RIPscrip 2.0.  It is specifically      > v2.A1
designed with two purposes in mind.  Firstly, it is defined to        > v2.A1
provide a consistent method for determining the revision of RIPscrip  > v2.A1
that is to follow in subsequent RIPscrip code.  Secondly, it provides > v2.A1
a way of performing many different kinds of reset operations (if any) > v2.A1
in one command - much more flexible then the older RIP_RESET_WINDOWS  > v2.A1
command.  This command has the ability to set many states and         > v2.A1
situations for subsequent RIPscrip code (whether MegaNums are to be   > v2.A1
used, or UltraNums, what gets reset and what doesn't, etc).           > v2.A1
                                                                      > v2.A1
The <revision> code of this command defines the revision of RIPscrip  > v2.A1
code that is to follow.  The valid defined revisions are as follows:  > v2.A1
                                                                      > v2.A1
               Revision  Description                                  > v2.A1
               -------------------------------                        > v2.A1
                  00     RIPscrip 1.54.00 code                        > v2.A1
                  01     RIPscrip 2.00.00 code                        > v2.A1
                                                                      > v2.A1
The real heart of this command is the <flags> parameter.  This field  > v2.A1
defines all of the attributes of the header command other then the    > v2.A1
revision field.  The possible values which may be combined in this    > v2.A1
parameter (OR'ed together) are as follows:                            > v2.A1
                                                                      > v2.A1
      Value   Description                                             > v2.A1
     ---------------------------------------------------------------  > v2.A1
          0   Do nothing                                              > v2.A1
              ------------------------------------------------------  > v2.A1
          1   Use MegaNums for subsequent RIPscrip code               > v2.A1
          2   Use UltraNums for subsequent RIPscrip code              > v2.A1
          4   Auto-set world coordinate frame                         > v2.A1
          8   Set world frame to 640x350 (backward compatible mode)   > v2.A1
              ------------------------------------------------------  > v2.A1

         16   Perform a hard reset - this resets everything.  This    > v2.A1
              includes clearing all save/restore/stack slots, and     > v2.A1
              data slots (graphical style slots, button slots, etc).  > v2.A1
         32   This performs a soft reset.  The screen is cleared,     > v2.A1
              all viewports are reset and viewport slot 0 is made     > v2.A1
              full screen, text windows are deleted and text          > v2.A1
              window 0 is made full screen.  All resident queries     > v2.A1
              are deleted, graphical style slots are erased as are    > v2.A1
              the button style slots.  This is identical in nature    > v2.A1
              to the RIP_RESET_WINDOWS.                               > v2.A1
              ------------------------------------------------------  > v2.A1
         64   Clears clipboard pages only                             > v2.A1
        128   Clears resident queries only                            > v2.A1
        256   Clears mouse/button definitions only                    > v2.A1
        512   Clears all slot related save/restore areas and reset    > v2.A1
              stack slot numbers to 0.                                > v2.A1
       1024   Clears all slot-less save/restore areas.                > v2.A1
       2048   Clears any currently defined/running animation          > v2.A1
       4096   Clears and stops any playing sound/music                > v2.A1
       8192   Clears the entire screen to background color            > v2.A1
      16384   Clears all viewport definitions and makes viewport 0    > v2.A1
              full screen (no screen clearing performed)              > v2.A1
      32768   Clears all text window definitions and makes text       > v2.A1
              window 0 full screen (no window clearing performed)     > v2.A1
      65536   Clears all graphical style slots                        > v2.A1
     131072   Clears all button style slots                           > v2.A1
              ------------------------------------------------------  > v2.A1
     262144   All existing viewports are erased.  If combined with    > v2.A1
              flag 16384, then this is done first, then flag 16384    > v2.A1
              is executed.                                            > v2.A1
     524288   All existing text windows are erased.  If combined      > v2.A1
              with flag 32768, then this is done first, then flag     > v2.A1
              32768 is executed.                                      > v2.A1
              ------------------------------------------------------  > v2.A1
    1048576   Disables all mouse/keyboard input (discards) until a    > v2.A1
              RIP_NO_MORE command is encountered thus signifying the  > v2.A1
              end of a RIPscrip sequence.  This prevents the user     > v2.A1
              from accidentally interrupting the data stream with     > v2.A1
              keyboard activity.  The mouse cursor should be changed  > v2.A1
              to something like an hourglass or disabled entirely.    > v2.A1
              If no RIP_NO_MORE is found and no RIPscrip or raw text  > v2.A1
              data is being received, then a RIP_NO_MORE should be    > v2.A1
              assumed after some suitable timeout (up to the          > v2.A1
              developer's discretion).                                > v2.A1
                                                                      > v2.A1
As you can see, the <flags> parameter allows you to reset only        > v2.A1
segments of things that you want to reset giving you considerable     > v2.A1
flexibility in starting off RIPscrip scenes.                          > v2.A1
                                                                      > v2.A1
Most of the flag options are fairly self-explanatory.  Some mention   > v2.A1
should be made to several of them.  Note that the flags described     > v2.A1
above are grouped into logically related flags.  Flags 1 and 2 are    > v2.A1
mutually exlusive meaning only "1" or "2" may be used, but not both.  > v2.A1
Choosing either flag 1 or 2 resets coordinate sizes to 2 bytes.       > v2.A1
                                                                      > v2.A1

Flag 4 requires some explanation.  Auto-setting the world coordinate  > v2.A1
frame will auto-set the world coordinate frame to a set of            > v2.A1
high-resolution world coordinates.  The exact choices of coordinates  > v2.A1
chosen depend on whether you specified UltraNums or MegaNums.  If you > v2.A1
specify flag 4, then you must specify either flag 1 or flag 2 to      > v2.A1
determine which base math to use.  MegaNums set the width of the      > v2.A1
world coordinate frame to 1296 (maximum size of 2 meganums), and set  > v2.A1
the height of the world 972.  This provides for a square world frame  > v2.A1
pixels.  If UltraNums are used, then the width of the world frame is  > v2.A1
set to 4096 and the height is set to 3072.  Again, this provides for  > v2.A1
square world frame pixels.  If you physically need a larger world     > v2.A1
frame then you either need to alter the base math setting explicitly  > v2.A1
or alter the X/Y coordinate parameter size (see the next few          > v2.A1
commands).                                                            > v2.A1
                                                                      > v2.A1
The Hard Reset option (flag 16) will perform a complete reset of the  > v2.A1
RIPscrip environment.  This is equivalent to choosing flags 64        > v2.A1
through 524288.  In effect, this clears everything including          > v2.A1
save/restore slots and slotless save areas.                           > v2.A1
                                                                      > v2.A1
The Soft Reset option (flag 32) will perform a reset that is          > v2.A1
identical in nature to the RIP_RESET_WINDOWS reset.  This is          > v2.A1
equivalent to choosing flags 1, 8, 64, 128, and 2048 through 131072.  > v2.A1
This doesn't deleted any save/restore slots or slot-less regions,     > v2.A1
doesn't intentionally affect the world frame except that it sets it   > v2.A1
to 640x350, and chooses MegaNums as the numbers of choice.            > v2.A1





--------------------------------------------------------------------- > v2.A0
RIP_SET_BASE_MATH                                                     > v2.A0
--------------------------------------------------------------------- > v2.A0
         Function:  Sets the base math for most RIPscrip parameters   > v2.A0
            Level:  0                                                 > v2.A0
          Command:  b                                                 > v2.A0
        Arguments:  base_math:2                                       > v2.A0
           Format:  !|b <base_math>                                   > v2.A0
          Example:  !|b036                                            > v2.A0
  Uses Draw Color:  NO                                                > v2.A0
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO                                                > v2.A0
  Uses Line Thick:  NO                                                > v2.A0
  Uses Fill Color:  NO                                                > v2.A0
Uses Fill Pattern:  NO                                                > v2.A0
  Uses Write Mode:  NO                                                > v2.A0
  Uses Font Sizes:  NO                                                > v2.A0
    Uses Viewport:  NO                                                > v2.A0
                                                                      > v2.A0
This command sets the Base Math used extensively throughout the       > v2.A0
RIPscrip language.  By default, the RIPscrip language used Base-36    > v2.A0
math for all of its numeric parameters.  This number can be changed   > v2.A0
to accomodate larger values for numeric parameters.  For example, a   > v2.A0
two digit base-36 number can hold a number from 0-1295.  A Base-64    > v2.A0
number can hold a number from 0-4095 which is considerably larger.    > v2.A0
                                                                      > v2.A0
This can be used when you set the World Coordinate Frame to larger    > v2.A0
coordinates, even larger than 1024x1024.  Altering the Base Math of   > v2.A0
the parameters gives you the ability to handle larger numbers without > v2.A0
expanding the size (byte-wise) of parameters throughout the language. > v2.A0
                                                                      > v2.A0
NOTE:  This command ALWAYS uses base-36 (MegaNum) math for            > v2.A0
       its parameter.  The reason for this is that this is a          > v2.A0
       universal command, and the Base Math may not be known          > v2.A0
       at the moment the command is received.                         > v2.A0
                                                                      > v2.A0
When a RIP_RESET_WINDOWS command is received, the base math is reset  > v2.A0
to Base-36 (MegaNum) values.  If a scene is received after the Reset  > v2.A0
Windows command and it uses Base Math other than Base-36, then you    > v2.A0
MUST send a RIP_SET_BASE_MATH command immediately after the           > v2.A0
RIP_RESET_WINDOWS command.                                            > v2.A0
                                                                      > v2.A0
The valid settings at this time are:                                  > v2.A0
                                                                      > v2.A0
     Base-36 ("10" meganum)                                           > v2.A0
     Base-64 ("1S" meganum)                                           > v2.A0
                                                                      > v2.A0
If an illegal Set Base Math command is received (an illegal base math > v2.A0
setting), RIPscrip will default to MegaNums.                          > v2.A0





--------------------------------------------------------------------- > v2.A1
RIP_SET_COORDINATE_SIZE                                               > v2.A1
--------------------------------------------------------------------- > v2.A1
         Function:  Sets the base math for most RIPscrip parameters   > v2.A1
            Level:  0                                                 > v2.A1
          Command:  n                                                 > v2.A1
        Arguments:  byte_size:1 res:3                                 > v2.A1
           Format:  !|n <byte_size> <res>                             > v2.A1
          Example:  !|n2000                                           > v2.A1
  Uses Draw Color:  NO                                                > v2.A1
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO                                                > v2.A1
  Uses Line Thick:  NO                                                > v2.A1
  Uses Fill Color:  NO                                                > v2.A1
Uses Fill Pattern:  NO                                                > v2.A1
  Uses Write Mode:  NO                                                > v2.A1
  Uses Font Sizes:  NO                                                > v2.A1
    Uses Viewport:  NO                                                > v2.A1
                                                                      > v2.A1
This command alters the number of bytes that will be expected for all > v2.A1
subsequent X or Y parameters in RIPscrip.  By default, all X or Y     > v2.A1
parameters are two bytes in length as denoted syntax-wise as x:2 or   > v2.A1
y:2 in the specification.  This command allows you to alter this      > v2.A1
size.  In 1.x versions of RIPscrip, the maximum size of a parameter   > v2.A1
was in the X direction and the maximum value was 639.  This could     > v2.A1
safely be represented in two meganum digits.  In 2.0 of RIPscrip and  > v2.A1
beyond, we introduce a world coordinate system into the specification > v2.A1
which allows you to use a much higher resolution for your drawing     > v2.A1
environment.  This facilitates resolution independence.  To provide   > v2.A1
for future expandability when ultra-high resolution devices might     > v2.A1
exist, the possibility of an X or Y coordinate exceeding 4095 might   > v2.A1
occur.  Since this is the largest value that can be accomodated in a  > v2.A1
2-byte UltraNum, we offer an option that provides this flexibility.   > v2.A1
                                                                      > v2.A1
Using this parameter to expand the byte size beyond 2 will make a     > v2.A1
RIPscrip file bigger.  This is because every X/Y coordinate will be   > v2.A1
expanded in size by a certain number of bytes, and since these are    > v2.A1
the fundamental values in any graphical environment, it will result   > v2.A1
in larger RIPscrip files.  In practice, this command should be used   > v2.A1
with caution.  When situations permit, do not use this command, or    > v2.A1
use it with a byte size of 2 (the default).  This will keep files     > v2.A1
from ever getting larger than they would be default.                  > v2.A1
                                                                      > v2.A1
There is nothing stopping you from setting this value to 1.  If you   > v2.A1
do this though, your coordinate sizes will never get larger than 35   > v2.A1
for MegaNums, or 63 for UltraNums.  Coordinates in this range though  > v2.A1
are hardly useful in a realistic environment, so we don't think that  > v2.A1
they will be used (if at all).                                        > v2.A1
                                                                      > v2.A1
A RIP_RESET_WINDOWS command will reset the coordinate size back to    > v2.A1
two bytes wide parameters.                                            > v2.A1
                                                                      > v2.A1
NOTE:  The <res> parameter is reserved and should be set to "000"     > v2.A1
       for future expansion by TeleGrafix.                            > v2.A1




--------------------------------------------------------------------- > v2.A0
RIP_SET_WORLD_FRAME                                                   > v2.A0
--------------------------------------------------------------------- > v2.A0
         Function:  Sets the coordinates for the World Frame          > v2.A0
            Level:  0                                                 > v2.A0
          Command:  r                                                 > v2.A0
        Arguments:  x_dim:2 y_dim:2                                   > v2.A0
           Format:  !|r <x_dim> <y_dim>                               > v2.A0
          Example:  !|rSGSG                                           > v2.A0
  Uses Draw Color:  NO                                                > v2.A0
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO                                                > v2.A0
  Uses Line Thick:  NO                                                > v2.A0
  Uses Fill Color:  NO                                                > v2.A0
Uses Fill Pattern:  NO                                                > v2.A0
  Uses Write Mode:  NO                                                > v2.A0
  Uses Font Sizes:  NO                                                > v2.A0
    Uses Viewport:  NO                                                > v2.A0
                                                                      > v2.A0
This command sets the dimensions of the World Coordinate Frame.  This > v2.A0
Frame is the Global Coordinate Space of the RIPscrip drawing screen.  > v2.A0
It is not the exact size of the Device Frame - that is a lower level  > v2.A0
coordinate system.  With this frame, you can "map" your scenes into   > v2.A0
something, say a 1024x1024 grid and let the terminal worry about      > v2.A0
mapping it into whatever device coordinates it is using (eg, 640x350, > v2.A0
800x600, etc).  Any coordinates used for setting viewports or other   > v2.A0
such things will be specified in World Frame Coordinates.  Actual     > v2.A0
drawing primitives will use the current Drawing Frame's coordinates - > v2.A0
another level of coordinate mapping.  This allows you to do things    > v2.A0
like draw full screen images inside a tinier window, leaving          > v2.A0
additional drawing space on the screen for other images.              > v2.A0
                                                                      > v2.A0
The actual Device Coordinate Frame is not specified in the RIPscrip   > v2.A0
language anywhere - it is handled entirely by the remote terminal,    > v2.A0
because only it knows the device coordinates of the environment that  > v2.A0
it is running under.                                                  > v2.A0
                                                                      > v2.A0
The <x_dim> parameter is how wide the drawing area is in logical      > v2.A0
coordinates.  The <y_dim> parameter is how tall the drawing area is   > v2.A0
in logical coordinates.                                               > v2.A0
                                                                      > v2.A0
To translate from World Coordinates to Device Coordinates, you need   > v2.A0
to know four things:                                                  > v2.A0
                                                                      > v2.A0
     1/2) The World Frame's dimensions (ie, x_dim and y_dim)          > v2.A0
     3/4) The dimensions of the actual display device (x_max, y_max)  > v2.A0
                                                                      > v2.A0
After you have these four values, you can translate any X/Y           > v2.A0
coordinate pair in World Coordinates to Device Coordinates with the   > v2.A0
following equations:                                                  > v2.A0
                                                                      > v2.A0
  EQUATION 1 - TRANSLATE WORLD TO DEVICE COORDINATES                  > v2.A0
  --------------------------------------------------                  > v2.A0
              _______________________________________                 > v2.A0
             |                   |                   |                > v2.A0
             |       Xw * x_max  |       Yw * y_max  |                > v2.A0
             |  Xd = ----------  |  Yd = ----------  |                > v2.A0
             |         x_dim     |         y_dim     |                > v2.A0
             |___________________|___________________|                > v2.A0
                                                                      > v2.A0

Where (Xw,Yw) is a point in World Coordinates.  We are solving for    > v2.A0
the point (Xd,Yd) which is in Device Coordinates.  The values         > v2.A0
x_max and y_max are the physical dimensions of the display device     > v2.A0
(eg, x_max=640, y_max=350).  The values x_dim and y_dim are the       > v2.A0
dimensions of the World Coordinate Frame (eg, x_dim=1000,             > v2.A0
y_dim=1000).                                                          > v2.A0
                                                                      > v2.A0
As an example, let's say we are drawing onto a 640x350 display device > v2.A0
and our World Coordinate Frame is 1000x1000 logical pixels in size.   > v2.A0
If we plot a pixel at coordinates right in the middle of the screen   > v2.A0
at (500,500), here is what we would have:                             > v2.A0
                                                                      > v2.A0
                       500 * 640   320,000                            > v2.A0
                  Xd = --------- = ------- = 320                      > v2.A0
                         1000       1000                              > v2.A0
                                                                      > v2.A0
                                                                      > v2.A0
                       500 * 350   175,000                            > v2.A0
                  Yd = --------- = ------- = 175                      > v2.A0
                         1000       1000                              > v2.A0
                                                                      > v2.A0
This gives us a final Device coordinate of (320,175) which is smack   > v2.A0
in the middle of the device screen as we wanted.                      > v2.A0
                                                                      > v2.A0
If we solve the above equations for Xw and Yw, we get the inverse     > v2.A0
equations - translations from Device Coordinates to World             > v2.A0
Coordinates:                                                          > v2.A0
                                                                      > v2.A0
  EQUATION 2 - TRANSLATE DEVICE TO WORLD COORDINATES                  > v2.A0
  --------------------------------------------------                  > v2.A0
              _______________________________________                 > v2.A0
             |                   |                   |                > v2.A0
             |       Xd * x_dim  |       Yd * y_dim  |                > v2.A0
             |  Xw = ----------  |  Yw = ----------  |                > v2.A0
             |         x_max     |         y_max     |                > v2.A0
             |___________________|___________________|                > v2.A0
                                                                      > v2.A0
If the World Coordinates are larger than the Device Coordinates, then > v2.A0
when you translate World Coordinates to Device Coordinates, there     > v2.A0
will be pixel-perfect translation.  This means that translation will  > v2.A0
be unambiguous - they will convert to pixel coordinates without there > v2.A0
being any discrepency.  For example, if your Device Coordinates are   > v2.A0
640x350 and your World Coordinates are 1280x700, then a Point in      > v2.A0
World Coordinate space at (0,0) and (1,0) will both translate to the  > v2.A0
Device Coordinates (0,0) and (0,0) respectively.  This is because the > v2.A0
World Coordinate space is twice as large as the Device Coordinate     > v2.A0
space.  If on the other hand the Device Coordinates were 1280x700 and > v2.A0
the World Coordinate space were 640x350, then the World Points (0,0)  > v2.A0
and (1,0) would translate to (0,0) and (2,0) respectively.  Notice    > v2.A0
that in the World Coordinates, the pixels were adjacent.  But in the  > v2.A0
Device Coordinates, they are separated by a one pixel gap.            > v2.A0
                                                                      > v2.A0
In summary, World Coordinates should always be equal to or greather   > v2.A0
than the size of the Device Coordinate Frame, otherwise disparity     > v2.A0
will exist in the translations.  Since coordinate translation will    > v2.A0
almost ALWAYS be from World -> Device coordinates, everything will be > v2.A0
fine if the World Frame has a larger resolution than the Device       > v2.A0
Frame.  The same holds true for the inverse equations to translate    > v2.A0
from Device to World coordinates.  If the World Coordinate Frame is   > v2.A0
larger than the Device Coordinate Frame, then any point that is       > v2.A0
translated from Device -> World Coordinates (a Mouse X/Y location for > v2.A0
example), might not translate over precisely - skipping over pixel    > v2.A0
spaces in the World Frame - this is simply because of the precision   > v2.A0
of translation and cannot be overcome mathematically since a Mouse    > v2.A0
Pointer's location is pixel based - it doesn't have any finer         > v2.A0
locations than on pixel boundary locations (there's no such thing as  > v2.A0
a fractional pixel location in graphics hardware - only               > v2.A0
mathematically).                                                      > v2.A0

                                                                      > v2.A0
To maintain backward compatibility with previous versions of the      > v2.A0
RIPscrip specification, after a RIP_RESET_WINDOWS command is          > v2.A0
received, the World Coordinate Frame is defined as having the         > v2.A0
dimensions 640x350 until reset by a RIP_SET_WORLD_FRAME command.      > v2.A0





---------------------------------------------------------------------
RIP_TEXT_WINDOW
---------------------------------------------------------------------
         Function:  Define the size and location of the Text Window
            Level:  0
          Command:  w
        Arguments:  x0:2, y0:2, x1:2, y1:2, wrap:1, size:1
           Format:  !|w <x0> <y0> <x1> <y1> <wrap> <size>
          Example:  !|w00001B0M10
  Uses Draw Color:  NO
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  NO
  Uses Font Sizes:  NO
    Uses Viewport:  NO                                                > v1.54

This command specifies the dimensions of the virtual TTY window that
will display all ASCII/ANSI (non-RIPscrip) data coming across the
connection.  (x0,y0) defines the upper-left corner of the window in
text-based character- cell coordinates.  (x1,y1) defines the
lower-right corner of the window (inclusive).  There may be two
simultaneous windows on the screen, one for TTY text, and one for the
display of RIPscrip graphics (a viewport), and they may overlap.

Bytes received over the modem are first checked for RIPscrip
commands.  All bytes that don't conform to the RIPscrip syntax are
treated as ANSI/ASCII and displayed in the TTY window (if defined).
User keystrokes that are echoed by the BBS would also appear in the
text window by this scheme.

The text window may be made invisible, ignoring all non-RIPscrip
bytes, by setting all RIP_TEXT_WINDOW parameters to zero (0).  The X
and Y parameters ranges vary depending on the setting of the <size>
parameter which governs the font size used for the output text. Valid
settings for the <size> parameter and the ranges for X/Y values are
as follows:

        Size   Font Size   X Range  Y Range
        ------------------------------------------
         0     8x8          0-79     0-42
         1     7x8          0-90     0-42
         2     8x14         0-79     0-24
         3     7x14         0-90     0-24
         4     16x14        0-39     0-24

The <wrap> parameter applies to both the horizontal and vertical
dimensions.  If <wrap> is set to 1, then any text that extends beyond
the right margin of the window will wrap to the next line of the
window, scrolling the window up if necessary.  If <wrap> is 0, then
any text going beyond the right margin is truncated and no scrolling
is performed; the cursor remains at the right margin.

When a text window is defined, its coordinates are relative to the    > v2.A0
World Coordinate Frame, not the current graphical Viewport or the     > v2.A0
Device Coordinate Frame.                                              > v2.A0


NOTE:  If the text window currently being defined is identical to the
       currently defined text window, the cursor will not be
       relocated to the upper-left corner of the window. The only
       aspect of the text window that can be different and still be
       deemed "identical" is the <wrap> parameter.  For the current
       and new text windows to be considered identical, the
       parameters <x0>, <y0>, <x1>, <y1> and <size> must be the same.





---------------------------------------------------------------------
RIP_VIEWPORT
---------------------------------------------------------------------
         Function:  Define the size & location of the Graphics Window
            Level:  0
          Command:  v
        Arguments:  x0:2, y0:2, x1:2, y1:2
           Format:  !|v <x0> <y0> <x1> <y1>
          Example:  !|v00002E1M
  Uses Draw Color:  NO
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  NO
  Uses Font Sizes:  NO
    Uses Viewport:  NO                                                > v1.54

This command defines the (X,Y) pixel boundaries of the RIPscrip
graphics window, which will contain all RIPscrip graphics output.
ASCII/ANSI text will be displayed in the virtual TTY window defined
by the RIP_TEXT_WINDOW command above.  (x0,y0) defines the upper-left
corner of the graphics viewport, and (x1,y1) defines the lower-right
corner (inclusive).  The viewport may be disabled, so RIPscrip
graphics commands are ignored, by setting all parameters to zero (0).

Graphics displayed in the viewport are "truncated" at this rectangular
border, meaning if a circle would normally extend outside one of the
borders, it will be chopped, only displaying the portion of the
circle that is contained inside the viewport boundaries.

Coordinates that specify the boundary of the Graphics Viewport are    > v2.A0
specified in World Coordinates.  The interior area of the Viewport is > v2.A0
then considered the Drawing Frame.  The Drawing Coordinate frame are  > v2.A0
set to the same size/dimension as the World Coordinate Frame area     > v2.A0
that the viewport inhabits.  For example, if you define a viewport    > v2.A0
from (100,100) to (299,299) in World Coordinates, then your Drawing   > v2.A0
Frame will be a drawing area with a resolution of 200x200 logical     > v2.A0
drawing pixels.  In other words, when you set a viewport, you         > v2.A0
immediately have a 1:1 mapping of logical drawing pixels to World     > v2.A0
Coordinate Pixels.  If you wish to change the X/Y Drawing Frame       > v2.A0
resolution to some other value, use the RIP_SET_DRAWING_FRAME command > v2.A0
after setting the viewport.  If you draw anything before executing    > v2.A0
this command, then the privimitives will be drawing things in the     > v2.A0
current Drawing Frame's coordinates (a sub-set of the World           > v2.A0
Coordinates).  The Drawing Frame's coordinates do not take on another > v2.A0
mapping until you actually set them with a RIP_SET_DRAWING_FRAME      > v2.A0
command.                                                              > v2.A0





--------------------------------------------------------------------- > v2.A0
RIP_SET_DRAWING_FRAME                                                 > v2.A0
--------------------------------------------------------------------- > v2.A0
         Function:  Sets the coordinates for the Drawing Frame        > v2.A0
            Level:  0                                                 > v2.A0
          Command:  r                                                 > v2.A0
        Arguments:  x_dim:2 y_dim:2                                   > v2.A0
           Format:  !|f <x_dim> <y_dim>                               > v2.A0
          Example:  !|fSGSG                                           > v2.A0
  Uses Draw Color:  NO                                                > v2.A0
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO                                                > v2.A0
  Uses Line Thick:  NO                                                > v2.A0
  Uses Fill Color:  NO                                                > v2.A0
Uses Fill Pattern:  NO                                                > v2.A0
  Uses Write Mode:  NO                                                > v2.A0
  Uses Font Sizes:  NO                                                > v2.A0
    Uses Viewport:  NO                                                > v2.A0
                                                                      > v2.A0
This command modifies the X/Y dimensions of the currently defined     > v2.A0
graphics viewport, thus changing the coordinate space mapping.  This  > v2.A0
allows you to custom tailor the coordinate space of your Drawing      > v2.A0
Viewport to something other than the World Coordinate system.  With   > v2.A0
this, you can set up a drawing region that has a uniform set of       > v2.A0
coordinates (eg, 1000x1000), even though the region isn't necessarily > v2.A0
square.  This allows for vertical or horizontal scaling of a scene    > v2.A0
thus squashing it or making it squishier in size.  If you choose your > v2.A0
coordinate dimensions properly based on the viewport's dimensions,    > v2.A0
you can get a perfectly defined coordinate space for your drawings.   > v2.A0
                                                                      > v2.A0
Let's say you defined a viewport that spanned the area of the World   > v2.A0
Coordinate system from (100,100) to (299,299).  This gives you a      > v2.A0
200x200 drawing space for your viewport.  But what if you wanted to   > v2.A0
display a RIPscrip scene in that window that was 640x350 in size?     > v2.A0
Set your Drawing Frame to a dimension of 640x350!  This will          > v2.A0
dynamically tranlate every coordinate in the scene into the viewport  > v2.A0
proportionally so that it fits inside the window perfectly.           > v2.A0
                                                                      > v2.A0
The equations for translating Drawing Coordinates (X,Y) to World      > v2.A0
Coordinates (Xw,Yw) are similar in nature to the translation from     > v2.A0
World to Device Coordinates with the exception that the viewport is   > v2.A0
not full screen - it is (possibly) offset from the upper-left corner  > v2.A0
of the World Frame by some offset (Xo,Yo).  The equations are:        > v2.A0
                                                                      > v2.A0
  EQUATION 3 - TRANSLATE DRAWING TO WORLD COORDINATES                 > v2.A0
  ---------------------------------------------------                 > v2.A0
         _________________________________________________            > v2.A0
        |                        |                        |           > v2.A0
        |       X * x_Vmax       |       Y * y_Vmax       |           > v2.A0
        |  Xw = ---------- + Xo  |  Yw = ---------- + Yo  |           > v2.A0
        |        x_Ddim          |        y_Ddim          |           > v2.A0
        |________________________|________________________|           > v2.A0
                                                                      > v2.A0
where:                                                                > v2.A0
                                                                      > v2.A0
     x_Vmax is the horizontal size of the viewport in World           > v2.A0
            Coordinates.                                              > v2.A0
                                                                      > v2.A0
     y_Vmax is the vertical size of the viewport in World             > v2.A0
            Coordinates.                                              > v2.A0
                                                                      > v2.A0
     x_Ddim is the horizontal size of the Drawing Frame in            > v2.A0
            Drawing Coordinates.                                      > v2.A0
                                                                      > v2.A0

     y_Ddim is the vertical size of the Drawing Frame in              > v2.A0
            Drawing Coordinates.                                      > v2.A0
                                                                      > v2.A0
Let's take an example.  Let's say our World Coordinate Frame is       > v2.A0
defined as being 1000 pixels wide (x_max), and 1000 pixels tall       > v2.A0
(y_max).  If we define a viewport from (500,500) to (999,999) we will > v2.A0
be defining a viewport in the lower-right quarter of the screen. The  > v2.A0
viewport would be 500 pixels wide (x_Vmax) and 500 pixels tall        > v2.A0
(y_Vmax).  Our X/Y offsets for the upper-left corner of the viewport  > v2.A0
are (Xo,Yo) which are equal to the first coordinate of the viewport   > v2.A0
(500,500).  In other words, Xo=500 and Yo=500.  Now, if we define our > v2.A0
Drawing Frame as being 640 pixels wide (x_Ddim) and 350 pixels high   > v2.A0
(y_Ddim), what would be the World Coordinates of a point drawn at     > v2.A0
(320,175) in Drawing Coordinates?  Let's evaluate the equations to    > v2.A0
see what values we get.                                               > v2.A0
                                                                      > v2.A0
We are given the following information:                               > v2.A0
                                                                      > v2.A0
       X = 320    Xo = 500     x_Vmax = 500     x_Ddim = 640          > v2.A0
       Y = 175    Yo = 500     y_Vmax = 500     y_Ddim = 350          > v2.A0
                                                                      > v2.A0
Substituting into our two equations, we have the following:           > v2.A0
                                                                      > v2.A0
          320 * 500          160,000                                  > v2.A0
     Xw = --------- + 500  = ------- + 500 = 250 + 500 = 750          > v2.A0
             640               640                                    > v2.A0
                                                                      > v2.A0
                                                                      > v2.A0
          175 * 500           87,500                                  > v2.A0
     Yw = --------- + 500  =  ------ + 500 = 250 + 500 = 750          > v2.A0
             350               350                                    > v2.A0
                                                                      > v2.A0
Since the Point we were trying to plot was in the middle of the       > v2.A0
viewport (320,175), we would expect the coordinate to be in the       > v2.A0
middle of the viewport's World Coordinates - halfway between          > v2.A0
(500,500) and (999,999) which would be at location (750,750) which is > v2.A0
exactly where it is!                                                  > v2.A0
                                                                      > v2.A0
If we solve the two previous equations for X and Y instead of Xw and  > v2.A0
Yw, we get the inverse equations - translations from World to Drawing > v2.A0
Coordinates as follows:                                               > v2.A0
                                                                      > v2.A0
  EQUATION 4 - TRANSLATE WORLD TO DRAWING COORDINATES                 > v2.A0
  ---------------------------------------------------                 > v2.A0
     _____________________________________________________________    > v2.A0
    |                              |                              |   > v2.A0
    |        x_Ddim * (Xw - Xo)    |        y_Ddim * (Yw - Yo)    |   > v2.A0
    |    X = ------------------    |    Y = ------------------    |   > v2.A0
    |              x_Vmax          |              y_Vmax          |   > v2.A0
    |______________________________|______________________________|   > v2.A0
                                                                      > v2.A0
As you may be thinking, what if you attempt to convert a World        > v2.A0
Coordinate Point to a Drawing Coordinate Point, but that point is not > v2.A0
actually inside the Viewport?  You could get negative results or the  > v2.A0
point could be larger than the X or Y dimensions of your viewport in  > v2.A0
Drawing Coordinates.  The results aren't undefined, they are just     > v2.A0
simply "out of bounds".                                               > v2.A0
                                                                      > v2.A0

The final set of equations are the meat and potatoes of the RIPscrip  > v2.A0
coordinate system: Drawing -> Device Coordinates.  To accomplish      > v2.A0
this, one must first translate a Drawing Coordinate to its            > v2.A0
corresponding World Coordinate, then take that World Coordinate and   > v2.A0
translate it to its respective Device Coordinate.  Now, this could be > v2.A0
done quite easily by systematically pumping the numbers through the   > v2.A0
two respective equations, but what we want is one equation that does  > v2.A0
this all in one operation.  To get this equation, we substitute       > v2.A0
Equation #3 into Equation #1 and after simplifying the results, we    > v2.A0
get the following equations:                                          > v2.A0
                                                                      > v2.A0
                                                                      > v2.A0
  EQUATION 5 - TRANSLATE DRAWING TO DEVICE COORDINATES                > v2.A0
  ----------------------------------------------------                > v2.A0
 ___________________________________________________________________  > v2.A0
|                                 |                                 | > v2.A0
|      x_max*(X*x_Vmax+x_Ddim*Xo) |      y_max*(Y*y_Vmax+y_Ddim*Yo) | > v2.A0
| Xd = -------------------------- | Yd = -------------------------- | > v2.A0
|             x_dim*x_Ddim        |            y_dim*y_Ddim         | > v2.A0
|_________________________________|_________________________________| > v2.A0
                                                                      > v2.A0
                                                                      > v2.A0
If we solve the above two equations for X and Y, we reach the inverse > v2.A0
equations, the translation from Device Coordinates to Drawing         > v2.A0
Coordinates:                                                          > v2.A0
                                                                      > v2.A0
                                                                      > v2.A0
  EQUATION 6 - TRANSLATE DEVICE TO DRAWING COORDINATES                > v2.A0
  ----------------------------------------------------                > v2.A0
 ___________________________________________________________________  > v2.A0
|                                 |                                 | > v2.A0
|     X_Ddim*(Xd*X_dim-x_max*Xo)  |     Y_Ddim*(Yd*Y_dim-y_max*Yo)  | > v2.A0
| X = --------------------------  | Y = --------------------------  | > v2.A0
|          x_max * x_Vmax         |          y_max * y_Vmax         | > v2.A0
|_________________________________|_________________________________| > v2.A0





---------------------------------------------------------------------
RIP_RESET_WINDOWS
---------------------------------------------------------------------
         Function:  Clear Graphic/Text Windows & reset to full screen
            Level:  0
          Command:  *
        Arguments:  <none>
           Format:  !|*
          Example:  !|*
  Uses Draw Color:  NO
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  NO
  Uses Font Sizes:  NO
    Uses Viewport:  NO                                                > v1.54

This command will set the Text Window to a full 80x43 EGA hi-res text
mode, place the cursor in the upper left corner, clear the screen,
and zoom the Graphics Window to full 640x350 EGA screen.  Both
windows are filled with the current graphics background color.  Also, > v1.54
all Mouse Regions and Mouse Buttons are deleted and the Clipboard is  > v1.54
erased.  A system One might use this function before entering a text  > v1.54
only mode that does not support RIP commands.  This command will also
restore the default 16-color RIP palette (see RIP_SET_PALETTE below).

All Style slots, Viewport slots and Text Window slots are reset and   > v2.A0
initialized to a suitable default in their respective slot #0.  All   > v2.A0
current slots are set to slot #0 as well.                             > v2.A0
                                                                      > v2.A0
When this command is executed, the Base Math is reset to Base-36.     > v2.A0

When this command is executed, all button style slots are reset, as
are graphical style slots.  The save/restore slots (clipboard, mouse
fields, etc) are not cleared however.

NOTE:  This command sets the world coordinate frame to 640x350,       > v2.A1
       sets coordinate sizes to 2 byte MegaNums, sets color palette   > v2.A1
       mode (disabling Direct RGB encoding).                          > v2.A1





---------------------------------------------------------------------
RIP_ERASE_WINDOW
---------------------------------------------------------------------
         Function:  Clears Text Window to current background color
            Level:  0
          Command:  e
        Arguments:  <none>
           Format:  !|e
          Example:  !|e
  Uses Draw Color:  NO
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  NO
  Uses Font Sizes:  NO
    Uses Viewport:  NO                                                > v1.54

This clears the TTY text window to the current graphics background
color and positions the cursor in the upper-left corner of the
window.  If the text window is inactive, then this command is
ignored.  If the text and graphics windows overlap, then this command
will clear the overlapping portion also.





---------------------------------------------------------------------
RIP_ERASE_VIEW
---------------------------------------------------------------------
         Function:  Clear Graphics Window to current background color
            Level:  0
          Command:  E
        Arguments:  <none>
           Format:  !|E
          Example:  !|E
  Uses Draw Color:  NO
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  NO
  Uses Font Sizes:  NO
    Uses Viewport:  NO                                                > v1.54

This command clears the Graphics Viewport to the current graphics
background color.  If the graphics viewport is not active (if the
boundaries are 0,0,0,0), then this command is ignored.  If the text
and graphics windows overlap, then this command will clear the
overlapping portion also.





---------------------------------------------------------------------
RIP_GOTOXY
---------------------------------------------------------------------
         Function:  Move text cursor to row & column in Text Window
            Level:  0
          Command:  g
        Arguments:  x:2, y:2
           Format:  !|g <x> <y>
          Example:  !|g0509
  Uses Draw Color:  NO
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  NO
  Uses Font Sizes:  NO
    Uses Viewport:  NO                                                > v1.54

This command sets the position of the text cursor in the TTY Text
window, if it is active.  If inactive (if the dimensions are
0,0,0,0), then this command is ignored.  This command is equivalent
to the ANSI/VT-100 command goto x/y, <Esc>[x;yH, except that the
coordinates of that ANSI command are 1-based and the coordinates of
this RIPscrip command are 0-based.





---------------------------------------------------------------------
RIP_HOME
---------------------------------------------------------------------
         Function:  Move cursor to upper-left corner of Text Window
            Level:  0
          Command:  H
        Arguments:  <none>
           Format:  !|H
          Example:  !|H
  Uses Draw Color:  NO
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  NO
  Uses Font Sizes:  NO
    Uses Viewport:  NO                                                > v1.54

This command positions the text cursor to the upper-left corner in
the TTY Text Window, if it is active.





---------------------------------------------------------------------
RIP_ERASE_EOL
---------------------------------------------------------------------
         Function:  Erase current line from cursor to end of line
            Level:  0
          Command:  >
        Arguments:  <none>
           Format:  !|>
          Example:  !|>
  Uses Draw Color:  NO
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  NO
  Uses Font Sizes:  NO
    Uses Viewport:  NO                                                > v1.54

This command will erase the current text line in the TTY text window
from the current cursor location (inclusive) to the end of the line.
The erased region is filled with the current graphics background
color.  This differs from the ANSI command ESC[K which clears the
area with the current ANSI background color.





---------------------------------------------------------------------
RIP_COLOR
---------------------------------------------------------------------
         Function:  Set current Drawing Color for graphics
            Level:  0
          Command:  c
        Arguments:  color:4                                           > v2.A0
           Format:  !|c <color>
          Example:  !|cA
  Uses Draw Color:  YES
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  NO
  Uses Font Sizes:  NO
    Uses Viewport:  NO                                                > v1.54

This command sets the color for drawing lines, circles, arcs,
rectangles, and other graphics primitives, as well as the color for
drawing graphics-text from the RIP_TEXT class of commands (not from
ASCII/ANSI text).  This command does not affect Fill colors or Fill
Patterns (see below).  It does affect the borders of graphic objects,
for example the border of an ellipse drawn with the RIP_FILLED_OVAL
command.  (The interior of the ellipse would be drawn according to
the most recent RIP_FILL_STYLE command).

The <color> parameter of this command serves two purposes depending   > v2.A0
on what Color Mode is currently set.  The default mode, Color Map     > v2.A0
mode, signifies that the color parameter of this command will use the > v2.A0
parameter as an index into the 256 color Drawing Palette color        > v2.A0
mapping table.  In this mode, this parameter will use the current     > v2.A0
Base Math set by the global RIP_SET_BASE_MATH command.                > v2.A0
                                                                      > v2.A0
In Direct RGB Color Mode, the color parameter will be encoded in      > v2.A0
UltraNums (regardless of the current Base Math setting).  The total   > v2.A0
number of digits used will vary depending on the number of bits per   > v2.A0
color component (R, G and B).  The following table will provide a     > v2.A0
breakdown of bits vs. total number of UltraNum digits used for Direct > v2.A0
RGB Color codes:                                                      > v2.A0
                                                                      > v2.A0
     Bits    Total Digits                                             > v2.A0
     --------------------                                             > v2.A0
       1          1                                                   > v2.A0
       2          1                                                   > v2.A0
       3          2                                                   > v2.A0
       4          2                                                   > v2.A0
       5          3                                                   > v2.A0
       6          3                                                   > v2.A0
       7          4                                                   > v2.A0
       8          4                                                   > v2.A0
                                                                      > v2.A0
These numeric values will be an encoded RGB value allowing you to set > v2.A0
arbitrary RGB colors directly with the Set Color commands.  If the    > v2.A0
RGB color is not permissable, the closest match from the Color Map    > v2.A0
table will be located and used.  The number of bits of precision used > v2.A0
in the encoded RGB value will be determined by the RIP_SET_COLOR_MODE > v2.A0
command.                                                              > v2.A0
                                                                      > v2.A0

When Direct RGB Colors Codes are used, the bits for each Red, Green   > v2.A0
and Blue are encoded as tightly as possible to ensure no wasted       > v2.A0
space.  For example, if 6 bits were used for R, G and B (the VGA      > v2.A0
color palette), you would have the following layout in binary form:   > v2.A0
                                                                      > v2.A0
     rrrrrr gggggg bbbbbb                                             > v2.A0
                                                                      > v2.A0
where each of "r", "g" and "b" could be individual ones or zeros.     > v2.A0
This binary representation of the color code is then converted to     > v2.A0
UltraNum using the proper number of digits from the preceding table.  > v2.A0
For example, if you had binary values:                                > v2.A0
                                                                      > v2.A0
       RED:  011011                                                   > v2.A0
     GREEN:  001001                                                   > v2.A0
      BLUE:  100100                                                   > v2.A0
                                                                      > v2.A0
You would have the following binary number:                           > v2.A0
                                                                      > v2.A0
     011011 001001 100100 (111,204 decimal)                           > v2.A0
                                                                      > v2.A0
And in UltraNum, the value would be: R9a                              > v2.A0
                                                                      > v2.A0
When Color Mapping Mode is in use, the color parameter may be shorter > v2.A0
than four digits.  This is for space savings, as it is allowable in   > v2.A0
the specification for the last numeric parameter in a parameter list  > v2.A0
to be "shorter" than the full length.                                 > v2.A0
                                                                      > v2.A0
In Color Map mode, this command chooses one of the colors of the      > v2.A0
256-color Drawing Palette defined by the class of Set Palette         > v2.A0
commands.  Here is the default 16 lowest colors of the Desktop        > v2.A0
Palette (these correspond to the colors of ANSI graphics):            > v2.A0

     Value   Color
     -------------------------------------------------------
     00      Black (00 is always the background color)
     01      Blue
     02      Green
     03      Cyan
     04      Red
     05      Magenta
     06      Brown
     07      Light Gray
     08      Dark Gray
     09      Light Blue
     0A      Light Green
     0B      Light Cyan
     0C      Light Red
     0D      Light Magenta
     0E      Yellow
     0F      White




--------------------------------------------------------------------- > v2.A1
RIP_BACK_COLOR                                                        > v2.A1
--------------------------------------------------------------------- > v2.A1
         Function:  Set background Drawing Color for graphics         > v2.A1
            Level:  0                                                 > v2.A1
          Command:  k                                                 > v2.A1
        Arguments:  color:4                                           > v2.A1
           Format:  !|k <color>                                       > v2.A1
          Example:  !|c04                                             > v2.A1
  Uses Draw Color:  NO                                                > v2.A1
  Uses Back Color:  YES                                               > v2.A1
Uses Line Pattern:  NO                                                > v2.A1
  Uses Line Thick:  NO                                                > v2.A1
  Uses Fill Color:  NO                                                > v2.A1
Uses Fill Pattern:  NO                                                > v2.A1
  Uses Write Mode:  NO                                                > v2.A1
  Uses Font Sizes:  NO                                                > v2.A1
    Uses Viewport:  NO                                                > v2.A1
                                                                      > v2.A1
This command alters the setting of the background pen drawing color.  > v2.A1
This color is used for fill operations for the background pixels of   > v2.A1
the fill.  The color of the foreground pixels of the fill pattern are > v2.A1
specified with a RIP_FILL_STYLE and RIP_FILL_PATTERN command.  Upon a > v2.A1
RIP_RESET_WINDOWS, the background color is automatically set to black > v2.A1
and remains that way unless overidden by a RIP_BACK_COLOR command.    > v2.A1
                                                                      > v2.A1
The background color can also affect the way line patterns/styles     > v2.A1
appear on the screen.  Normally a line pattern is a sequence of on    > v2.A1
and off pixels where the on pixels are drawn in the normal RIPscrip   > v2.A1
foreground drawing color as set by the RIP_COLOR command.  The other  > v2.A1
pixels (the odd pixels) are normally not drawn at all (ie,            > v2.A1
transparent).  When you use the RIP_LINE_STYLE command, you can now   > v2.A1
specify that these odd pixels are to be drawn in the current          > v2.A1
background color (set with this command).  See the RIP_LINE_STYLE for > v2.A1
exact syntax on using this mode.                                      > v2.A1
                                                                      > v2.A1
See the RIP_COLOR command for an exact description of the <color>     > v2.A1
parameter used in this command (both Color Palette mode and Direct    > v2.A1
RGB color mode are supported).                                        > v2.A1




---------------------------------------------------------------------
RIP_SET_PALETTE
---------------------------------------------------------------------
         Function:  Set 16-color Desktop Palette from 64-clr palette  > v2.A0
            Level:  0
          Command:  Q
        Arguments:  c1:2, c2:2, ... c16:2
           Format:  !|Q <c1> <c2> ... <c16>
          Example:  !|Q000102030405060708090A0B0C0D0E0F
  Uses Draw Color:  YES
  Uses Back Color:  YES                                               > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  NO
  Uses Font Sizes:  NO
    Uses Viewport:  NO                                                > v1.54

This command modifies the 16-color Desktop palette by choosing from
the 64 colors in the master palette.  This allows you to alter the
colors in your RIPscrip graphics scenes.  Once a Set Palette command
is processed, any colors on the screen that had their corresponding
palette entries changed will instantly switch to the new color set.
You may obtain color cycling effects by using this command.  The
default 16-color RIP palette is restored by the RIP_RESET_WINDOWS
command.  The default 16-color RIP palette is:

                           Master 64-Color EGA                        > v2.A0
                           Palette Color Code                         > v2.A0
    16-Color RIP Palette   -----------------    R/G/B                 > v2.A0
        Color Code         Base-10 B-36 B-64    (0-3)  Color          > v2.A0
    -------------------------------------------------------------     > v2.A0
           00                0     (00) [0]     0 0 0  Black          > v2.A0
           01                1     (01) [1]     0 0 2  Blue           > v2.A0
           02                2     (02) [2]     0 2 0  Green          > v2.A0
           03                3     (03) [3]     0 2 2  Cyan           > v2.A0
           04                4     (04) [4]     2 0 0  Red            > v2.A0
           05                5     (05) [5]     2 0 2  Magenta        > v2.A0
           06                20    (0K) [K]     2 1 0  Brown          > v2.A0
           07                7     (07) [7]     2 2 2  Light Gray     > v2.A0
           08                56    (1K) [u]     1 1 1  Dark Gray      > v2.A0
           09                57    (1L) [v]     1 1 3  Light Blue     > v2.A0
           0A                58    (1M) [w]     1 3 1  Light Green    > v2.A0
           0B                59    (1N) [x]     1 3 3  Light Cyan     > v2.A0
           0C                60    (1O) [y]     3 1 1  Light Red      > v2.A0
           0D                61    (1P) [z]     3 1 3  Light Magenta  > v2.A0
           0E                62    (1Q) [#]     3 3 1  Yellow         > v2.A0
           0F                63    (1R) [@]     3 3 3  White          > v2.A0
                                                                      > v2.A0
The raw color values (0-63) correspond to an RGB color definition in  > v2.A0
which two bits are used for each of the Red, Green and Blue           > v2.A0
components.  The layout of the binary number is shown as follows:     > v2.A0
                                                                      > v2.A0
                      Secondary    Primary                            > v2.A0
                     ___________ ___________                          > v2.A0
             ___ ___ ___ ___ ___ ___ ___ ___                          > v2.A0
            |   |   |   |   |   |   |   |   |                         > v2.A0
            | - | - | R | G | B | R | G | B |                         > v2.A0
            |___|___|___|___|___|___|___|___|                         > v2.A0
              80  40  20  10  8   4   2   1  (hex)                    > v2.A0
              7   6   5   4   3   2   1   0  (position)               > v2.A0
                                                                      > v2.A0

Notice that each of the R, G and B sections are broken up into two    > v2.A0
separate bit sections in the color palette entry number.  Also, the   > v2.A0
bits are reversed when they are encoded.  Let's look at four separate > v2.A0
colors of Red, Green and Blue to see how the bit patterns correspond  > v2.A0
to the actual Palette entries:                                        > v2.A0
                                                                      > v2.A0
 RED   PALETTE ENTRY    GREEN  PALETTE ENTRY     BLUE  PALETTE ENTRY  > v2.A0
 -------------------     -------------------     -------------------  > v2.A0
         xxRGBrgb                xxRGBrgb                xxRGBrgb     > v2.A0
         --------                --------                --------     > v2.A0
 00      00000000        00      00000000        00      00000000     > v2.A0
 01      00100000        01      00010000        01      00001000     > v2.A0
 10      00000100        10      00000010        10      00000001     > v2.A0
 11      00100100        11      00010010        11      00001001     > v2.A0

Color 00 of the 16-color RIP palette is always the background color
(which is typically Black, or color 00 of the 64-color EGA palette).





---------------------------------------------------------------------
RIP_ONE_PALETTE
---------------------------------------------------------------------
         Function:  Set color of 16-color Desktop Palette             > v2.A0
            Level:  0
          Command:  a
        Arguments:  color:2 value:2
           Format:  !|a <color> <value>
          Example:  !|a051B
  Uses Draw Color:  YES
  Uses Back Color:  YES                                               > v2.A1
  Uses Line Thick:  NO
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  NO
  Uses Font Sizes:  NO
    Uses Viewport:  NO                                                > v1.54

This command changes one color in the 16-color Desktop Palette.  The
color number is sent along with the new color value from the Master
Color Palette. The color <value> must be in the range of 0-63.  Once
a Set One Palette command is processed, any colors on the screen that
correspond to the <color> number will be changed instantly to the new
color value.  You may obtain color cycling effects by using this
command.  The default RIP palette is restored when by the
RIP_RESET_WINDOWS command.

                           Master 64-Color EGA                        > v2.A0
                           Palette Color Code                         > v2.A0
    16-Color RIP Palette   -----------------    R/G/B                 > v2.A0
        Color Code         Base-10 B-36 B-64    (0-3)  Color          > v2.A0
    -------------------------------------------------------------     > v2.A0
           00                0     (00) [0]     0 0 0  Black          > v2.A0
           01                1     (01) [1]     0 0 2  Blue           > v2.A0
           02                2     (02) [2]     0 2 0  Green          > v2.A0
           03                3     (03) [3]     0 2 2  Cyan           > v2.A0
           04                4     (04) [4]     2 0 0  Red            > v2.A0
           05                5     (05) [5]     2 0 2  Magenta        > v2.A0
           06                20    (0K) [K]     2 1 0  Brown          > v2.A0
           07                7     (07) [7]     2 2 2  Light Gray     > v2.A0
           08                56    (1K) [u]     1 1 1  Dark Gray      > v2.A0
           09                57    (1L) [v]     1 1 3  Light Blue     > v2.A0
           0A                58    (1M) [w]     1 3 1  Light Green    > v2.A0
           0B                59    (1N) [x]     1 3 3  Light Cyan     > v2.A0
           0C                60    (1O) [y]     3 1 1  Light Red      > v2.A0
           0D                61    (1P) [z]     3 1 3  Light Magenta  > v2.A0
           0E                62    (1Q) [#]     3 3 1  Yellow         > v2.A0
           0F                63    (1R) [@]     3 3 3  White          > v2.A0
                                                                      > v2.A0
The raw color values (0-63) correspond to an RGB color definition in  > v2.A0
which two bits are used for each of the Red, Green and Blue           > v2.A0
components.  The layout of the binary number is shown as follows:     > v2.A0
                                                                      > v2.A0
                      Secondary    Primary                            > v2.A0
                     ___________ ___________                          > v2.A0
             ___ ___ ___ ___ ___ ___ ___ ___                          > v2.A0
            |   |   |   |   |   |   |   |   |                         > v2.A0
            | - | - | R | G | B | R | G | B |                         > v2.A0
            |___|___|___|___|___|___|___|___|                         > v2.A0
              80  40  20  10  8   4   2   1  (hex)                    > v2.A0
              7   6   5   4   3   2   1   0  (position)               > v2.A0
                                                                      > v2.A0

Notice that each of the R, G and B sections are broken up into two    > v2.A0
separate bit sections in the color palette entry number.  Also, the   > v2.A0
bits are reversed when they are encoded.  Let's look at four separate > v2.A0
colors of Red, Green and Blue to see how the bit patterns correspond  > v2.A0
to the actual Palette entries:                                        > v2.A0
                                                                      > v2.A0
 RED   PALETTE ENTRY    GREEN  PALETTE ENTRY     BLUE  PALETTE ENTRY  > v2.A0
 -------------------     -------------------     -------------------  > v2.A0
         xxRGBrgb                xxRGBrgb                xxRGBrgb     > v2.A0
         --------                --------                --------     > v2.A0
 00      00000000        00      00000000        00      00000000     > v2.A0
 01      00100000        01      00010000        01      00001000     > v2.A0
 10      00000100        10      00000010        10      00000001     > v2.A0
 11      00100100        11      00010010        11      00001001     > v2.A0

Color 00 of the 16-color RIP palette is always the background color
(which is typically Black, or color 00 of the 64-color EGA palette).





--------------------------------------------------------------------- > v2.A0
RIP_SET_DRAWING_PALETTE                                               > v2.A0
--------------------------------------------------------------------- > v2.A0
         Function:  Set Drawing Palette entries to RGB colors         > v2.A0
            Level:  0                                                 > v2.A0
          Command:  D                                                 > v2.A0
        Arguments:  <num>:2 <start>:2 <bits>:1 c1:4, ... cn:4         > v2.A0
           Format:  !|D <num> <bits> <start> <c1> ... <c16>           > v2.A0
          Example:  !|D0301080GhZPzr3aZr3                             > v2.A0
  Uses Draw Color:  YES                                               > v2.A0
  Uses Back Color:  YES                                               > v2.A1
Uses Line Pattern:  NO                                                > v2.A0
  Uses Line Thick:  NO                                                > v2.A0
  Uses Fill Color:  NO                                                > v2.A0
Uses Fill Pattern:  NO                                                > v2.A0
  Uses Write Mode:  NO                                                > v2.A0
  Uses Font Sizes:  NO                                                > v2.A0
    Uses Viewport:  NO                                                > v2.A0
                                                                      > v2.A0
This command will set one or more colors in the 256-entry Drawing     > v2.A0
Palette to arbitrary RGB color mappings.  This allows you to          > v2.A0
customize the Drawing Palette with extended color information beyond  > v2.A0
what you can normally do with the Desktop Palette.  The Desktop       > v2.A0
Palette (all 16 colors) can only be set with 6 bits of RGB            > v2.A0
information.  This command is more flexible in nature in that it      > v2.A0
allows you to access colors between 0-255 and gives you the added     > v2.A0
flexibility to store more than 6 bits of RGB data - thus allowing you > v2.A0
to select colors out of a 256K color palette or even a 24-bit color   > v2.A0
palette.                                                              > v2.A0
                                                                      > v2.A0
The <num> parameter specifies how many color entries are contained in > v2.A0
this given Palette command.  This is used in determining how many     > v2.A0
bytes long the command should be.                                     > v2.A0
                                                                      > v2.A0
The <start> parameter determines the starting Color Palette Entry     > v2.A0
number that the first color in the command will be assigned to.       > v2.A0
Every following parameter will correspond to the next highest Color   > v2.A0
Palette Entry number.                                                 > v2.A0
                                                                      > v2.A0
NOTE:  The four-digit color parameters are not MegaNums - they are    > v2.A0
       always ULTRA-NUMS regardless of the setting of the global      > v2.A0
       base-math value!  With four digits at base-64 math, you can    > v2.A0
       achieve 24-bits of precision in one four-digit number.         > v2.A0
                                                                      > v2.A0
If you break-down the four-digit UltraNum color values into their     > v2.A0
binary equivalents (three bytes), the MSB would contain the Red       > v2.A0
component, the LSB would contain the Blue component and the byte in   > v2.A0
between contains the Green component.  This command allows you to     > v2.A0
specify a number of bits for each component.  Under no circumstances  > v2.A0
are values above 8 allowed, since this would overflow a four-digit    > v2.A0
UltraNum parameter (beyond 24 bits).                                  > v2.A0
                                                                      > v2.A0
Color Entry number zero (0) is the screen's background color.  It is  > v2.A0
normally set to RGB color 0/0/0, or Black.  Changing this color will  > v2.A0
alter the background color of the entire screen/environment, so great > v2.A0
care should be taken if you alter color number 0.                     > v2.A0





--------------------------------------------------------------------- > v2.A0
RIP_ONE_DRAWING_PALETTE                                               > v2.A0
--------------------------------------------------------------------- > v2.A0
         Function:  Set Drawing Palette entries to RGB colors         > v2.A0
            Level:  0                                                 > v2.A0
          Command:  d                                                 > v2.A0
        Arguments:  <entry>:2 <bits>:1 <rgb_color>:4                  > v2.A0
           Format:  !|d <entry> <bits> <rgb_color>                    > v2.A0
          Example:  !|d0108qR3P                                       > v2.A0
  Uses Draw Color:  YES                                               > v2.A0
  Uses Back Color:  YES                                               > v2.A1
Uses Line Pattern:  NO                                                > v2.A0
  Uses Line Thick:  NO                                                > v2.A0
  Uses Fill Color:  NO                                                > v2.A0
Uses Fill Pattern:  NO                                                > v2.A0
  Uses Write Mode:  NO                                                > v2.A0
  Uses Font Sizes:  NO                                                > v2.A0
    Uses Viewport:  NO                                                > v2.A0
                                                                      > v2.A0
This command will set a single entry in the Drawing Palette to an     > v2.A0
arbitrary RGB color.  This allows you to customize the                > v2.A0
Drawing Palette with extended color information beyond what you can   > v2.A0
normally do with the Desktop Palette.  The Desktop Palette (all 16    > v2.A0
colors) can only be set with 6 bits of RGB information.  This command > v2.A0
is more flexible in nature in that it allows you to access colors     > v2.A0
between 0-255 and gives you the added flexibility to store more than  > v2.A0
6 bits of RGB data - thus allowing you to select colors out of a 256K > v2.A0
color palette or even a 24-bit color palette.                         > v2.A0
                                                                      > v2.A0
The <entry> parameter specifies which Color Palette Entry number will > v2.A0
be set with the RGB color data.                                       > v2.A0
                                                                      > v2.A0
NOTE:  The four-digit color parameters are not MegaNums - they are    > v2.A0
       always ULTRA-NUMS regardless of the setting of the global      > v2.A0
       base-math value!  With four digits at base-64 math, you can    > v2.A0
       achieve 24-bits of precision in one four-digit number.         > v2.A0
                                                                      > v2.A0
If you break-down the four-digit UltraNum color values into their     > v2.A0
binary equivalents (three bytes), the MSB would contain the Red       > v2.A0
component, the LSB would contain the Blue component and the byte in   > v2.A0
between contains the Green component.  This command allows you to     > v2.A0
specify a number of <bits> for each component.  Under no              > v2.A0
circumstances are values above 8 allowed, since this would overflow a > v2.A0
four-digit UltraNum parameter (beyond 24 bits).                       > v2.A0
                                                                      > v2.A0
Color Entry number zero (0) is the screen's background color.  It is  > v2.A0
normally set to RGB color 0/0/0, or Black.  Changing this color will  > v2.A0
alter the background color of the entire screen/environment, so great > v2.A0
care should be taken if you alter color number 0.                     > v2.A0





--------------------------------------------------------------------- > v2.A0
RIP_SET_COLOR_MODE                                                    > v2.A0
--------------------------------------------------------------------- > v2.A0
         Function:  Set the Color Drawing Mode (MAP or DIRECT RGB)    > v2.A0
            Level:  0                                                 > v2.A0
          Command:  M                                                 > v2.A0
        Arguments:  <mode>:1  <bits>:1                                > v2.A0
           Format:  !|M <mode> <bits>                                 > v2.A0
          Example:  !|M18                                             > v2.A0
  Uses Draw Color:  NO                                                > v2.A0
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO                                                > v2.A0
  Uses Line Thick:  NO                                                > v2.A0
  Uses Fill Color:  NO                                                > v2.A0
Uses Fill Pattern:  NO                                                > v2.A0
  Uses Write Mode:  NO                                                > v2.A0
  Uses Font Sizes:  NO                                                > v2.A0
    Uses Viewport:  NO                                                > v2.A0
                                                                      > v2.A0
This command determines whether Color Mapping mode is in use, or if   > v2.A0
Direct RGB Colors are being used for color codes.  See the beginning  > v2.A0
of this specification for a detailed explanation of the differences   > v2.A0
between these modes.                                                  > v2.A0
                                                                      > v2.A0
The <mode> parameter may take on the following values:                > v2.A0
                                                                      > v2.A0
     Mode   Description                                               > v2.A0
     -----------------------------------------                        > v2.A0
       0    Color Mapping mode                                        > v2.A0
       1    Direct RGB Color mode                                     > v2.A0
                                                                      > v2.A0
The <bits> parameter is used to determine how many bits are to be     > v2.A0
parsed in the Direct RGB Color mode.  This parameter is ignored if    > v2.A0
the Color Mapping Mode is in effect.                                  > v2.A0
                                                                      > v2.A0
When in Direct RGB Color Mode, any Color Code parameter in the        > v2.A0
RIPscrip language that doesn't explicitly state that it uses only     > v2.A0
Color Map Mode will process a color value as a raw RGB value encoded  > v2.A0
in the same fashion as the RIP_SET_DRAWING_PALETTE command.  These    > v2.A0
parameters will always be in ULTRA-NUM format regardless of the       > v2.A0
global Base Math settings for compression.  Color palette mode though > v2.A0
uses the current base math settings for these color parameters.       > v2.A1
                                                                      > v2.A0
In Color Mapping Mode, these color parameters will typically not be   > v2.A0
the lengthy four-digit sequence used in Direct RGB Color Mode.  When  > v2.A0
in Color Mapping Mode, the color parameters used throughout RIPscrip  > v2.A0
will obey the global Base Math setting - it's only in Direct RGB      > v2.A0
Color Mode where UltraNums are forced ON for these parameters.        > v2.A0





---------------------------------------------------------------------
RIP_WRITE_MODE
---------------------------------------------------------------------
         Function:  Set drawing mode for graphics primitives
            Level:  0
          Command:  W
        Arguments:  mode:2
           Format:  !|W <mode>
          Example:  !|W00
  Uses Draw Color:  NO
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  YES
  Uses Font Sizes:  NO
    Uses Viewport:  NO                                                > v1.54

This command sets the current drawing mode for most of the graphics
primitives:

    Mode   Description                        Logical
    -------------------------------------------------
     00    Normal drawing mode (overwrite)    (COPY)                  > v2.A1
     01    Exclusive-OR  drawing mode         (XOR)                   > v2.A1
     02    Logical OR drawing mode            (OR)                    > v2.A1
     03    Logical AND drawing mode           (AND)                   > v2.A1
     04    Inverse drawing mode               (NOT)                   > v2.A1

In normal mode, things are drawn in the current drawing color over top
of whatever is in the graphics viewport.  This is the typical mode of
operation in a GUI environment.

In the XOR mode, instead of changing each pixel to the current
drawing color, the pixel is merged with the destination pixel using   > v2.A1
the logical operation XOR.  This is a bitwise manipulation of the     > v2.A1
destination and source pixel values.  In a monochrome environment,    > v2.A1
the following bit combinations would yield the following:             > v2.A1
                                                                      > v2.A1
          A   B  | A XOR B                                            > v2.A1
          -------+--------                                            > v2.A1
          0   0  |    0                                               > v2.A1
          0   1  |    1                                               > v2.A1
          1   0  |    1                                               > v2.A1
          1   1  |    0                                               > v2.A1
                                                                      > v2.A1
In the OR mode, instead of changing each pixel to the current drawing > v2.A1
color, the pixel is merged with the destination pixel using the       > v2.A1
logical operation OR.  The bits in the source pixel are OR'ed with    > v2.A1
the bits in the destination pixel to achieve the final result.  In a  > v2.A1
monochrome environment, the following bit combinations would yield    > v2.A1
the following:                                                        > v2.A1
                                                                      > v2.A1
          A   B  | A OR B                                             > v2.A1
          -------+-------                                             > v2.A1
          0   0  |   0                                                > v2.A1
          0   1  |   1                                                > v2.A1
          1   0  |   1                                                > v2.A1
          1   1  |   1                                                > v2.A1
                                                                      > v2.A1

In the AND mode, instead of changing each pixel to the current        > v2.A1
drawing color, the pixel is merged with the destination pixel using   > v2.A1
the logical operation AND.  The bits in the source pixel are AND'ed   > v2.A1
with the bits in the destination pixel to achieve the final result.   > v2.A1
In a monochrome environment, the following bit combinations would     > v2.A1
yield the following:                                                  > v2.A1
                                                                      > v2.A1
          A   B  | A AND B                                            > v2.A1
          -------+--------                                            > v2.A1
          0   0  |    0                                               > v2.A1
          0   1  |    0                                               > v2.A1
          1   0  |    0                                               > v2.A1
          1   1  |    1                                               > v2.A1
                                                                      > v2.A1
In the NOT mode, the color of the source pixel is completely ignored. > v2.A1
The bits in the destination pixel's color are inverted (0's become    > v2.A1
1's and 1's become 0's).  In other words, black becomes white, light  > v2.A1
gray becomes dark gray, etc.                                          > v2.A1
                                                                      > v2.A1
This command affects all line drawing operations (line, rectangle,    > v2.A1
circle, oval, pie slice, pixel, etc).  It also affects any fill-based > v2.A1
operations (filled bar, internal parts of a pie slice, filled circle, > v2.A1
etc).  It only affects level-0 drawing primitives.  It also affects   > v2.A1
fonts that are drawn to the screen (including the default font).      > v2.A1



---------------------------------------------------------------------
RIP_MOVE
---------------------------------------------------------------------
         Function:  Move the current drawing position to (X,Y)
            Level:  0
          Command:  m
        Arguments:  x:2, y:2
           Format:  !|m <x> <y>
          Example:  !|m0509
  Uses Draw Color:  NO
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  NO
  Uses Font Sizes:  NO
    Uses Viewport:  YES                                               > v1.54

This command moves the current graphics drawing cursor to (x,y).  You
could use this to draw text at a certain point, but you'd probably
use RIP_TEXT_XY instead.  This command is primarily provided for
future development which will make use of its ability to relocate the
current drawing position without physically drawing anything.





---------------------------------------------------------------------
RIP_TEXT
---------------------------------------------------------------------
         Function:  Draw text in current font/color at current spot
            Level:  0
          Command:  T
        Arguments:  text-string
           Format:  !|T <text-string>
          Example:  !|Thello world
  Uses Draw Color:  YES
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  YES
  Uses Font Sizes:  YES
    Uses Viewport:  YES                                               > v1.54

This command displays text at the current location in the graphics
window, as set with the RIP_MOVE command.  The text is also affected
by the most recent settings of these commands:

     Command            Description of Command
     ----------------------------------------------------------------
     RIP_FONT_STYLE     font style (character set, direction, size)
     RIP_WRITE_MODE     drawing mode (normal or XOR)
     RIP_COLOR          drawing color (from the 16-color RIP palette)

The drawing position is placed at the end of the last character
drawn.

The current drawing position is set immediately to the right of the
drawn text.  Subsequent Line, Circle or other such commands will not
affect this position.  This provides a means so that you can quickly
do another RIP_TEXT command (presumably in another color) at a later
time and have the text show up immediately after the previous text.





---------------------------------------------------------------------
RIP_TEXT_XY
---------------------------------------------------------------------
         Function:  Draw text in current font/color at specific spot
            Level:  0
          Command:  @
        Arguments:  x:2, y:2 and text-string
           Format:  !|@ <x> <y> <text-string>
          Example:  !|@0011hello world
  Uses Draw Color:  YES
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  YES
  Uses Font Sizes:  YES
    Uses Viewport:  YES                                               > v1.54

This command is an efficient combination of RIP_MOVE and RIP_TEXT.
The text is drawn at the specified location according to the same
settings as apply to RIP_TEXT (see above).

The current drawing position is set immediately to the right of the
drawn text.  Subsequent Line, Circle or other such commands will not
affect this position.  This provides a means so that you can quickly
do another RIP_TEXT command (presumably in another color) at a later
time and have the text show up immediately after the previous text.





---------------------------------------------------------------------
RIP_FONT_STYLE
---------------------------------------------------------------------
         Function:  Select current font style, orientation and size
            Level:  0
          Command:  Y
        Arguments:  font:2, direction:2, size:2, h_align:1 v_align:1  > v2.A0
           Format:  !|Y <font> <direction> <size> <h_align> <v_align> > v2.A0
          Example:  !|Y01000400
  Uses Draw Color:  NO
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  NO
  Uses Font Sizes:  YES
    Uses Viewport:  NO                                                > v1.54

This command sets the font, direction and size for RIP_TEXT commands.

     Font   Description of Font
     ---------------------------------------------
     00     Default 8x8 font            Bit-Mapped
     01     Triplex Font                Scalable
     02     Small Font                  Scalable
     03     Sans Serif Font             Scalable
     04     Gothic [Old English] Font   Scalable
     05     Script Font                 Scalable
     06     Simplex Font                Scalable
     07     Triplex Script Font         Scalable
     08     Complex Font                Scalable
     09     European Font               Scalable
     0A     Bold Font                   Scalable

For the Direction parameter, use 00 to indicate horizontal and 01 for
vertical.

For the Size parameter, use 01 for the normal default size, 02 for x2
magnification, 03 for x3 magnification, ... , and 0A for x10
magnification.

The <h_align> parameter allows you to adjust the horizontal alignment > v2.A0
of drawn text with respect to the text's base X/Y location.  There    > v2.A0
are three possible settings:                                          > v2.A0
                                                                      > v2.A0
   Value   Description of Horizontal Alignment                        > v2.A0
   -------------------------------------------------------------      > v2.A0
     0     Align text to the left - X/Y location is the far left      > v2.A0
           of the text                                                > v2.A0
     1     Right align text.  The X/Y location is the far right       > v2.A0
           of the text                                                > v2.A0
     2     Center the text horizontally around the X/Y location       > v2.A0
                                                                      > v2.A0

The <v_align> parameter allows you to adjust the vertical alignment   > v2.A0
of the drawn text with respect to the text's base X/Y location.       > v2.A0
There are four possible settings:                                     > v2.A0
                                                                      > v2.A0
   Value   Description of Vertical Alignment                          > v2.A1
   -------------------------------------------------------------      > v2.A0
     0     Align the text vertically with the X/Y location at         > v2.A0
           the very top of the tallest character in the font.         > v2.A0
     1     Make the X/Y location of the text at the very bottom       > v2.A0
           of the tallest character in the font.                      > v2.A0
     2     Center the text vertically around the X/Y location         > v2.A0
           (this takes descenders into consideration).                > v2.A0
     3     Align the text where the X/Y base point defines the        > v2.A0
           location where the baseline of the font will appear.       > v2.A0

NOTE:  The Default font is bit-mapped and looks best when drawn in
       size 1.  In sizes greater than one, the individual pixels are
       enlarged, giving a jagged look.  This may not be the desired
       effect.  The fonts 1 - A are smooth scalable vector fonts.





--------------------------------------------------------------------- > v2.A1
RIP_EXTENDED_FONT                                                     > v2.A1
--------------------------------------------------------------------- > v2.A1
         Function:  Select current font style, orientation and size   > v2.A1
            Level:  0                                                 > v2.A1
          Command:  y                                                 > v2.A1
        Arguments:  direction:2, size:2, style:2, h_align:1 v_align:1 > v2.A1
                    font_name_string                                  > v2.A1
           Format:  !|y <direction> <size> <style> <h_align>          > v2.A1
                    <v_align> <font_name_string>                      > v2.A1
          Example:  !|y01000400                                       > v2.A1
  Uses Draw Color:  NO                                                > v2.A1
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO                                                > v2.A1
  Uses Line Thick:  NO                                                > v2.A1
  Uses Fill Color:  NO                                                > v2.A1
Uses Fill Pattern:  NO                                                > v2.A1
  Uses Write Mode:  NO                                                > v2.A1
  Uses Font Sizes:  YES                                               > v2.A1
    Uses Viewport:  NO                                                > v2.A1
                                                                      > v2.A1
This command is an extended form of the RIP_FONT_STYLE command.  The  > v2.A1
use of this command opens up a large number of other fonts that       > v2.A1
aren't like the older RIPscrip 1.x fonts.  They are not vector based  > v2.A1
and they're not bitmapped based like those used with the              > v2.A1
RIP_FONT_STYLE command.  The older fonts are very useful for many     > v2.A1
applications, but when it comes to production video graphics they     > v2.A1
leave a bit to be desired.  This command utilizes True-Type (tm)      > v2.A1
style fonts which are "outline" fonts.  By outline, we mean that they > v2.A1
draw the outline of the font and fill-in the interior of the font.    > v2.A1
They also have a number of special attributes that you may assign to  > v2.A1
them (ie, Bold, Italic, Strikeout and Underline).                     > v2.A1
                                                                      > v2.A1
The addition of this extended font system fills a need in RIPscrip    > v2.A1
for solid fonts that are extensible (ie, specifying fonts not in the  > v2.A1
default system).  Fonts are scalable to an arbitrary point size       > v2.A1
(unlike the fonts in RIP_FONT_STYLE which have pre-defined font       > v2.A1
sizes).                                                               > v2.A1
                                                                      > v2.A1
The commands RIP_TEXT, RIP_TEXT_XY, RIP_REGION_TEXT and RIP_BUTTON    > v2.A1
use whichever font command is most recent (eg, RIP_FONT_STYLE or      > v2.A1
RIP_EXTENDED_FONT).  In other words, whichever font style that has    > v2.A1
been selected will be the one that is used for rendering the          > v2.A1
associated RIPscrip text related commands.                            > v2.A1
                                                                      > v2.A1
This command differs from the RIP_FONT_STYLE in several respects.     > v2.A1
One, it doesn't use built-in font sizes like the older format does    > v2.A1
(see RIP_FONT_STYLE); this command specifies fonts in a more          > v2.A1
universal format of Point Sizes.  A "point" is technically defined as > v2.A1
1/72nd of an inch.  Secondly, these fonts have the ability to alter   > v2.A1
the text "facing" which should be shown to the user (bold, italic,    > v2.A1
etc).                                                                 > v2.A1
                                                                      > v2.A1
This font system supports simple horizontal or vertical orientations  > v2.A1
for the text just like the RIP_FONT_STYLE command does.  The way you  > v2.A1
specify the font direction though is different!  You specify the      > v2.A1
direction of the font in degrees.  The possible values for the font   > v2.A1
<direction> are as follows (in decimal):                              > v2.A1
                                                                      > v2.A1
     Direction  Description                                           > v2.A1
     ---------------------------------------------------------------- > v2.A1
         0      Horizontal text (left to right text)                  > v2.A1
        90      Vertical text (bottom to top - rotated 90 degrees)    > v2.A1
                                                                      > v2.A1

The <direction> parameter may be enhanced in a future revision to     > v2.A1
support arbitrary rotation of the font (in integral degree            > v2.A1
increments).  For now, valid values for this parameter are 0 and 90   > v2.A1
degrees.                                                              > v2.A1
                                                                      > v2.A1
The <h_align> parameter determines the orientation of the displayed   > v2.A1
text around the specified text beginning coordinates.  In other       > v2.A1
words, the text might begin at the coordinate and move left, right,   > v2.A1
or be centered around the location.  The possible values for the      > v2.A1
<h_align> parameter are as follows:                                   > v2.A1
                                                                      > v2.A1
   Value   Description of Horizontal Alignment                        > v2.A1
   -------------------------------------------------------------      > v2.A1
     0     Align text to the left - X/Y location is the far left      > v2.A1
           of the text                                                > v2.A1
     1     Right align text.  The X/Y location is the far right       > v2.A1
           of the text                                                > v2.A1
     2     Center the text horizontally around the X/Y location       > v2.A1
                                                                      > v2.A1
The <v_align> parameter is much like the <h_align> parameter in that  > v2.A1
it defines the orientation of the font in relation to the X/Y text    > v2.A1
coordinates.  This command though performs vertical justification of  > v2.A1
the font instead of horizontal justification (like the <h_align>      > v2.A1
parameter).  The possible values for this parameter are:              > v2.A1
                                                                      > v2.A1
   Value   Description of Vertical Alignment                          > v2.A1
   -------------------------------------------------------------      > v2.A1
     0     Align the text vertically with the X/Y location at         > v2.A1
           the very top of the tallest character in the font.         > v2.A1
     1     Make the X/Y location of the text at the very bottom       > v2.A1
           of the tallest character in the font.                      > v2.A1
     2     Center the text vertically around the X/Y location         > v2.A1
           (this takes descenders into consideration).                > v2.A1
     3     Align the text where the X/Y base point defines the        > v2.A1
           location where the baseline of the font will appear.       > v2.A1
                                                                      > v2.A1
The <size> parameter defines the point size of the font to be         > v2.A1
displayed on the screen.                                              > v2.A1
                                                                      > v2.A1
In order to maintain resolution independence with extended fonts and  > v2.A1
various resolutions, we need to formally define how a point size is   > v2.A1
rendered at different resolutions.  For the purposes of RIPscrip font > v2.A1
systems, we formally define a point size as one physical pixel on a   > v2.A1
640x480 resolution device.  Since a VGA 640x480 device on a 13"       > v2.A1
monitor is exactly 1 point per pixel, this definition holds well.     > v2.A1
For other resolutions, we simply adjust the point size to some        > v2.A1
proportion.  For example, a 1280x1024 resolution is exactly twice as  > v2.A1
wide as a 640x480 screen, but the height is 2.1333 times that of its  > v2.A1
480 counterpart.  So a little bit of adjustment must be made on the   > v2.A1
fonts to accomodate this precisely.  The ideal method for this would  > v2.A1
be if you could apply certain scaling parameters to the font system   > v2.A1
in both the horizontal and vertical directions separately.  Not all   > v2.A1
font systems will allow this though so a "closest approximation"      > v2.A1
might have to occur.  In our 1280x1024 example, you might decide to   > v2.A1
just use twice the specified point size and leave it at that (and not > v2.A1
worrying about the slight discrepency on the height portion of the    > v2.A1
font).  When getting into resolution independence, it is not always   > v2.A1
possible to get 100.0% pixel perfect accuracy.  If you can,           > v2.A1
wonderful, but it can't be expected 100.0% on all platforms.          > v2.A1
                                                                      > v2.A1

For the standard RIPterm resolutions of 640x350, 640x480, 800x600,    > v2.A1
1024x768 and 1280x1024, only two of the resolutions do not have       > v2.A1
perfectly square pixels - these are 640x350 and 1280x1024.  These are > v2.A1
not the only resolutions possible under RIPscrip - they're just the   > v2.A1
ones that TeleGrafix's RIP products utilize.  The 640x350 resolution  > v2.A1
is like the 1280x1024 resolution in that the height of fonts will     > v2.A1
need to be adjusted to be pixel accurate with their 640x480           > v2.A1
counterparts.  If you cannot do this with your font system, then you  > v2.A1
might wish to reduce the point size a little bit so that the vertical > v2.A1
component more closely matches the visual size of the font on a       > v2.A1
640x480 screen (note that your horizontal size will shrink a little   > v2.A1
bit smaller than the 640x480 font - this is a compromise).            > v2.A1
                                                                      > v2.A1
The <style> parameter defines the style in which the font is to be    > v2.A1
rendered (eg, Normal, Bold, etc).  The style options are organized as > v2.A1
a set of flags which may be combined (OR'ed) together to produce a    > v2.A1
final, composite result:                                              > v2.A1
                                                                      > v2.A1
               Style     Description                                  > v2.A1
               ----------------------------                           > v2.A1
                 00      Normal font sizing                           > v2.A1
                 01      Bold font                                    > v2.A1
                 02      Italic font                                  > v2.A1
                 04      Strike-out font                              > v2.A1
                 08      Underlined font                              > v2.A1
                                                                      > v2.A1
The last, and possibly most important parameter in this command is    > v2.A1
the text parameter, <font_name_string>.  This string of text definfes > v2.A1
the name of the font to activate.  If a specified font is not         > v2.A1
recognized, then the default font in the RIP_FONT_STYLE is selected   > v2.A1
(with size of 1).                                                     > v2.A1
                                                                      > v2.A1
The possible (pre-defined) font names are:                            > v2.A1
                                                                      > v2.A1
     Name                Description                                  > v2.A1
     ---------------------------------------------------------------  > v2.A1
     COURIER             Courier mono-spaced font                     > v2.A1
     HELV                Helvetica proportional font                  > v2.A1
     TIMESROM            Times Roman proportional font                > v2.A1
     OLDENGL             Old English (gothic) proportional font       > v2.A1
     SANSSERF            Sans Serif proportional font                 > v2.A1
                                                                      > v2.A1
These pre-defined fonts must be supported by all RIPscrip 2.0 and     > v2.A1
later software packages.  A font name is up to eight characters in    > v2.A1
length.  Other fonts may be specified by an application designer.  In > v2.A1
order for these fonts to be usable by the terminal system, they must  > v2.A1
already exist on the system and have some form of recognizable name   > v2.A1
associated with them.  In RIPscrip 2.0, we define an extended font    > v2.A1
name as a name up to eight character in length.  In order for the     > v2.A1
font to be recognized by the target terminal system it has to         > v2.A1
understand the same font name (presumably a font filename).           > v2.A1
                                                                      > v2.A1
BETA TESTER NOTE:  Any thoughts on some kind of universal way of      > v2.A1
                   implementing this?                                 > v2.A1







---------------------------------------------------------------------
RIP_PIXEL
---------------------------------------------------------------------
         Function:  Draws a one pixel using current drawing color
            Level:  0
          Command:  X
        Arguments:  x:2, y:2
           Format:  !|X <x> <y>
          Example:  !|X1122
  Uses Draw Color:  YES
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  YES                                               > v2.A1
  Uses Font Sizes:  NO
    Uses Viewport:  YES                                               > v1.54

This command will draw a single pixel in the current drawing color at
the given (x,y) graphics position.  This command is included for
completeness, but in practice it would be extremely inefficient to
make much use of it.





---------------------------------------------------------------------
RIP_LINE
---------------------------------------------------------------------
         Function:  Draw a line in the current color/line style
            Level:  0
          Command:  L
        Arguments:  x0:2, y0:2, x1:2, y1:2
           Format:  !|L <x0> <y0> <x1> <y1>
          Example:  !|L00010A0E
  Uses Draw Color:  YES
  Uses Back Color:  YES                                               > v2.A1
Uses Line Pattern:  YES
  Uses Line Thick:  YES
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  YES
  Uses Font Sizes:  NO
    Uses Viewport:  YES                                               > v1.54

This command will draw a line in the current drawing color, using the
current line style, pattern and thickness.  The line is drawn from
(x0,y0) to (x1,y1) in the graphics viewport.





---------------------------------------------------------------------
RIP_RECTANGLE
---------------------------------------------------------------------
         Function:  Draw a rectangle in current color/line style
            Level:  0
          Command:  R
        Arguments:  x0:2, y0:2, x1:2, y1:2
           Format:  !|R <x0> <y0> <x1> <y1>
          Example:  !|R00010A0E
  Uses Draw Color:  YES
  Uses Back Color:  YES                                               > v2.A1
Uses Line Pattern:  YES
  Uses Line Thick:  YES
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  YES
  Uses Font Sizes:  NO
    Uses Viewport:  YES                                               > v1.54

This command draws a rectangle in the current drawing color, using
the current line style, pattern and thickness.  (x0,y0) and (x1,y1)
are any two opposing corners of the rectangle.  If x0=x1 or y0=y1
then the command will draw a single vertical or horizontal line.  The
rectangle interior is not filled by RIP_RECTANGLE.





---------------------------------------------------------------------
RIP_BAR
---------------------------------------------------------------------
         Function:  Draw filled rectangle with fill color/pattern
            Level:  0
          Command:  B
        Arguments:  x0:2, y0:2, x1:2, y1:2
           Format:  !|B <x0> <y0> <x1> <y1>
          Example:  !|B00010A0E
  Uses Draw Color:  NO
  Uses Back Color:  YES                                               > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  YES
Uses Fill Pattern:  YES
  Uses Write Mode:  YES                                               > v2.A1
  Uses Font Sizes:  NO
    Uses Viewport:  YES                                               > v1.54

This command fills a rectangular region with the current fill color
and pattern.  No border is drawn.





---------------------------------------------------------------------
RIP_CIRCLE
---------------------------------------------------------------------
         Function:  Draw circle in current color and line thickness
            Level:  0
          Command:  C
        Arguments:  x_center:2, y_center:2, radius:2
           Format:  !|C <x_center> <y_center> <radius>
          Example:  !|C1E180M
  Uses Draw Color:  YES
  Uses Back Color:  YES                                               > v2.A1
Uses Line Pattern:  YES                                               > v2.A1
  Uses Line Thick:  YES
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  YES                                               > v2.A1
  Uses Font Sizes:  NO
    Uses Viewport:  YES                                               > v1.54

This command draws a circle in the current drawing color and line
thickness.  The <radius> is in pixel units.  This command understands
aspect ratios and will draw a truly circular circle instead of an
oblong circle (ellipse) like on other graphics systems.  The aspect
ratio is currently based on the EGA 640x350 resolution and is
understood by both the GUI designer and the Terminal Program.

NOTE:  This command uses the line thickness setting, but not the line
       patterns.  In other words, you can draw a circle with a thick
       or a thin border, but not a dashed or dotted border.





---------------------------------------------------------------------
RIP_OVAL
---------------------------------------------------------------------
         Function:  Draw elliptical arc in current color/line style
            Level:  0
          Command:  O
        Arguments:  x:2, y:2, st_ang:2, end_ang:2, x_rad:2, y_rad:2
           Format:  !|O <x> <y> <st_ang> <end_ang> <x_rad> <y_rad>
          Example:  1E1A18003G150Z
  Uses Draw Color:  YES
  Uses Back Color:  YES                                               > v2.A1
Uses Line Pattern:  YES                                               > v2.A1
  Uses Line Thick:  YES
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  YES                                               > v2.A1
  Uses Font Sizes:  NO
    Uses Viewport:  YES                                               > v1.54

This command draws an elliptical arc similar to the circular RIP_ARC
command.  The center of the ellipse is (x,y) and the arc is drawn
starting from <st_ang> and proceeding counterclockwise to <end_ang>
(see RIP_ARC above for details).

The X radius is half the full width of the ellipse, the Y radius is
half the full height.  The ellipse is drawn according to the current
line thickness, but the current line pattern has no effect.





---------------------------------------------------------------------
RIP_FILLED_OVAL
---------------------------------------------------------------------
         Function:  Draw filled ellipse using current color/pattern
            Level:  0
          Command:  o
        Arguments:  x_center:2, y_center:2, x_rad:2, y_rad:2
           Format:  !|o <x_center> <y_center> <x_rad> <y_rad>
          Example:  !|o1G2B0M0G
  Uses Draw Color:  YES
  Uses Back Color:  YES                                               > v2.A1
Uses Line Pattern:  YES                                               > v2.A1
  Uses Line Thick:  YES
  Uses Fill Color:  YES
Uses Fill Pattern:  YES
  Uses Write Mode:  YES                                               > v2.A1
  Uses Font Sizes:  NO
    Uses Viewport:  YES                                               > v1.54

This command draws a complete filled ellipse on the screen.  The
interior of the ellipse is drawn using the current fill pattern and
fill color.  The outline of the ellipse is drawn using the current
drawing color and line thickness.





---------------------------------------------------------------------
RIP_ARC
---------------------------------------------------------------------
         Function:  Draw circular arc in current color/line thickness
            Level:  0
          Command:  A
        Arguments:  x:2, y:2, start_ang:2, end_ang:2, radius:2
           Format:  !|A <x> <y> <start_ang> <end_ang> <radius>
          Example:  !|A1E18003G15
  Uses Draw Color:  YES
  Uses Back Color:  YES                                               > v2.A1
Uses Line Pattern:  YES                                               > v2.A1
  Uses Line Thick:  YES
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  YES                                               > v2.A1
  Uses Font Sizes:  NO
    Uses Viewport:  YES                                               > v1.54

This command draws a circular arc, or a segment of a circle.  Drawing
begins at <start_ang> and terminates at <end_ang>.  The angles are
represented starting at zero for the 3 o'clock position and
increasing counterclockwise through a full circle to 360:

                          90
                           |
                     180---|--- 0
                           |
                          270

The arc drawing begins at the <start_angle> and continues counter-
clockwise to the <end_angle>.  A full circle will be displayed if
<start_ang>=0 and <end_ang>=360.  This command recognizes aspect
ratios like the circle command does.  It does not take advantage of
line patterns but does comply with line thickness.

If both angles are equal, nothing is drawn.





---------------------------------------------------------------------
RIP_OVAL_ARC
---------------------------------------------------------------------
         Function:  Draw an elliptical arc
            Level:  0
          Command:  V
        Arguments:  x:2, y:2, st_ang:2, e_ang:2, radx:2 rady:2
           Format:  !|V <x> <y> <st_ang> <e_ang> <radx> <rady>
          Example:  !|V1E18003G151Q
  Uses Draw Color:  YES
  Uses Back Color:  YES                                               > v2.A1
Uses Line Pattern:  YES                                               > v2.A1
  Uses Line Thick:  YES
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  YES                                               > v2.A1
  Uses Font Sizes:  NO
    Uses Viewport:  YES                                               > v1.54

This command draws an elliptical arc, or a segment of an ellipse.
Drawing begins at <st_ang> and terminates at <e_ang>.  The angles are
represented starting at zero for 3 o'clock position and increasing
counterclockwise through a full ellipse at 360 degrees:

                          90
                           |
                     180---|--- 0
                           |
                          270

The arc drawing begins at the <st_ang> and continues counterclockwise
to the <e_ang>.  A complete ellipse will be displayed if <st_ang>=0
and <e_ang>=360.  This command does not utilize "aspect ratios"
because of the nature of an Ellipse.  It does not take advantage of
line patterns but does comply with line thickness.





---------------------------------------------------------------------
RIP_PIE_SLICE
---------------------------------------------------------------------
         Function:  Draws a circular pie slice
            Level:  0
          Command:  I
        Arguments:  x:2, y:2, start_ang:2, end_ang:2, radius:2
           Format:  !|I <x> <y> <start_ang> <end_ang> <radius>
          Example:  !|I1E18003G15
  Uses Draw Color:  YES
  Uses Back Color:  YES                                               > v2.A1
Uses Line Pattern:  YES                                               > v2.A1
  Uses Line Thick:  YES
  Uses Fill Color:  YES
Uses Fill Pattern:  YES
  Uses Write Mode:  YES                                               > v2.A1
  Uses Font Sizes:  NO
    Uses Viewport:  YES                                               > v1.54

This command draws a "pie slice".  The slice is circular.  It obeys
all of the same commands as the Arc command described above.  The
ends of the arc are connected to the Center-Point of the Arc with two
straight lines.  These two lines converge at the Center-Point.  The
interior of the Slice is filled with the current Fill Color and
Pattern.  The exterior (outline) of the Slice is drawn using the
current drawing color and line thickness.  The Line Pattern feature
does not apply to this command.





---------------------------------------------------------------------
RIP_OVAL_PIE_SLICE
---------------------------------------------------------------------
         Function:  Draws an elliptical pie slice
            Level:  0
          Command:  i
        Arguments:  x:2, y:2, st_ang:2, e_ang:2, radx:2 rady:2
           Format:  !|i <x> <y> <st_ang> <e_ang> <radx> <rady>
          Example:  !|i1E18003G151Q
  Uses Draw Color:  YES
  Uses Back Color:  YES                                               > v2.A1
Uses Line Pattern:  YES                                               > v2.A1
  Uses Line Thick:  YES
  Uses Fill Color:  YES
Uses Fill Pattern:  YES
  Uses Write Mode:  YES                                               > v2.A1
  Uses Font Sizes:  NO
    Uses Viewport:  YES                                               > v1.54

This command draws an  "elliptical pie slice".  It obeys all of the
same commands as the Elliptical Arc command described above.  The
ends of the arc are connected to the Center-Point of the Arc with two
straight lines.  These two lines converge at the Center-Point.  The
interior of the Slice is filled with the current Fill Color and
Pattern.  The exterior (outline) of the Slice is drawn using the
current drawing color and line thickness.  The Line Pattern feature
does not apply to this command.





---------------------------------------------------------------------
RIP_BEZIER
---------------------------------------------------------------------
         Function:  Draw a bezier curve
            Level:  0
          Command:  Z
        Arguments:  x1:2 y1:2 x2:2 y2:2 x3:2 y3:2 x4:2 y4:2 cnt:2
           Format:  !|Z <x1> <y1> <x2> <y2> <x3> <y3> <x4> <y4> <cnt>
          Example:  !|Z0A0B0C0D0E0F0G0H1G
  Uses Draw Color:  YES
  Uses Back Color:  YES                                               > v2.A1
Uses Line Pattern:  YES
  Uses Line Thick:  YES
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  YES
  Uses Font Sizes:  NO
    Uses Viewport:  YES                                               > v1.54

This command provides customizable curves.  Four control points are
used to create the shape of the curve.  The curves beginning point is
at point (x1,y1) and it ends at (x4,y4).  Points (x2,y2) and (x3,y3)
are not necessarily on the curve, but are used to pull the curve in
their direction.  The diagram below indicates how points 2 and 3 can
be utilized to form the desired curve.  Note that points 2 and 3 are
not actually on the curve, but points 1 and 4 are.

                          X2

                         *****
                       **     ****
                      *           **            X4
                     *              **          *
                   X1                 *       **
                                       *    **
                                        ****

                                         X3

NOTE: Points 2 and 3 are not actually on the curve - points 1 and 4
      are.

The last parameter of this command is the <cnt> parameter.  This
determines how many "segments" the curve should be drawn in.  Each
segment is in fact, a straight line.  The more segments you allow,
the smoother the curve may be.  If a curve does not have a
significant amount of "curviness" then a low "count" can improve
performance of the curve drawing.  Bezier Curves use "floating point"
math internally for its processing.  All parameters specified for
this command are simple integers however.

Each segment of the Bezier Curve will be drawn using the current      > v1.54
line style pattern and thickness.  You can achieve some unusual       > v1.54
effects using patterned lines for Bezier Curves.  If XOR is active    > v1.54
when you draw a bezier curve, you will find gaps at the inter-        > v1.54
sections of each segment.                                             > v1.54

NOTE: This command is implemented in C using double floating point    > v1.54
      numbers.  To make sure you do not have round-off or precision   > v1.54
      errors in another language, you should also use an equivalent   > v1.54
      floating point type.  In Borland's Turbo Pascal, do not use     > v1.54
      REAL's, but use DOUBLE's instead!                               > v1.54



--------------------------------------------------------------------- > v2.A1
RIP_POLY_BEZIER                                                       > v2.A1
--------------------------------------------------------------------- > v2.A1
         Function:  Draw a poly-bezier curve (multi-segmented)        > v2.A1
            Level:  0                                                 > v2.A1
          Command:  z                                                 > v2.A1
        Arguments:  num:2 count:2 x_base:2 y_base:2 ...               > v2.A1
           Format:  !|z <num> <count> <x_base> <y_base> ...           > v2.A1
          Example:  !|Z0A0B0C0D0E0F0G0H1G                             > v2.A1
  Uses Draw Color:  YES                                               > v2.A1
  Uses Back Color:  YES                                               > v2.A1
Uses Line Pattern:  YES                                               > v2.A1
  Uses Line Thick:  YES                                               > v2.A1
  Uses Fill Color:  NO                                                > v2.A1
Uses Fill Pattern:  NO                                                > v2.A1
  Uses Write Mode:  YES                                               > v2.A1
  Uses Font Sizes:  NO                                                > v2.A1
    Uses Viewport:  YES                                               > v2.A1
                                                                      > v2.A1
This command is a variation on the RIP_BEZIER command.  The typical   > v2.A1
RIP_BEZIER command creates one single bezier curve.  This command     > v2.A1
combines one or more bezier curves into a chain of connected bezier   > v2.A1
curves.  Each segment (curve) of the poly-bezier can be of different  > v2.A1
types.  It can be a bezier curve, or a simple straight line.  The     > v2.A1
combination of these facilities allows the construction of say, a     > v2.A1
text character of a font that has some straight line segments and     > v2.A1
some curves segments.  The curved portions (bezier curves) are        > v2.A1
actually comprised of many smaller straight line segments - when      > v2.A1
viewed on a monitor, they appear to be a continuous curve.  The       > v2.A1
actual number of segments comprising a particular curve in the        > v2.A1
poly-bezier is determined by the command's <count> parameter.         > v2.A1
                                                                      > v2.A1
This command is different than any other in RIPscrip in that its      > v2.A1
variable length portion of the command is made up of different blocks > v2.A1
of parameters which can be different byte lengths!  If you look at    > v2.A1
the definition, the beginning of the command includes a <num>,        > v2.A1
<count>, <x_base> and <y_base> parameter.  The <count> parameter      > v2.A1
defines how many "segments" are to be drawn for each bezier curve     > v2.A1
segment of this poly-bezier curve.  This means that all bezier curve  > v2.A1
segments in a poly-bezier will have the same number of segments for   > v2.A1
their respective curves.  The <num> parameter defines how many        > v2.A1
parameter blocks are to be expected in this command.                  > v2.A1
                                                                      > v2.A1
The (x_base,y_base) parameters define the pixel beginning point for   > v2.A1
the entire poly-bezier "curve".  To determine what type of parameter  > v2.A1
block follows, you need to look at the first byte of the block; this  > v2.A1
is the <type> parameter.                                              > v2.A1
                                                                      > v2.A1
The <type> parameter defines what type of parameter block is to be    > v2.A1
parsed.  The possible types are:                                      > v2.A1
                                                                      > v2.A1
     Type  Description                                                > v2.A1
     ---------------------------                                      > v2.A1
       0   Bezier curve segment                                       > v2.A1
       1   Locked Bezier curve segment                                > v2.A1
       2   Straight line segment                                      > v2.A1

A "locked Bezier Curve" is a bezier curve whose beginning curve is    > v2.A1
totally smooth with the ending curve of a previous bezier curve.  In  > v2.A1
practice on a terminal system, this doesn't mean anything to a        > v2.A1
terminal program because it is going to display a bezier curve as a   > v2.A1
normal bezier curve.  The meaning of having a second bezier curve     > v2.A1
type comes into play when using paint program utilities that let you  > v2.A1
manipulate poly-bezier curves.  A paint system might use this         > v2.A1
information to control how end-points and control points can be moved > v2.A1
because they are "locked" with one or two points from the previous    > v2.A1
(or next) bezier curve.  See the notes at the end of this command's   > v2.A1
description about smooth bezier curve joints.                         > v2.A1
                                                                      > v2.A1
If the <type> indicates that the segment is a bezier curve, then the  > v2.A1
parameter block contains six parameters as in the following syntax    > v2.A1
definition (not including the <type> parameter):                      > v2.A1
                                                                      > v2.A1
     type:1 x1:2 y1:2 x2:2 y2:2 x3:2 y3:2                             > v2.A1
                                                                      > v2.A1
The first byte is the <type> value for this block (be set to 0 or 1   > v2.A1
for a bezier curve segment).  The remaining six parameters define the > v2.A1
first two control points and the end-point for the bezier curve       > v2.A1
segment.  The beginning point of the curve segment is defined as the  > v2.A1
end-point of the previous block (or the (x_base,y_base) parameter in  > v2.A1
the header of the command if this is the first parameter block).      > v2.A1
                                                                      > v2.A1
Refer to the RIP_BEZIER command for a complete description of bezier  > v2.A1
curve beginning/end-points and how control points shape the curve to  > v2.A1
a desired result.                                                     > v2.A1
                                                                      > v2.A1
If the <type> parameter indicates that the segment is a straight-line > v2.A1
segment, then there are only two remaining parameters (not including  > v2.A1
the <type> parameter) in the block (the line's end-points) as in the  > v2.A1
following syntax definition:                                          > v2.A1
                                                                      > v2.A1
     type:1 x1:2 y1:2                                                 > v2.A1
                                                                      > v2.A1
The <type> parameter should be set to "2" for line segments.  The     > v2.A1
(x1,y1) parameters define the endpoints of the line segment.  The     > v2.A1
beginning point of the line is the end-point of the last segment (or  > v2.A1
the (x_base,y_base) parameters of the command header if this is the   > v2.A1
first parameter block).                                               > v2.A1

An example of a poly-bezier curve might be shown as follows:          > v2.A1
                                                                      > v2.A1
      Segment 1 ____________    P2                                    > v2.A1
        (line)      P1      \ (40,10)       P3 (50,10)                > v2.A1
                 (20,10) X*****X**         X                          > v2.A1
                         *        **    _____________ Segment 2       > v2.A1
                         *          ** /               (bezier)       > v2.A1
                         *            *                               > v2.A1
                         *            *        X P4 (70,35)           > v2.A1
         Segment 0 ----- *      P5  **                                > v2.A1
           (line)        * (55,45) X                                  > v2.A1
                         *          **         X P6 (70,75)           > v2.A1
                         *            * _______________ Segment 3     > v2.A1
                         *            *                  (bezier)     > v2.A1
                         *  (50,90) **                                > v2.A1
              BASE       *     P8 **        P7 (50,90)                > v2.A1
              POINT ---> X*****X**         X                          > v2.A1
                       P0/P9 \________________________ Segment 4      > v2.A1
                      (20,90)                            (line)       > v2.A1
                                                                      > v2.A1
The above diagram shows 5 different segments to the poly-bezier       > v2.A1
curve.  Segments 0, 1 and 4 are straight line segments, and semgents  > v2.A1
2 and 3 are actual bezier curves.  All X/Y points (beginning-points,  > v2.A1
end-points and control-points are depicted with X's and are labeled   > v2.A1
P0 through P9.  The parameters to represent this command might        > v2.A1
appear something like the following (in expanded decimal):            > v2.A1
                                                                      > v2.A1
     !|z 05 ........ 5 segments                                       > v2.A1
         10 ........ 10 lines per bezier curve                        > v2.A1
         20 90 ..... Base point - P0                                  > v2.A1
         2 ......... SEGMENT 0 - LINE                                 > v2.A1
           20 10 ... Line endpoint - P1                               > v2.A1
         2 ......... SEGMENT 1 - LINE                                 > v2.A1
           40 10 ... Line endpoint - P2                               > v2.A1
         0 ......... SEGMENT 2 - BEZIER                               > v2.A1
           50 10 ... Control point - P3                               > v2.A1
           70 35 ... Control point - P4                               > v2.A1
           55 45 ... Curve end point - P5                             > v2.A1
         0 ......... SEGMENT 3 - BEZIER                               > v2.A1
           70 75 ... Control point - P6                               > v2.A1
           50 90 ... Control point - P7                               > v2.A1
           50 90 ... Curve end point - P8                             > v2.A1
         2 ......... SEGMENT 4 - LINE                                 > v2.A1
           20 90 ... Line endpoint - P9                               > v2.A1
                                                                      > v2.A1
Notice that in the preceding example we are not expressing numbers in > v2.A1
meganums as would normally be used in RIPscrip files.  This is for    > v2.A1
simple human readability for this example.                            > v2.A1
                                                                      > v2.A1
This command is often used to combine several segments together       > v2.A1
into one larger "curve".  As previously mentioned, the end-point of   > v2.A1
one segment is the beginning point of the next segment (if any).      > v2.A1

When you are dealing with bezier curve segments, it is possible to    > v2.A1
make sure that the end of one curve has a perfectly smooth curve with > v2.A1
the beginning of the next curve.  If two adjacent bezier curve blocks > v2.A1
are to have a perfectly smooth "connecting joint", then you must make > v2.A1
sure that the last control point and the end-point of the first curve > v2.A1
are colinear with the first control point of the second curve.  This  > v2.A1
is not a requirement of this command - it is generic in that it can   > v2.A1
display any combination of line segments and bezier curve segments.   > v2.A1
We are simply noting this mathematical attribute of bezier curves for > v2.A1
the benefit of the RIPscrip programmer to generate smooth segmented   > v2.A1
curves in some sort of paint program.                                 > v2.A1
                                                                      > v2.A1
A bezier curve can also have a "smooth joint" with a line segment. If > v2.A1
the bezier curve is followed by a line segment, then to make sure     > v2.A1
that the joint has a smooth curve, you must make sure that the last   > v2.A1
control point and the end point of the bezier curve segment are       > v2.A1
colinear with the end-point of the following line segment.  The same  > v2.A1
holds true of the segments are reversed (line segment followed by a   > v2.A1
bezier curve segment) - the only difference is that the beginning     > v2.A1
point of a line segment is determined by the end-point of its         > v2.A1
preceding block (or the base point if the line segment is the first   > v2.A1
parameter block) and you would be making the starting point of the    > v2.A1
bezier curve and the 1ST control point colinear.                      > v2.A1
                                                                      > v2.A1
NOTE:  Poly-Bezier curves might exhibit pixel annomolies at the       > v2.A1
beginning and ending points of each segment if thick lines are used   > v2.A1
for the curve with XOR or other non-COPY write modes.  The reason for > v2.A1
this is because some graphics engines (Windows, Macintosh, MS-DOS,    > v2.A1
etc) might not handle things 100.0% perfectly for thick poly-lines in > v2.A1
XOR mode (poly-lines are used to represent this command after all     > v2.A1
segments are broken down).                                            > v2.A1




---------------------------------------------------------------------
RIP_POLYGON
---------------------------------------------------------------------
         Function:  Draw polygon in current color/line-style
            Level:  0
          Command:  P
        Arguments:  npoints:2, x1:2, y1:2, ... xn:2, yn:2
           Format:  !|P <npoints> <x1> <y1> ... <xn> <yn>
          Example:  !|P03010105090905
  Uses Draw Color:  YES
  Uses Back Color:  YES                                               > v2.A1
Uses Line Pattern:  YES
  Uses Line Thick:  YES
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  YES
  Uses Font Sizes:  NO
    Uses Viewport:  YES                                               > v1.54

This command will draw a multi-sided closed polygon.  The polygon is
drawn using the current drawing color, line pattern and thickness.
The <npoints> parameter is between 2 and 512 and indicates how many
(x,y) coordinate pairs will follow, which is also the number of sides
of the polygon.  The polygon interior is not filled by RIP_POLYGON.

The polygon is enclosed by the last vertex between xn,yn and x1,y1.
In other words, you do not have to connect the end to the beginning -
it is automatically done for you.





---------------------------------------------------------------------
RIP_FILL_POLYGON
---------------------------------------------------------------------
         Function:  Draw filled polygon in current color/fill pattern
            Level:  0
          Command:  p
        Arguments:  npoints:2, x1:2, y1:2, ... xn:2, yn:2
           Format:  !|p <npoints> <x1> <y1> ... <xn> <yn>
          Example:  !|p03010105050909
  Uses Draw Color:  YES
  Uses Back Color:  YES                                               > v2.A1
Uses Line Pattern:  YES
  Uses Line Thick:  YES
  Uses Fill Color:  YES
Uses Fill Pattern:  YES
  Uses Write Mode:  YES
  Uses Font Sizes:  NO
    Uses Viewport:  YES                                               > v1.54

This command is identical to RIP_POLYGON, except that the interior of
the polygon is filled with the current fill color and fill pattern.
The actual outline of the polygon is drawn using the current drawing
color, line pattern and thickness.

NOTE:  You will get unusual effects if the lines of the polygon
       overlap, creating a polygon with internal "gaps".  (The rule
       is this: regions that are "inside" the polygon an even number
       of times due to overlap are NOT filled.)  The interior fill
       does not utilize Write Mode, but the outline of the polygon
       does.





--------------------------------------------------------------------- > v1.54
RIP_POLYLINE                                                          > v1.54
--------------------------------------------------------------------- > v1.54
         Function:  Draw a Poly-Line (multi-faceted line)             > v1.54
            Level:  0                                                 > v1.54
          Command:  l                                                 > v1.54
        Arguments:  npoints:2, x1:2, y1:2, ... xn:2, yn:2             > v1.54
           Format:  !|l <npoints> <x1> <y1> ... <xn> <yn>             > v1.54
          Example:  !|l03010105090905                                 > v1.54
  Uses Draw Color:  YES                                               > v1.54
  Uses Back Color:  YES                                               > v2.A1
Uses Line Pattern:  YES                                               > v1.54
  Uses Line Thick:  YES                                               > v1.54
  Uses Fill Color:  NO                                                > v1.54
Uses Fill Pattern:  NO                                                > v1.54
  Uses Write Mode:  YES                                               > v1.54
  Uses Font Sizes:  NO                                                > v1.54
    Uses Viewport:  YES                                               > v1.54
                                                                      > v1.54
This command will draw a multi-faceted line.  It is identical in      > v1.54
nature to the RIP_POLYGON command above, except that the last point   > v1.54
is NOT connected to the first point.  Generally speaking, a Poly-     > v1.54
Line is not an "enclosed area".  It should not be filled unless       > v1.54
you are very careful to close the shape so that it leaves a fillable  > v1.54
area.  The segments of the Poly-Line are drawn using the current      > v1.54
drawing color, line pattern, thickness and Drawing Write Mode.        > v1.54
                                                                      > v1.54
The <npoints> parameter is between 2 and 512 and indicates how many   > v1.54
(x,y) coordinate pairs will follow, which is also the number of sides > v1.54
of the Poly-Line.                                                     > v1.54
                                                                      > v1.54
An example of a five sided (6 vertices) Poly-Line might be:           > v1.54
                                                                      > v1.54
               X                 P4         X                         > v1.54
             P1 \                  X       / P6                       > v1.54
                 \                /|      /                           > v1.54
                  \              / |     /                            > v1.54
                   \            /  |    /                             > v1.54
                    \          /   |   /                              > v1.54
                     X--------X    |  /                               > v1.54
                   P2       P3     | /                                > v1.54
                                 P5|/                                 > v1.54
                                   X                                  > v1.54
                                                                      > v1.54




---------------------------------------------------------------------
RIP_FILL
---------------------------------------------------------------------
         Function:  Flood fill screen area with current fill settings
            Level:  0
          Command:  F
        Arguments:  x:2, y:2, border:4                                > v2.A0
           Format:  !|F <x> <y> <border>
          Example:  !|F25090F
  Uses Draw Color:  NO
  Uses Back Color:  NO (1.xx only)                                    > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  YES
Uses Fill Pattern:  YES
  Uses Write Mode:  NO
  Uses Font Sizes:  NO
    Uses Viewport:  YES                                               > v1.54

This command performs a "flood fill" emanating from the given <x,y>
point.  The fill "oozes" in all directions up to <border> color, but
the border itself is not changed.  Whatever is inside the border
that's not the border color gets changed to the current fill color
and fill pattern.  If the border color does not completely enclose
the <x,y> point, the fill will continue to the edges of the viewport.

If the point on the screen that is chosen as the "fill point" is the  > v1.54
same color as the fill border color, then no Fill Operation will be   > v1.54
performed!  This restriction is necessary because of some limitations > v1.54
of Flood Fill abilities in different hardware/software environments   > v1.54
like Microsoft Windows, etc).                                         > v1.54

The <border> parameter of this command serves two purposes depending  > v2.A0
on what Color Mode is currently set.  The default mode, Color Map     > v2.A0
mode, signifies that the border parameter of this command will use    > v2.A0
the parameter as an index into the 256 color Drawing Palette color    > v2.A0
mapping table.  In this mode, this parameter will use the current     > v2.A0
Base Math set by the global RIP_SET_BASE_MATH command.                > v2.A0
                                                                      > v2.A0
In Direct RGB Color Mode, the border parameter will be a four-digit   > v2.A0
UltraNum (regardless of the current Base Math setting).  This numeric > v2.A0
value will be an encoded RGB value, allowing you to use arbitrary RGB > v2.A0
colors directly with the Fill command.  If the RGB color is not       > v2.A0
permissable, the closest match from the Color Map table will be       > v2.A0
located and used.  The number of bits of precision used in the        > v2.A0
encoded RGB value will be determined by the RIP_SET_COLOR_MODE        > v2.A0
command.                                                              > v2.A0
                                                                      > v2.A0
When Color Mapping Mode is in use, the border parameter may be        > v2.A0
shorter than four digits.  This is for space savings, as it is        > v2.A0
allowable in the specification for the last numeric parameter in a    > v2.A0
parameter list to be "shorter" than the full length.                  > v2.A0

NOTE:  A flood-fill operation is only allowed in v1.54 and earlier    > v2.A1
       RIPscrip files.  The command is no longer allowed in 2.0 type  > v2.A1
       files because of a large number of technical issues with       > v2.A1
       color palette independence and resolution independence.        > v2.A1
       This command will be ignored unless it is specifically being   > v2.A1
       used in a file that has a RIP_HEADER command with a revision   > v2.A1
       code of "00" (1.54.00 code).                                   > v2.A1





---------------------------------------------------------------------
RIP_LINE_STYLE
---------------------------------------------------------------------
         Function:  Defines a line style and thickness
            Level:  0
          Command:  =
        Arguments:  odd_draw:1 style:1, user_pat:4, thick:2           > v2.A1
           Format:  !|= <odd_draw> <style> <user_pat> <thick>         > v2.A1
          Example:  !|=01000001
  Uses Draw Color:  NO
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  YES
  Uses Line Thick:  YES
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  NO
  Uses Font Sizes:  NO
    Uses Viewport:  NO                                                > v1.54

This command establishes the current line pattern and thickness for
many subsequent graphics primitive commands.  There are four built-in
line styles plus provisions for custom line patterns.

     Style   Description           Binary            Hex              > v1.54
     ----------------------------------------------------             > v1.54
      0      Normal, Solid Line    1111111111111111  FFFF             > v1.54
      1      Dotted Line           0011001100110011  3333             > v1.54
      2      Centered Line         0001111000111111  1E3F             > v1.54
      3      Dashed Line           0001111100011111  1F1F             > v1.54
      4      Custom Defined line (see about <user_pat> below)

If the <style> is set to a value of 4 (custom pattern), then the
<user_pat> parameter is used as a 16-bit representation of the pixels
in the line pattern.  For example:

Repeating Pattern     Binary Coding     Hex     Decimal   MegaNum
-------------------------------------------------------------------
 - - - - - - - -    1010101010101010    AAAA     43690     0XPM
 ----    ----       1111000011110000    F0F0     61680     1BLC

So, the most-significant-bit of <user_pat> is toward the starting
point of the line or border that uses this fill pattern.  If the
<style> parameter is not 4, then the <user_pat> parameter is ignored.

In v2.0 of RIPscrip, the odd spaces of a patterned line can now be    > v2.A1
something other than transparent (as in 1.x RIPscrip format).  If     > v2.A1
the <odd_draw> parameter is set to a non-zero value, then the current > v2.A1
pen background color is used to draw the odd spaces of a patterned    > v2.A1
line.  The values of the <odd_draw> field are as follows:             > v2.A1
                                                                      > v2.A1
     Value   Description                                              > v2.A1
     --------------------------------------------------               > v2.A1
       0     Draw odd spaces as transparent pixels                    > v2.A1
       1     Draw odd spaces using pen background color               > v2.A1
                                                                      > v2.A1
In earlier verions of RIPscrip (v1.54 and earlier), only two          > v2.A1
different line thickness options were allowed (1 pixel wide and 3     > v2.A1
pixels wide).  In 2.00 and later revisions, arbitrary thicknesses of  > v2.A1
lines are supported from 1 pixel on up.  If the thickness is an even  > v2.A1
number than it is up to the destination system's graphics engine to   > v2.A1
determine whether the even pixel is drawn to the left or right of the > v2.A1
center point in vertical orientations, or above/below for horizontal  > v2.A1
orientations.  In any event, the thickness value of lines is          > v2.A1
specified by the <thick> parameter.                                   > v2.A1

---------------------------------------------------------------------
RIP_FILL_STYLE
---------------------------------------------------------------------
         Function:  Set current fill style (predefined) & fill color
            Level:  0
          Command:  S
        Arguments:  pattern:2, color:4                                > v2.A0
           Format:  !|S <pattern> <color>
          Example:  !|S050F
  Uses Draw Color:  NO
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  YES
Uses Fill Pattern:  YES
  Uses Write Mode:  NO
  Uses Font Sizes:  NO
    Uses Viewport:  NO                                                > v1.54

This command defines the current fill pattern and fill color for use
in subsequent graphics fill operations.  There are twelve (12)
predefined fill patterns.  They are:

    Pattern  Description                 Example       Misc
    -----------------------------------------------------------------
      00     Fill with background color                (color #0)
      01     Solid Fill                                (fill color)
      02     Line Fill                   -----------   (thick lines)
      03     Light Slash Fill            /  /  /  /    (thin lines)
      04     Normal Slash Fill           // // // //   (thick lines)
      05     Normal Backslash Fill       \\ \\ \\ \\   (thick lines)
      06     Light Backslash Fill        \  \  \  \    (thin lines)
      07     Light Hatch Fill            ###########   (thin lines)
      08     Heavy Cross Hatch Fill      XXXXXXXXXXX   (thin lines)
      09     Interleaving Line Fill      +-+-+-+-+-+   (thin lines)
      0A     Widely spaced dot fill      . : . : . :   (pixels only)
      0B     Closely spaced dot fill     :::::::::::   (pixels only)

The <color> parameter is the fill color for subsequent fill commands.
The "active" pixels of the pattern become this color.  The "inactive"
pixels become the current background color (color 00, typically
black).  Fill pattern 00 will set the entire fill area to the
background color.  (In this case, the fill color doesn't matter).

The <color> parameter of this command serves two purposes depending   > v2.A0
on what Color Mode is currently set.  The default mode, Color Map     > v2.A0
mode, signifies that the color parameter of this command will use the > v2.A0
parameter as an index into the 256 color Drawing Palette color        > v2.A0
mapping table.  In this mode, this parameter will use the current     > v2.A0
Base Math set by the global RIP_SET_BASE_MATH command.                > v2.A0
                                                                      > v2.A0
In Direct RGB Color Mode, the color parameter will be a four-digit    > v2.A0
UltraNum (regardless of the current Base Math setting).  This numeric > v2.A0
value will be an encoded RGB value, allowing you to set arbitrary RGB > v2.A0
colors directly with the Fill Style commands. If the RGB color is not > v2.A0
permissable, the closest match from the Color Map table will be       > v2.A0
located and used.  The number of bits of precision used in the        > v2.A0
encoded RGB value will be determined by the RIP_SET_COLOR_MODE        > v2.A0
command.                                                              > v2.A0
                                                                      > v2.A0
When Color Mapping Mode is in use, the color parameter may be shorter > v2.A0
than four digits.  This is for space savings, as it is allowable in   > v2.A0
the specification for the last numeric parameter in a parameter list  > v2.A0
to be "shorter" than the full length.                                 > v2.A0

The following twelve diagrams show visually what each fill pattern    > v1.54
appears like.  Next to each diagram are the eight numerical values    > v1.54
which represent the monochrome bit-pattern of each line of each       > v1.54
pattern.  Numbers are shown in Hexadecimal (base 16), decimal (base   > v1.54
10) and MegaNum (base 36):                                            > v1.54
                                                                      > v1.54
                                                                      > v1.54
       BACKGROUND FILL                      SOLID FILL                > v1.54
                                                                      > v1.54
     --------   HEX DEC MEGA          --------   HEX DEC MEGA         > v1.54
    |        |  00    0  00          |########|  FF  255  73          > v1.54
    |        |  00    0  00          |########|  FF  255  73          > v1.54
    |        |  00    0  00          |########|  FF  255  73          > v1.54
    |        |  00    0  00          |########|  FF  255  73          > v1.54
    |        |  00    0  00          |########|  FF  255  73          > v1.54
    |        |  00    0  00          |########|  FF  255  73          > v1.54
    |        |  00    0  00          |########|  FF  255  73          > v1.54
    |        |  00    0  00          |########|  FF  255  73          > v1.54
     --------                         --------                        > v1.54
        00                               01                           > v1.54
                                                                      > v1.54
                                                                      > v1.54
                                                                      > v1.54
           LINE FILL                     LIGHT SLASH FILL             > v1.54
                                                                      > v1.54
     --------   HEX DEC MEGA          --------   HEX DEC MEGA         > v1.54
    |########|  FF  255  73          |       #|  01    1  01          > v1.54
    |########|  FF  255  73          |      # |  02    2  02          > v1.54
    |        |  00    0  00          |     #  |  04    4  04          > v1.54
    |        |  00    0  00          |    #   |  08    8  08          > v1.54
    |########|  FF  255  73          |   #    |  10   16  0G          > v1.54
    |########|  FF  255  73          |  #     |  20   32  0W          > v1.54
    |        |  00    0  00          | #      |  40   64  1S          > v1.54
    |        |  00    0  00          |#       |  80  128  3K          > v1.54
     --------                         --------                        > v1.54
        02                               03                           > v1.54
                                                                      > v1.54
                                                                      > v1.54
                                                                      > v1.54
                                                                      > v1.54
        NORMAL SLASH FILL               LIGHT BACKSLASH FILL          > v1.54
                                                                      > v1.54
     --------   HEX DEC MEGA          --------   HEX DEC MEGA         > v1.54
    |###     |  E0  224  68          |####    |  F0  240  60          > v1.54
    |##     #|  C1  193  5D          | ####   |  78  120  3C          > v1.54
    |#     ##|  83  131  3N          |  ####  |  3C   60  1O          > v1.54
    |     ###|  07    7  07          |   #### |  1E   30  0U          > v1.54
    |    ### |  0E   15  0F          |    ####|  0F   15  0F          > v1.54
    |   ###  |  1C   28  0S          |#    ###|  87  135  3R          > v1.54
    |  ###   |  38   56  1K          |##    ##|  C3  195  5F          > v1.54
    | ###    |  70  112  34          |###    #|  E1  225  69          > v1.54
     --------                         --------                        > v1.54
        04                               05                           > v1.54
                                                                      > v1.54
                                                                      > v1.54
                                                                      > v1.54
                                                                      > v1.54

      LIGHT BACKSLASH FILL               LIGHT HATCH FILL             > v1.54
                                                                      > v1.54
     --------   HEX DEC MEGA          --------   HEX DEC MEGA         > v1.54
    |# #  # #|  A5  165  4L          |########|  FF  255  73          > v1.54
    |## #  # |  D2  210  5U          |#   #   |  88  136  3S          > v1.54
    | ## #  #|  69  105  2X          |#   #   |  88  136  3S          > v1.54
    |# ## #  |  B4  180  50          |#   #   |  88  136  3S          > v1.54
    | # ## # |  5A   90  2I          |########|  FF  255  73          > v1.54
    |  # ## #|  2D   45  19          |#   #   |  88  136  3S          > v1.54
    |#  # ## |  96  150  46          |#   #   |  88  136  3S          > v1.54
    | #  # ##|  4B   75  23          |#   #   |  88  136  3S          > v1.54
     --------                         --------                        > v1.54
        06                               07                           > v1.54
                                                                      > v1.54
                                                                      > v1.54
                                                                      > v1.54
                                                                      > v1.54
     HEAVY CROSS HATCH FILL           INTERLEAVING LINE FILL          > v1.54
                                                                      > v1.54
     --------   HEX DEC MEGA          --------   HEX DEC MEGA         > v1.54
    |#      #|  81  129  3L          |##  ##  |  CC  204  5O          > v1.54
    | #    # |  42   66  1U          |  ##  ##|  33   51  1F          > v1.54
    |  #  #  |  24   36  10          |##  ##  |  CC  204  5O          > v1.54
    |   ##   |  18   24  0O          |  ##  ##|  33   51  1F          > v1.54
    |   ##   |  18   24  0O          |##  ##  |  CC  204  5O          > v1.54
    |  #  #  |  24   36  10          |  ##  ##|  33   51  1F          > v1.54
    | #    # |  42   66  1U          |##  ##  |  CC  204  5O          > v1.54
    |#      #|  81  129  3L          |  ##  ##|  33   51  1F          > v1.54
     --------                         --------                        > v1.54
        08                               09                           > v1.54
                                                                      > v1.54
                                                                      > v1.54
                                                                      > v1.54
                                                                      > v1.54
     WIDELY SPACED DOT FILL           CLOSELY SPACED DOT FILL         > v1.54
                                                                      > v1.54
     --------   HEX DEC MEGA          --------   HEX DEC MEGA         > v1.54
    |#       |  80  128  3K          |#   #   |  88  136  3S          > v1.54
    |        |  00    0  00          |        |  00    0  00          > v1.54
    |    #   |  08    8  08          |  #   # |  22   34  0Y          > v1.54
    |        |  00    0  00          |        |  00    0  00          > v1.54
    |#       |  80  128  3K          |#   #   |  88  136  3S          > v1.54
    |        |  00    0  00          |        |  00    0  00          > v1.54
    |    #   |  08    8  08          |  #   # |  22   34  0Y          > v1.54
    |        |  00    0  00          |        |  00    0  00          > v1.54
     --------                         --------                        > v1.54
        0A                               0B                           > v1.54





---------------------------------------------------------------------
RIP_FILL_PATTERN
---------------------------------------------------------------------
         Function:  Set user-definable (custom) fill pattern/color
            Level:  0
          Command:  s
        Arguments:  c1:2 c2:2 c3:2 c4:2 c5:2 c6:2 c7:2 c8:2 col:4     > v2.A0
           Format:  !|s <c1> <c2> <c3> <c4> <c5> <c6> <c7> <c8> <col>
          Example:  !|s11223344556677880F
  Uses Draw Color:  NO
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  YES
Uses Fill Pattern:  YES
  Uses Write Mode:  NO
  Uses Font Sizes:  NO
    Uses Viewport:  NO                                                > v1.54

This command allows you to specify a user-defined, custom Fill
Pattern.  This pattern supersedes the predefined patterns of
RIP_FILL_STYLE.  A custom fill pattern is an 8x8 pixel array defining
which pixels should be drawn in the current fill color (as set by the
<col> parameter here).  The other pixels in the fill area are set to
the current background color (color 00, typically black).

Each of the eight parameters of this command, <c1> through <c8>
represent bit-patterns for a line of the 8x8 pixel array.  Each line
is comprised of 8 pixels.  The value of each parameter is the binary
representation of these 8 pixels as follows:

     Bit     7     6    5    4   3   2   1   0
     ----------------------------------------------
     c1     128   64   32   16   8   4   2   1
     c2     128   64   32   16   8   4   2   1
     c3     128   64   32   16   8   4   2   1
     c4     128   64   32   16   8   4   2   1
     c5     128   64   32   16   8   4   2   1
     c6     128   64   32   16   8   4   2   1
     c7     128   64   32   16   8   4   2   1
     c8     128   64   32   16   8   4   2   1

So, c1 is the top, and the most-significant bit is to the left.

The <col> parameter of this command serves two purposes depending     > v2.A0
on what Color Mode is currently set.  The default mode, Color Map     > v2.A0
mode, signifies that the color parameter of this command will use the > v2.A0
parameter as an index into the 256 color Drawing Palette color        > v2.A0
mapping table.  In this mode, this parameter will use the current     > v2.A0
Base Math set by the global RIP_SET_BASE_MATH command.                > v2.A0
                                                                      > v2.A0
In Direct RGB Color Mode, the color parameter will be a four-digit    > v2.A0
UltraNum (regardless of the current Base Math setting).  This numeric > v2.A0
value will be an encoded RGB value, allowing you to set arbitrary RGB > v2.A0
colors directly with the Set Color commands.  If the RGB color is not > v2.A0
permissable, the closest match from the Color Map table will be       > v2.A0
located and used.  The number of bits of precision used in the        > v2.A0
encoded RGB value will be determined by the RIP_SET_COLOR_MODE        > v2.A0
command.                                                              > v2.A0
                                                                      > v2.A0

When Color Mapping Mode is in use, the color parameter may be shorter > v2.A0
than four digits.  This is for space savings, as it is allowable in   > v2.A0
the specification for the last numeric parameter in a parameter list  > v2.A0
to be "shorter" than the full length.                                 > v2.A0

NOTE:  The RIP_FILL_STYLE (predefined fill patterns) and this
       RIP_FILL_PATTERN (custom fill patterns) completely override
       each other's effects.





---------------------------------------------------------------------
RIP_NO_MORE
---------------------------------------------------------------------
         Function:  End of RIPscrip Scene
            Level:  0
          Command:  #
        Arguments:  <none>
           Format:  !|#
          Example:  !|#
  Uses Draw Color:  NO
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  NO
  Uses Font Sizes:  NO
    Uses Viewport:  NO                                                > v1.54

This command indicates that RIPscrip commands are complete.  This
allows the terminal program to activate Mouse Regions, or respond to
queued up Mouse Clicks without disturbing the natural flow of the
script transmission.

For noise-immunity, the Host should transmit three or more
RIP_NO_MORE command consecutively to make sure the message gets to
the terminal.  The terminal should also time-out if no data is
received for a while, and assume RIP_NO_MORE.

The actual duration of the "time-out" is entirely up to the           > v1.54
implementor of their terminal program.  A good recommended setting    > v1.54
would be at least an entire second or more after the receipt of the   > v1.54
last RIPscrip command.  Raw ASCII/ANSI text does not contribute to    > v1.54
the time-out in any way.  Only an actual RIPscrip command could       > v1.54
cause the time-out counter to be reset (thus starting the time-out    > v1.54
countdown all over again).  Timing-out is not a pre-requisite to      > v1.54
supporting RIPscrip.  It is a highly desirable feature to do this,    > v1.54
but it is not required.                                               > v1.54

This command also can re-activate user input previously disabled with > v2.A1
a RIP_HEADER command.  This is useful to prevent the user from        > v2.A1
clicking on buttons before the scene is completely drawn.  See the    > v2.A1
RIP_HEADER command for more details on this mode of operation.        > v2.A1

=====================================================================
==                          LEVEL-1 COMMANDS                       ==
=====================================================================

---------------------------------------------------------------------
RIP_MOUSE
---------------------------------------------------------------------
         Function:  Defines a rectangular hot mouse region
            Level:  1
          Command:  M
        Arguments:  num:2 x0:2 y0:2 x1:2 y1:2 clk:1 clr:1 res:5 text
           Format:  !|1M <num> <x0><y0><x1><y1> <clk><clr><res><text>
          Example:  !|1M00001122331100000host command^M
  Uses Draw Color:  NO
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  NO
  Uses Font Sizes:  NO
    Uses Viewport:  YES                                               > v1.54

This command ties together three things:

     A region on the screen
     A mouse-click event
     A string of text to be transmitted by the terminal.

This command defines a rectangular region on the screen that functions
as a "hot" mouse area.  If the user clicks the [left] mouse button
while pointing inside the region, then the terminal must transmit the
<text> string to the Host.  The (x0,y0) parameter MUST be the
upper-left corner, and (x1,y1) MUST be the lower-right corner of the
region.

The <num> parameter used to be used in the older RIPscrip v1.0        > v1.54
specification but is now obsolete.  For upwards compatibility, it     > v1.54
should be set to "00".                                                > v1.54

The <clk> parameter, if 1, indicates that the region should be
visibly inverted while the mouse button is down.  This offers visual
feedback. If <clk> is 0, the region will not be inverted while
clicked.

The <clr> parameter, if 1, will physically zoom the text window to
full screen size and clear the screen.  This is useful if the <text>
parameter instructs the host to enter an area of the System that
doesn't support RIPscrip graphics.

The <text> parameter is a Host command that gets sent when the field
is clicked.  You may use a caret (^) to represent control characters,
(e.g., ^M for carriage return, ^G, ^C, etc.).

When this command is stored in-memory, it is converted to global      > v1.54
screen coordinates (for internal storage only).  This makes it so     > v1.54
that if you have mouse regions defined in multiple different          > v1.54
viewports, that each field will be properly inverted at the right     > v1.54
location regardless of the currently defined viewport.                > v1.54

NOTE: All Mouse Fields are scanned in "last in, first out" order.     > v1.54
      This means that the last-most received Mouse Field will be      > v1.54
      the first one scanned for a mouse click.                        > v1.54

NOTE:  You are limited to a maximum of 128 Mouse Regions or           > v1.54
       Mouse Buttons (128 total).                                     > v1.54

       In addition, the 5-byte <res> parameter is RESERVED FOR
       FUTURE USE, and should be set to zeros (00000).

---------------------------------------------------------------------
RIP_KILL_MOUSE_FIELDS
---------------------------------------------------------------------
         Function:  Destroys all previously defined hot mouse regions
            Level:  1
          Command:  K
        Arguments:  <none>
           Format:  !|1K
          Example:  !|1K
  Uses Draw Color:  NO
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  NO
  Uses Font Sizes:  NO
    Uses Viewport:  NO                                                > v1.54

This command will "forget" all Mouse Regions.  Use it at the beginning
of each Scene, so that one scene's Mouse Regions don't get used in
another.





--------------------------------------------------------------------- > v2.A0
RIP_KILL_ENCLOSED_MOUSE_FIELDS                                        > v2.A0
--------------------------------------------------------------------- > v2.A0
         Function:  Destroys any Mouse Fields inside a region         > v2.A0
            Level:  1                                                 > v2.A0
          Command:  k                                                 > v2.A0
        Arguments:  x0:2 y0:2 x1:2 y1:2 flags:4                       > v2.A0
           Format:  !|1k <x0> <y0> <x1> <y1>                          > v2.A0
          Example:  !|1k00003G2H                                      > v2.A0
  Uses Draw Color:  NO                                                > v2.A0
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO                                                > v2.A0
  Uses Line Thick:  NO                                                > v2.A0
  Uses Fill Color:  YES (see below)                                   > v2.A0
Uses Fill Pattern:  YES (see below)                                   > v2.A0
  Uses Write Mode:  NO                                                > v2.A0
  Uses Font Sizes:  NO                                                > v2.A0
    Uses Viewport:  NO                                                > v2.A0
                                                                      > v2.A0
This command will destroy any Mouse Fields or Mouse Active Buttons    > v2.A0
that are contained inside the given rectangle or that intersect the   > v2.A0
rectangle.  The exact operation of this function is dependent on the  > v2.A0
setting of the <flags> parameter.  The <flags> parameter can combine  > v2.A0
any of the following flags to determine the exact mode of operation:  > v2.A0
                                                                      > v2.A0
  FLAGS   DESCRIPTION                                                 > v2.A0
  ==========================================================          > v2.A0
          Region Specific Flags                                       > v2.A0
          --------------------------------------------------          > v2.A0
      1   Kill only fields that intersect bounding rectangle          > v2.A0
      2   Kill fields entirely outside bounding rectangle             > v2.A0
                                                                      > v2.A0
           > If 1 or 2 are not present, then all fields               > v2.A0
           > INSIDE the rectangle are destroyed (based on             > v2.A0
           > the remaining flags).                                    > v2.A0
                                                                      > v2.A0
          What Types of Fields to Destroy                             > v2.A0
          --------------------------------------------------          > v2.A0
      4   Don't destroy simple Mouse Fields                           > v2.A0
      8   Don't destroy active Mouse Button fields                    > v2.A0
                                                                      > v2.A0
           > If 4 or 8 are not present, then all types                > v2.A0
           > of mouse fields are destroyed.                           > v2.A0
                                                                      > v2.A0
          What to do With the Affected Region(s)                      > v2.A0
          --------------------------------------------------          > v2.A0
      16  Clear the affected field(s) to black                        > v2.A0
      32  Fill the affected field(s) with current fill color          > v2.A0
          and fill pattern.                                           > v2.A0
      64  Perform the 16/32 operations on the whole bounding          > v2.A0
          rectangle (based on Region Specific Flags).                 > v2.A0
                                                                      > v2.A0
           > If 64 is omitted but 16 or 32 are used,                  > v2.A0
           > then the mouse fields affected are                       > v2.A0
           > cleared with the appropriate method.                     > v2.A0
           > If 64 is present as well, then instead                   > v2.A0
           > of clearing the individual mouse fields                  > v2.A0
           > with the given method, the entire region                 > v2.A0
           > specified by the Region Specific Flags                   > v2.A0
           > are affected (ie, the entire interior                    > v2.A0
           > of the bounding rectangle is cleared,                    > v2.A0
           > etc).  If 16, 32 and 64 are omitted, then                > v2.A0
           > the affected region/fields are left on                   > v2.A0
           > the screen visually, but their mouse                     > v2.A0
           > field definitions are destroyed internally.              > v2.A0

---------------------------------------------------------------------
RIP_BEGIN_TEXT
---------------------------------------------------------------------
         Function:  Define a rectangular text region
            Level:  1
          Command:  T
        Arguments:  x1:2, y1:2, x2:2, y2:2, res:2
           Format:  !|1T <x1> <y1> <x2> <y2> <res>
          Example:  !|1T00110011
  Uses Draw Color:  NO
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  NO
  Uses Font Sizes:  NO
    Uses Viewport:  YES                                               > v1.54

This command defines a rectangular portion of the graphics viewport
that is to display text, usually a long stream of text.  Following
this command should be a number of RIP_REGION_TEXT commands with the
text to be displayed.  The RIP_END_TEXT terminates this stream of
text, something like this:

RIP_BEGIN_TEXT
     RIP_REGION_TEXT
     RIP_REGION_TEXT
     RIP_REGION_TEXT
     :
     RIP_REGION_TEXT
RIP_END_TEXT

There must be at least one RIP_REGION_TEXT command in between the
header and the footer.  There may be as many as needed.

These commands ignore the current font "direction"; all text is
always displayed horizontally.

NOTE:  The "res" parameter is two bytes wide and is RESERVED for
       future use.





---------------------------------------------------------------------
RIP_REGION_TEXT
---------------------------------------------------------------------
         Function:  Display a line of text in rectangular text region
            Level:  1
          Command:  t
        Arguments:  justify:1 and text-string
           Format:  !|1t <justify> <text-string>
          Example:  !|1t1This is a text line to be justified
  Uses Draw Color:  YES
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  YES
  Uses Font Sizes:  YES
    Uses Viewport:  YES                                               > v1.54

A number of these commands may come sandwiched between the
RIP_BEGIN_TEXT and RIP_END_TEXT commands.  The <text-string> is
already word-wrapped in such a way that it will fit inside the
rectangular region based on the current font, font size, and drawing
color.

There are two possible settings for the <justify> parameter:

  Justify   Description
  ------------------------------------------------------------------
    0       Don't right/left justify.  Left-justify only
    1       Perform right/left margin justification of this line of
            text.

If a text line falls off the bottom of the region, it is discarded --
the rectangular Text Region does not scroll.

This command is intended to import some sort of text file document    > v1.54
directly into a RIPscrip scene and format it nicely to fit inside a   > v1.54
simple rectangular area.  If the <justify> parameter is set to a      > v1.54
value of "1" for a given RIP_REGION_TEXT line, then that line will be > v1.54
justified to both the left and right margins (the RIP_BEGIN_TEXT      > v1.54
boundaries).  This is so that the displayed text aligns on both sides > v1.54
with the invisible boundaries.  This "justification" is done by       > v1.54
splitting each RIP_REGION_TEXT line up into chunks of word-groups,    > v1.54
broken up at their "white-space" locations.  Each spacer is then      > v1.54
padded by however many pixels are necessary to keep each spacer       > v1.54
uniformly of approximately equal size.  Only enough spare pixels are  > v1.54
added to make sure that the right-edge of the text region alignts     > v1.54
with the right border of the boundary.  The result is a nicely        > v1.54
formatted text block.                                                 > v1.54





---------------------------------------------------------------------
RIP_END_TEXT
---------------------------------------------------------------------
         Function:  End a rectangular text region
            Level:  1
          Command:  E
        Arguments:  <none>
           Format:  !|1E
          Example:  !|1E
  Uses Draw Color:  NO
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  NO
  Uses Font Sizes:  NO
    Uses Viewport:  YES                                               > v1.54

This command indicates the end of a formatted text block.  Only one
of these "end" commands is necessary for each block.





---------------------------------------------------------------------
RIP_GET_IMAGE
---------------------------------------------------------------------
         Function:  Copy rectangular image to clipboard (as icon)
            Level:  1
          Command:  C
        Arguments:  x0:2, y0:2, x1:2, y1:2, clipboard_no:1            > v2.A0
           Format:  !|1C <x0> <y0> <x1> <y1> <clipboard_no>           > v2.A0
          Example:  !|1C001122330
  Uses Draw Color:  NO
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  NO
  Uses Font Sizes:  NO
    Uses Viewport:  YES                                               > v1.54

This command instructs the terminal program to copy the rectangular
region defined by (x0,y0) to (x1,y1) onto an internal Clipboard for
future use.  This combined with the Paste Clipboard command can
provide an extremely powerful and efficient mechanism to avoid
baud-rate bandwidth limitations.  The (x0,y0) parameter MUST specify
the upper-left corner of the region and the (x1,y1) parameter MUST
specify the lower-right corner.  If the indicated coordinates are in
anyway invalid, the command is ignored.  The Clipboard is completely
overwritten by this command (the previous contents are lost).

The <clipboard_no> parameter determines which clipboard slot to save  > v2.A0
the image to.  In previous versions of RIPscrip, this was a reserved  > v2.A0
parameter set to zero (0) indicating clipboard #0.  In v2.00 and      > v2.A0
higher, this value specifies which segment of the clipboard to store  > v2.A0
the image onto, allowing you to have multiple images on the clipboard > v2.A0
simultaneously.                                                       > v2.A0

The formal definition of the entire clipboard:  the clipboard is an   > v2.A1
offscreen bitmap (or collection of bitmaps) that is the size of the   > v2.A1
entire screen (no 64k memory limits).  That full-screen memory area   > v2.A1
can be subdivided into 36 separate sub-regions (multiple clipboard    > v2.A1
system).                                                              > v2.A1





---------------------------------------------------------------------
RIP_PUT_IMAGE
---------------------------------------------------------------------
         Function:  Pastes the clipboard contents onto the screen
            Level:  1
          Command:  P
        Arguments:  x:2, y:2, clipboard_no:1 mode:1, res:1            > v2.A0
           Format:  !|1P <x> <y> <clipboard_no> <mode> <res>          > v2.A0
          Example:  !|1P0011010
  Uses Draw Color:  NO
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  NO
  Uses Font Sizes:  NO
    Uses Viewport:  YES                                               > v1.54

This command takes the contents of the Clipboard (if any) and pastes
the image onto the screen starting at the upper-left corner of the
image of (x,y).  If the right edge of the image would go off-screen,
the paste command is ignored.  The Height and Width of the clipboard
image is recorded on the Clipboard, so this command doesn't need to
supply it.

The <clipboard_no> parameter determines which clipboard slot will be  > v2.A0
used for the source of the image.  With this option, you can support  > v2.A0
multiple clipboards simultaneously.  This provides for high-speed     > v2.A0
bitmap animations by allowing you to flip through multiple clipboard  > v2.A0
images quickly and easily.                                            > v2.A0

The <mode> parameter defines "how" the image will be pasted on the
screen:

  Mode   Description                                          Logical
  -------------------------------------------------------------------
    0    Paste the image on-screen normally                   (COPY)  > v2.A0
    1    Exclusive-OR  image with the one already on screen   (XOR)   > v2.A0
    2    Logically OR  image with the one already on screen   (OR)    > v2.A0
    3    Logically AND image with the one already on screen   (AND)   > v2.A0
    4    Paste the inverse of the image on the screen         (NOT)   > v2.A0

NOTE:  The 1-byte <res> parameter is RESERVED FOR FUTURE USE
       and should be set to zero.

The formal definition of the entire clipboard:  the clipboard is an   > v2.A1
offscreen bitmap (or collection of bitmaps) that is the size of the   > v2.A1
entire screen (no 64k memory limits).  That full-screen memory area   > v2.A1
can be subdivided into 36 separate sub-regions (multiple clipboard    > v2.A1
system).                                                              > v2.A1





---------------------------------------------------------------------
RIP_WRITE_ICON
---------------------------------------------------------------------
         Function:  Write contents of the clipboard (icon) to disk
            Level:  1
          Command:  W
        Arguments:  clipboard_no:1, filename                          > v2.A0
           Format:  !|1W <clipboard_no> <filename>                    > v2.A0
          Example:  !|1W0filename.icn
  Uses Draw Color:  NO
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  NO
  Uses Font Sizes:  NO
    Uses Viewport:  NO                                                > v1.54

This command takes the contents of the Clipboard and writes it to a
disk file.  This Icon file can be loaded later with a RIP_LOAD_ICON
command and stamped on the screen.

The command instructs the terminal to store an Icon on the terminal's
disk drive, or on some appropriate storage media.  Path or
sub-directory information is not allowed in the filename portion of
the command.  If the clipboard is nonexistent (i.e., at the beginning
of a scene), this command is ignored.  If an Icon by the same name
already exists on disk, it is overwritten.

The <clipboard_no> parameter allows you to specify which clipboard    > v2.A0
entry should be saved to an external icon file.  Since you can have   > v2.A0
multiple clipboard entries in v2.00 of the RIPscrip specification,    > v2.A0
this lets you choose which clipboard entry to store to disk.          > v2.A0





---------------------------------------------------------------------
RIP_LOAD_ICON
---------------------------------------------------------------------
         Function:  Loads and displays a disk-based icon to screen
            Level:  1
          Command:  I
        Arguments:  x:2, y:2, clipboard_no:1, mode:1, clipboard:1,    > v2.A0
                    res:2, filename                                   > v2.A0
           Format:  !|1I <x> <y> <clipboard_no> <mode> <clipboard>    > v2.A0
                    <res> <filename>                                  > v2.A0
          Example:  !|1I0011010100button.icn
  Uses Draw Color:  NO
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  NO
  Uses Font Sizes:  NO
    Uses Viewport:  YES                                               > v1.54

This command instructs the terminal to read an Icon from disk and
display it at the given upper-left (x,y) location.  If the width or
height of the Icon would make it go off the right or left edge of the
screen, the Icon will not be displayed.  The <mode> parameter defines
the modes in which the Icon will be displayed on the screen.  The
modes are identical to the RIP_PUT_IMAGE command, and are as follows:

The .BMP file extension does not need to be included as part of the   > v2.A1
filename.  If omitted, it will automatically be appended to the
filename.  If an extension is provided, it will be used verbatim.

  Mode   Description                                         Logical
  ------------------------------------------------------------------
    0    Paste the image on-screen normally                   (COPY)  > v2.A0
    1    Exclusive-OR  image with the one already on screen   (XOR)   > v2.A0
    2    Logically OR  image with the one already on screen   (OR)    > v2.A0
    3    Logically AND image with the one already on screen   (AND)   > v2.A0
    4    Paste the inverse of the image on the screen         (NOT)   > v2.A0

The <clipboard> parameter can be one of three values:

  Value  Description                                                  > v2.A0
  --------------------------------------------------------------      > v2.A0
    0    Load the image onto the screen verbatim                      > v2.A0
    1    Load the image onto the screen and put on the clipboard      > v2.A0
                                                                      > v2.A0
If the Icon is to be loaded onto the Clipboard, then the              > v2.A0
<clipboard_no> parameter is used to determine which clipboard slot to > v2.A0
use for the image's contents.                                         > v2.A0

The <filename> parameter must not contain any sub-directory or path
information and must specify a valid Icon file name.  If the Icon
cannot be located or an error occurs on the disk, then a box should
be displayed on screen indicating that the given Icon File could not
be loaded.  This visual prompt indicates that something is amiss to
the end-user.

NOTE:  The 2-byte <res> parameter is RESERVED FOR THE FUTURE
       and unlike many other previously mentioned reserved
       parameters, should be set to "10".

--------------------------------------------------------------------- > v2.A1
RIP_LOAD_BITMAP                                                       > v2.A1
--------------------------------------------------------------------- > v2.A1
         Function:  Loads and displays a disk-based bitmap to screen  > v2.A1
            Level:  1                                                 > v2.A1
          Command:  b                                                 > v2.A1
        Arguments:  x0:2, y0:2, x1:2, y1:2, clipboard_no:1, mode:1,   > v2.A1
                    palette:1 dither:1, clipboard:1, res:2, filename  > v2.A1
           Format:  !|1b <x0> <y0> <x1> <y1> <clipboard_no> <mode>    > v2.A1
                    <clipboard> <palette> <dither> <res> <filename>   > v2.A1
          Example:  !|1b001122330100100button.icn                     > v2.A1
  Uses Draw Color:  NO                                                > v2.A1
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO                                                > v2.A1
  Uses Line Thick:  NO                                                > v2.A1
  Uses Fill Color:  NO                                                > v2.A1
Uses Fill Pattern:  NO                                                > v2.A1
  Uses Write Mode:  NO                                                > v2.A1
  Uses Font Sizes:  NO                                                > v2.A1
    Uses Viewport:  YES                                               > v2.A1
                                                                      > v2.A1
This command is nearly identical in nature to the RIP_LOAD_ICON       > v2.A1
command but it is more flexible in that it supports scaling of the    > v2.A1
bitmap to the destination screen and it supports dithering methods.   > v2.A1
It can be made to exactly match the RIP_LOAD_ICON command.            > v2.A1
                                                                      > v2.A1
This command instructs the terminal to read an Icon from disk and     > v2.A1
display it at the given upper-left (x0,y0) location.  If the (x1,y1)  > v2.A1
values are non-zero, then it specifies the lower-right corner on the  > v2.A1
screen for the bitmaps display region.  If the bitmap differs in      > v2.A1
size than the on-screen rectangle, than it is scaled (stretched) to   > v2.A1
fit into the proper region.  If the values of X0 and Y0 are zero,     > v2.A1
then the bitmap is shown verbatim in whatever resolution of the       > v2.A1
disk based file (this is more like the RIP_LOAD_ICON command above).  > v2.A1
                                                                      > v2.A1
If the width or height of the Icon would make it go off the right or  > v2.A1
bottom edge of the viewport, the bitmap will be clipped.  The <mode>  > v2.A1
parameter defines the modes in which the Icon will be displayed on    > v2.A1
the screen.  The modes are identical to the RIP_PUT_IMAGE command,    > v2.A1
and are as follows:                                                   > v2.A1
                                                                      > v2.A1
The .BMP file extension does not need to be included as part of the   > v2.A1
filename.  If omitted, it will automatically be appended to the       > v2.A1
filename.  If an extension is provided, it will be used verbatim.     > v2.A1
                                                                      > v2.A1
  Mode   Description                                         Logical  > v2.A1
  ------------------------------------------------------------------  > v2.A1
    0    Paste the image on-screen normally                   (COPY)  > v2.A1
    1    Exclusive-OR  image with the one already on screen   (XOR)   > v2.A1
    2    Logically OR  image with the one already on screen   (OR)    > v2.A1
    3    Logically AND image with the one already on screen   (AND)   > v2.A1
    4    Paste the inverse of the image on the screen         (NOT)   > v2.A1
                                                                      > v2.A1
The <clipboard> parameter can be one of three values:                 > v2.A1
                                                                      > v2.A1
  Value  Description                                                  > v2.A1
  --------------------------------------------------------------      > v2.A1
    0    Load the image onto the screen verbatim                      > v2.A1
    1    Load the image onto the screen and put on the clipboard      > v2.A1

If the Icon is to be loaded onto the Clipboard, then the              > v2.A1
<clipboard_no> parameter is used to determine which clipboard slot to > v2.A1
use for the image's contents.                                         > v2.A1
                                                                      > v2.A1
The <palette> parameter determines how to handle the internal color   > v2.A1
palette in the bitmap.  256 color and lower bitmaps have color        > v2.A1
palette information stored in the bitmap.  24 bit bitmaps contain     > v2.A1
no internal color palette (see BMP file format at the end of this     > v2.A1
document).  Because the bitmap was originally created with some       > v2.A1
color scheme, RIPscrip needs to know how it should handle the         > v2.A1
internal color palette.  The values for this parameter are as         > v2.A1
follows:                                                              > v2.A1
                                                                      > v2.A1
  Value  Description                                                  > v2.A1
  --------------------------------------------------------------      > v2.A1
    0    Use the current screen's color palette.  Typically this      > v2.A1
         will be the default color palette for use with RIPscrip      > v2.A1
         but it might be different.  This means that any pixel        > v2.A1
         of the bitmap that is drawn to the screen is shown in        > v2.A1
         whatever actual color is the absolute closest to the         > v2.A1
         color palette number corresponding to that pixel in          > v2.A1
         the bitmap.                                                  > v2.A1
    1    Commit the color palette inside the bitmap to the            > v2.A1
         display device.  This means that the color palette in        > v2.A1
         the bitmap is copied into the video device's color           > v2.A1
         palette (and into RIPscrip's).  This means that if any       > v2.A1
         graphics are already on the screen when this happens,        > v2.A1
         they might change in color as soon as the bitmap is          > v2.A1
         loaded (this is due to the fact that the color palette       > v2.A1
         is changed).  If the number of colors in the bitmap          > v2.A1
         is higher than the number of colors in the active            > v2.A1
         display device, then the actual color palette in use         > v2.A1
         is used for the bitmap instead of the internal bitmap        > v2.A1
         palette.  If the number of colors in the bitmap is           > v2.A1
         equal or less than the number of colors for the active       > v2.A1
         video mode then the image will be displayed exactly as       > v2.A1
         it was intended.  If this is the case, then no               > v2.A1
         dithering is necessary on the image so the <dither>          > v2.A1
         parameter is ignored.                                        > v2.A1
                                                                      > v2.A1
The <dither> parameter determines what kind of dithering is performed > v2.A1
on the bitmap when it is drawn to the screen.  Dithering is used to   > v2.A1
make the bitmap appear as close to its original appearance as         > v2.A1
possible in different color schemes.  RIPterm implements a Floyd-     > v2.A1
Steinberg dithering process for its bitmap dithering.  The valid      > v2.A1
values for this parameter and their meanings are as follows:          > v2.A1
                                                                      > v2.A1
  Value  Description                                                  > v2.A1
  --------------------------------------------------------------      > v2.A1
    0    Perform no dithering whatsoever.  If the number of           > v2.A1
         colors in the bitmap is higher than the number of            > v2.A1
         colors in the display device then this will yield a          > v2.A1
         lower quality image.  But if there are more colors in        > v2.A1
         the display device than the bitmap then the quality of       > v2.A1
         the image will be close to the actual bitmap (or exact).     > v2.A1

    1    Auto-Dithering mode.  This is a more intelligent way of      > v2.A1
         determining if dithering should be performed or not.         > v2.A1
         If there are more colors in the bitmap than in the           > v2.A1
         video device or if the bitmap's color palette is not         > v2.A1
         used to set the video device, then dithering is used to      > v2.A1
         get the image as close to the original color scheme as       > v2.A1
         possible.  If the bitmap's palette is committed to the       > v2.A1
         video device then no dithering is necessary because the      > v2.A1
         color palette in use has all (or more) of the necessary      > v2.A1
         colors to display the image.  24 bit images will always      > v2.A1
         enable dithering if this mode is used unless the terminal    > v2.A1
         is running in 24-bit mode.  Dithering slows down image       > v2.A1
         drawing so it should only be used for images that really     > v2.A1
         need it.                                                     > v2.A1
                                                                      > v2.A1
If the bitmap is placed on the clipboard, then it is done in a        > v2.A1
specific order.  The image is shown on the screen then the            > v2.A1
resulting image (after color palette translation and dithering        > v2.A1
are performed) is placed on the clipboard.  This is done so that      > v2.A1
the image on the clipboard will already have its processing done      > v2.A1
on it so that subsequent clipboard operations will not require        > v2.A1
any color translation or dithering (a speed consideration).           > v2.A1
                                                                      > v2.A1
The <filename> parameter must not contain any sub-directory or path   > v2.A1
information and must specify a valid Icon file name.  If the Icon     > v2.A1
cannot be located or an error occurs on the disk, then a box should   > v2.A1
be displayed on screen indicating that the given Icon File could not  > v2.A1
be loaded.  This visual prompt indicates that something is amiss to   > v2.A1
the end-user.  The size of the box will be as big as the destination  > v2.A1
icon image on screen.  If the X1 and Y1 are zero, then some suitable  > v2.A1
box should be drawn.                                                  > v2.A1
                                                                      > v2.A1
NOTE:  The 2-byte <res> parameter is RESERVED FOR THE FUTURE          > v2.A1
       and should be set to "00".                                     > v2.A1





--------------------------------------------------------------------- > v2.A0
RIP_IMAGE                                                             > v2.A0
--------------------------------------------------------------------- > v2.A0
         Function:  Display a scalable photo type image               > v2.A0
            Level:  1                                                 > v2.A1
          Command:  p                                                 > v2.A1
        Arguments:  res:4 filename                                    > v2.A0
           Format:  !|1p <res> <filename>                             > v2.A1
          Example:  !|1p0000filename.jpg                              > v2.A1
  Uses Draw Color:  NO                                                > v2.A0
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO                                                > v2.A0
  Uses Line Thick:  NO                                                > v2.A0
  Uses Fill Color:  NO                                                > v2.A0
Uses Fill Pattern:  NO                                                > v2.A0
  Uses Write Mode:  NO                                                > v2.A0
  Uses Font Sizes:  NO                                                > v2.A0
    Uses Viewport:  YES                                               > v2.A0
                                                                      > v2.A0
This command will physically take a JPEG image file that is           > v2.A1
located on the remote terminal's hard disk (like Icon files) and      > v2.A0
display it in the image area set by a RIP_IMAGE_STYLE command.        > v2.A0
See the RIP_IMAGE_STYLE command for more details on the options       > v2.A0
available to set for image viewing and manipulation.                  > v2.A0






--------------------------------------------------------------------- > v2.A0
RIP_IMAGE_STYLE                                                       > v2.A0
--------------------------------------------------------------------- > v2.A0
         Function:  Alter subsequent displayed image settings         > v2.A0
            Level:  1                                                 > v2.A1
          Command:  i                                                 > v2.A0
        Arguments:  x0:2 y0:2 x1:2 y1:2 flags:4 res:12                > v2.A1
           Format:  !|1i <x0> <y0> <x1> <y1> <flags> <res>            > v2.A1
          Example:  !|1i00008G5B0002000000000000                      > v2.A1
  Uses Draw Color:  NO                                                > v2.A0
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO                                                > v2.A0
  Uses Line Thick:  NO                                                > v2.A0
  Uses Fill Color:  NO                                                > v2.A0
Uses Fill Pattern:  NO                                                > v2.A0
  Uses Write Mode:  NO                                                > v2.A0
  Uses Font Sizes:  NO                                                > v2.A0
    Uses Viewport:  YES                                               > v2.A0
                                                                      > v2.A0
This command alters the settings for subsequently received (or        > v2.A0
displayed) image files.  RIPscrip supports the display of JPEG (Joint > v2.A0
Photographic Experts Group) files.  These files can be transmitted to > v2.A1
the remote terminal and viewed. The <x0>, <y0>, <x1> and <y1>         > v2.A1
parameters determine the size of the image area in the current        > v2.A1
viewport.                                                             > v2.A1

If the <x0>, <y0>, <x1> and <y1> parameters are all set to zero (0),  > v2.A0
then Image Viewing is disabled.  Any explicitly viewed images, or any > v2.A0
images received with RIP_ENTER_BLOCK_MODE will be ignored (however    > v2.A0
they will be deleted if flag 4 or 8 are active - see below).          > v2.A0
                                                                      > v2.A0
If the image view area is larger than the current viewport size, then > v2.A0
the image area size will be adjusted according to the viewport's      > v2.A0
current size (making them both identical in size and orientation).    > v2.A0

The image will be scaled to fit inside the specified display region.  > v2.A1
If any of these coordinates extend beyond the dimensions of the       > v2.A1
viewport, they will be adjusted to fit.                               > v2.A1

There is a <flags> parameter which alters some of the aspects of the  > v2.A0
image being displayed.  These flags can be OR'd together to create a  > v2.A0
combination of various flag values.  The possible flags are:          > v2.A0
                                                                      > v2.A0
  Value  Description                                                  > v2.A0
  ----------------------------------------------------------------    > v2.A0
      1  Maintain image aspect ratio - This will keep the image       > v2.A0
         maintained in size no matter what the size of the display    > v2.A0
         region is.  If the region isn't perfectly proportioned       > v2.A0
         in relation to the actual bitmap, then areas of the          > v2.A0
         display region above and below the image will be blacked     > v2.A0
         out (a margin), or possibly left and right depending on      > v2.A1
         proportions of the bitmap.  This will yield a visually       > v2.A1
         accurate representation of the image.                        > v2.A1

      2  Delete image definition when complete.  This is only         > v2.A1
         useful for images received via RIP_ENTER_BLOCK_MODE or via   > v2.A1
         a UU-encoded RIPscrip data block for text-only transfer.     > v2.A1
         When the image is rendered on the screen, it's definition    > v2.A1
         and/or local disk file is deleted automatically upon         > v2.A1
         completion of the drawing process.                           > v2.A1






---------------------------------------------------------------------
RIP_BUTTON_STYLE
---------------------------------------------------------------------
         Function:  Button style definition
            Level:  1
          Command:  B
        Arguments:  wid:2 hgt:2 orient:2 flags:4 size:2
                    dfore:2 dback:2 bright:2 dark:2 surface:2
                    grp_no:2 flags2:2 uline_col:2 corner_col:2
                    clipboard_no:1 slot:1 res:4                       > v2.A1
           Format:  !|1B <wid> <hgt> <orient> <flags>
                    <bevsize> <dfore> <dback> <bright> <dark>
                    <surface> <grp_no> <flags2> <uline_col>
                    <corner_col> <clipboard_no> <slot> <res>          > v2.A1
          Example:  !|1B0A0A010274030F080F080700010E07010A00
  Uses Draw Color:  NO
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  NO
  Uses Font Sizes:  NO
    Uses Viewport:  NO                                                > v1.54

This RIPscrip command is probably one of the most complex in the
entire protocol.  It defines how subsequent RIP_BUTTON commands will
be interpreted.  The purpose of this command is to define what a
Button is and how they operate.  Buttons can have many different
configurations, flags, and styles.  With the diversity of modes that
the Button can take on, complexity is a necessary evil.

There are 36 separate button style slots that can be defined          > v2.A1
simultaneously.  This command allows you to alter one of the button   > v2.A1
style slots as specified by the <slot> parameter.  These style slots  > v2.A1
can be used by RIP_BUTTON commands to define buttons of particular    > v2.A1
types.  Button style slots can be used to avoid retransmitting button > v2.A1
styles over and over again.                                           > v2.A1

This command does not actually do anything visibly on the screen.
Simply put, this creates an internal definition for the Button mode
which will be used with RIP_BUTTON commands after the definition is
created.

Every Button can have an optional text label.  It can appear in
several different locations compared to the Button itself.  This is
specified in the <orient> parameter.  The actual text of the label is
not specified with this command, it is specified when you actually
create a Button (see RIP_BUTTON below).  The value that <orient> can
be is as follows:

        Value   Description of Orientation
        -------------------------------------------------
         00     Display label above button
         01     Display label to the left of button
         02     Display label in the center of the button
         03     Display label to the right of button
         04     Display label beneath the button


There are three basic "types" of Buttons.  There are Icon buttons,    > v1.54
Clipboard buttons and Plain buttons.  Each of these differ in the     > v1.54
way that they create the button's image.  A description of each type  > v1.54
is as follows:                                                        > v1.54
                                                                      > v1.54
     ICON BUTTON (flag 128) - An Icon Button means that the           > v1.54
     actual image of the button will be created by loading a          > v1.54
     bitmap icon image from the disk and load it at the given         > v1.54
     locatino.  Any special effects (see below) can be applied        > v1.54
     to the Icon to further enhance the image.  The filename          > v1.54
     for the Icon is supplied with the RIP_BUTTON command, as         > v1.54
     is the Icon's upper left X/Y coordinate.  Icon Buttons           > v1.54
     are always stamped in COPY mode.                                 > v1.54
                                                                      > v1.54
     CLIPBOARD BUTTON (flag 1) - A clipboard button uses the          > v1.54
     current contents of the clipboard for the base image of          > v1.54
     the button.  If no clipboard is defined, then the button         > v1.54
     is ignored.  The clipboard is pasted in COPY mode at             > v1.54
     the X/Y location specified in the RIP_BUTTON command             > v1.54
     that defines the actual button instance.  Any special            > v1.54
     effects can be applied to this image to further enhance          > v1.54
     the overall button's image.                                      > v1.54
                                                                      > v1.54
     PLAIN BUTTON (flag 256) - A plain button is exactly that,        > v1.54
     plain.  No special graphics are used to create the button.       > v1.54
     The entire button region is simply filled-in with a solid        > v1.54
     colored rectangle using the <surface> color.  Any                > v1.54
     special effects can be further applied to enhance the            > v1.54
     button's appearance.                                             > v1.54

The <hgt> and <wid> parameters represent the fixed height and width
of the Button (applies only to Plain Buttons).  If both values are
greater than zero, then this will represent the actual size of the
Button (its dimensions are not specified by the RIP_BUTTON command).
If both of these are set to zero, then the actual RIP_BUTTON command
will specify the size of the particular Button (dynamic sizing).

The <bevsize> parameter is only used if the BEVEL FLAG (flag 512) is  > v1.54
specified.  When active, this parameter will determine how many
pixels thick the bevel should be.  This may be any value greater or
equal to zero.

There are a large number of flag values that can be combined to
achieve a great many effects.  There are two flag parameters for the
RIP_BUTTON_STYLE command, <flags> and <flags2>.  They are detailed in
the two tables that follow in this Section.  You may combine any of
the flags in the first table together simply by adding the "Value" of
each one together and representing that number as a MegaNum.

The <dfore> and <dback> parameters are used with the text label.  The
<dfore> parameter is the foreground color for the text.  It is always
used to determine the color of the text label.  The <dback> color is
the color of the dropshadow (if any).  This parameter is only used
when you have specified the "Dropshadow" flag in the <flags>
parameter (see below).

NOTE: There are seven (7) color parameters in this command.           > v2.A0
      These parameters are ALWAYS used in Color Map mode.             > v2.A0
      Direct RGB Color Mode cannot be used for these                  > v2.A0
      parameters.  With Color Map mode, you have up to 256            > v2.A0
      separate color combinations possible for each color,            > v2.A0
      providing you with a great deal of flexibility.  The            > v2.A0
      color parameters always use the Base Math set by the            > v2.A0
      global Base Math setting.                                       > v2.A0

The <bright>, <dark> and <surface> parameters are used with Plain
Buttons and with the Special Effects styles (see <flags> below).
These colors represent the highlighted color, the shadowed color, and
the regular surface color that is used in Special Effects.  Typical
color combinations for these colors might be White, Dark-Gray and
Light-Gray respectively for a "chiseled steel" appearance.  Each of
these values can contain a two-digit value representing any valid
color code that may be used in the RIP_COLOR command.

In addition to the special effects colors, are two additional colors
that can be used, <uline_color> which is used for the color of the
underline (in the text label), and <corner_color> which is used to
display the colors of corners for things like the Bevel, Recess, etc.

The <grp_no> parameter determines which Button Group subsequent
RIP_BUTTON commands will be associated with.  Button Groups are used
to maintain groups of Buttons for things like Radio Buttons and/or
Checkbox Buttons.  See the section on the BUTTON COMMAND for more
information on these modes, and what Button Groups can offer.  This
value can range anywhere from 0-Z (i.e., 0-35).  You should not mix
Checkbox and Radio buttons in the same group. -- unpredictable things
may happen if you do.

Some <flags> are mutually exclusive.  For example, you can only have
one of the "Plain", "Icon", or "Clipboard" flags chosen at once.  To
better assist you in determining which values can be combined with
each other, the right-most five columns in the next two tables
explain if the specific flag can be used under a specific condition.
For example, you cannot choose the "Hot Icon" flag if you are dealing
with a Clipboard Button.  Another example is that you cannot
underline the hotkey character in the label if it is not a Mouse
Button.

The following table contains the possible flag values for the <flags>
parameter.  Each of these values may be combined to achieve a
"composite" group of flags.  See the preceding paragraphs for a more
detailed explanation of this method.

Value Description of Flags Field #1   Icon Clip  Plain Mouse No-Mouse
---------------------------------------------------------------------
    1 Button is a "Clipboard Button"   N     Y     N     Y     Y
    2 Button is "Invertable"           Y     Y     Y     Y     N
    4 Reset screen after button click  Y     Y     Y     Y     N
    8 Display Chisel special effect    Y     Y     Y     Y     Y
   16 Display Recessed special effect  Y     Y     Y     Y     Y
   32 Dropshadow the label (if any)    Y     Y     Y     Y     Y
   64 Auto-stamp image onto Clipboard  Y     Y     Y     Y     Y
  128 Button is an "Icon Button"       Y     N     N     Y     Y
  256 Button is a "Plain Button"       N     N     Y     Y     Y
  512 Display Bevel special effect     Y     Y     Y     Y     Y
 1024 Button is a Mouse Button         Y     Y     Y     Y     N
 2048 Underline hot-key in label       Y     Y     Y     Y     N
 4096 Make Icon Button use Hot Icons   Y     N     N     Y     N
 8192 Adj. vertical centering of label Y     Y     Y     Y     Y
16384 Button belongs to a Radio Group  Y     Y     Y     Y     N
32768 Display Sunken special effect    Y     Y     Y     Y     Y


The Icon Button, Clipboard button and Plain flags have already been   > v1.54
discussed.  Following, will be more discussion of the various flags   > v1.54
used in the preceding table:                                          > v1.54
                                                                      > v1.54
     BUTTON IS INVERTABLE (flag 2) - This means that the button       > v1.54
     will be inverted when clicked.  This flag is only useful         > v1.54
     when combined with the "Button is a Mouse Button - flag          > v1.54
     1024) flag.  Even if the button has special effects, those       > v1.54
     will be inverted as well as they are considered part of          > v1.54
     the button - all except for the Recessed effect.  The            > v1.54
     recessed effect is NEVER considered part of the actual           > v1.54
     button image, and will never be part of the mouse field,         > v1.54
     button's image or anything - it is just extra graphics.          > v1.54
                                                                      > v1.54
     RESET SCREEN AFTER BUTTON CLICK (flag 4) - This flag is          > v1.54
     used when the button is considered a Mouse Button (flag          > v1.54
     1024).  What this means is that when the user clicks on          > v1.54
     the button, the screen will be reset exactly the same            > v1.54
     as a RIP_RESET_WINDOWS command will do.  The reset is            > v1.54
     performed before the host command is processed (if any).         > v1.54
                                                                      > v1.54
     DISPLAY CHISEL SPECIAL EFFECT (flag 8) - This displays           > v1.54
     a special effect on-top of the button image that gives           > v1.54
     the visual impression of an indented gutter just to the          > v1.54
     inside of the button's border.  The amount of indentation        > v1.54
     varies depending on the size of the button.  See below           > v1.54
     for a table of indentation values for the Chisel effect.         > v1.54
                                                                      > v1.54
     DISPLAY RECESSED SPECIAL EFFECT (flag 16) - This places          > v1.54
     a recessed one-pixel bevel around the exterior of the            > v1.54
     button.  It is never considered part of the button's             > v1.54
     image.  Its purpose is to give the button a more 3D look         > v1.54
     by making it appear that the button is "poking through"          > v1.54
     a hole in a dialog box.  This effect is accomplished by          > v1.54
     placing a black outline (one pixel wide) around the              > v1.54
     exterior of the button's image (including bevel, etc),           > v1.54
     then placing a one-pixel wide inverted bevel around the          > v1.54
     black outline.                                                   > v1.54
                                                                      > v1.54
     DROPSHADOW THE LABEL IF ANY (flag 32) - This flag will           > v1.54
     instruct RIPscrip to place a dropshadowed version of the         > v1.54
     text label one pixel to the right and one pixel lower            > v1.54
     than the original label.  This is accomplished by drawing        > v1.54
     the label first in the <dback> color, then drawing the           > v1.54
     label offset up-left in the <dfore>.                             > v1.54
                                                                      > v1.54
     AUTO-STAMP IMAGE ONTO CLIPBOARD (flag 64) - This option          > v1.54
     is also known as "Auto-Clip".  What this means is right          > v1.54
     after the first button's image is rendered (including any        > v1.54
     special effects), it is automatically copied onto the            > v1.54
     clipboard.  The Recessed special effect is not considered        > v1.54
     part of the button image for this flag and is not made           > v1.54
     part of the clipboard image.  After the image is copied          > v1.54
     onto the clipboard, the label is drawn (this is so that          > v1.54
     the label is not placed onto the clipboard), then a              > v1.54
     number of flags in the current Button Style definition           > v1.54
     are altered.  Specifically, the Icon and Plain flags are         > v1.54
     disabled, and Clipboard button enabled (thus making any          > v1.54
     subsequent buttons use the resultant Clipboard button            > v1.54
     image for their button's representation).  In addition,          > v1.54
     the chisel, bevel, auto-clip and sunken flags are                > v1.54
     disabled.  The final result is a Clipboard button with           > v1.54
     no special effects other than the Recessed effect (if            > v1.54
     any).  This is most often used with Icon Buttons where           > v1.54

     every subsequent button uses the same Icon over and over         > v1.54
     again - the net result of this is less "disk thrashing"          > v1.54
     whenever a button is created; in addition, buttons will          > v1.54
     draw faster too.  If this option is used, then the               > v2.A0
     parameter <clipboard_no> is used to determine which              > v2.A0
     clipboard slot to use for the stored image.                      > v2.A0
                                                                      > v1.54
     BUTTON IS AN ICON BUTTON (flag 128) - See previous               > v1.54
     discussions on button types above.                               > v1.54
                                                                      > v1.54
     BUTTON IS A PLAIN BUTTON (flag 256) - See previous               > v1.54
     discussions on button types above.                               > v1.54
                                                                      > v1.54
     DISPLAY BEVEL SPECIAL EFFECT (flag 512) - When this flag         > v1.54
     is active, a bevel will be drawn <size> pixels thick on          > v1.54
     the outside of the base image of the button.  This makes         > v1.54
     the button that many pixels wider and taller in each             > v1.54
     direction.  See the RIP_BUTTON for a more detailed               > v1.54
     description of the affects of the button's final size.           > v1.54
                                                                      > v1.54
     BUTTON IS A MOUSE BUTTON (flag 1024) - When this flag is         > v1.54
     enabled, the button becomes a clickable mouse region.            > v1.54
     When this option is in use, the Invert flag and several          > v1.54
     others are available (see the preceding chart).  When            > v1.54
     a button is a non-mouse button, then it is only used to          > v1.54
     draw a dialog box or an elaborate "static graphic" image         > v1.54
     of something that "looks" like a button.                         > v1.54
                                                                      > v1.54
     UNDERLINE HOT-KEYS IN LABEL (flag 2048) - When this              > v1.54
     flag is active, the first occurence of the hot-key               > v1.54
     character in the button's label will be underlined using         > v1.54
     the <uline_col> color.  Special care must be taken when          > v1.54
     underlining the character, taking into consideration if          > v1.54
     the character has a segment that goes below the "baseline"       > v1.54
     of the font.  Consult the following section to determine         > v1.54
     what ASCII characters have these "descenders".  Characters       > v1.54
     with descenders have the underline drawn slightly lower          > v1.54
     than for characters without them.                                > v1.54
                                                                      > v1.54
     MAKE ICON BUTTON USE HOT ICONS (flag 4096) - A Hot Icon          > v1.54
     is a button that has an alternative image when the button        > v1.54
     is "depressed".  Normally, when a button is an Icon              > v1.54
     button, some form of Icon File is used to create the image       > v1.54
     of the button (eg, EMAIL.BMP).  When the Hot Icon flag is        > v2.A1
     in use, whenever that button is depressed, rather than           > v1.54
     using the normal Icon File for the button's image, a             > v1.54
     different Icon File is used for the button's image.  The         > v1.54
     filename would be the same filename as the original Icon,        > v1.54
     but with an extension of .HIC instead of .BMP.  When Hot         > v2.A1
     Icon is in use, the alternative Icon is stamped in COPY          > v1.54
     mode.  If the file does not exist, then the original             > v1.54
     Icon's image is used, but pasted in NOT mode for the             > v1.54
     duration of the depression.                                      > v1.54
                                                                      > v1.54
     ADJ. VERTICAL CENTERING OF LABEL (flag 8192) - Some Labels       > v1.54
     may appear non-centered vertically when drawn using some         > v1.54
     fonts that are rather large.  With this in mind, you have        > v1.54
     the option to adjust the vertical centering.  What this          > v1.54
     does is take into consideration the height of any                > v1.54
     descenders of the label and calculate those into the             > v1.54
     overall height of the label before centering.  If this           > v1.54
     flag is not used, then the descenders are not taken into         > v1.54
     consideration when the vertical centering is calculated.         > v1.54
     See the Font Metric tables below for more detailed               > v1.54
     information on font sizes and their associated metrics.          > v1.54
     This command has no effect if the Label orientation is           > v1.54
     LEFT or RIGHT of the button.  It only applies to an              > v1.54
     orientation of TOP, BOTTOM or CENTER.                            > v1.54

     BUTTON BELONGS TO A RADIO GROUP (flag 16384) - When this         > v1.54
     flag is used, then any buttons defined in this button            > v1.54
     <group_no> are considered to be radio buttons where only         > v1.54
     one of the buttons can be clicked (selected) at any              > v1.54
     particular time.  If a button is not a radio button or           > v1.54
     a checkbox button, then the "selected" flag of the               > v1.54
     RIP_BUTTON command is ignored.  When a Radio Button is           > v1.54
     clicked, any other radio button in that button group that        > v1.54
     is selected is automatically de-selected and the current         > v1.54
     one selected.  Any host command is processed at the time         > v1.54
     of the button click.  If a Radio Button is drawn initally        > v1.54
     as selected, then that host command is processed at the          > v1.54
     time of its initial drawing.  See the section near the           > v1.54
     end of this document discussing TEMPLATES for a more             > v1.54
     complete description of Radio Buttons and how they               > v1.54
     interact with their Button Group and with each other.            > v1.54
                                                                      > v1.54
     DISPLAY SUNKEN SPECIAL EFFECT (flag 32768) - When this           > v1.54
     option is enabled, a one-pixel inverted bevel is drawn           > v1.54
     exactly one pixel to the inside of the base image of the         > v1.54
     button.  This and the chisel effect are the only two             > v1.54
     special effects which physically "overwrite" portions of         > v1.54
     the base button image.                                           > v1.54

This array defines which characters have descenders (portions of
their font that go below the baseline).  This information is used in
the vertical centering of button text labels.

char low_char[256] =
{
    0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
    0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
    0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
    0,0,0,0,0,0,0,1,0,0,1,0,0,0,0,0,1,1,0,0,0,0,0,0,0,1,0,0,0,0,0,0,
    1,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,1,
    0,0,0,0,0,0,0,0,0,0,0,1,1,0,0,0,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
    1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
    0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0
};

struct METRIC
{
    unsigned char top;    // Scan lines from TOP OF CELL to char top
    unsigned char bow;    // Scan lines from TOC to crest of char
    unsigned char base;   // Scan lines from TOC to baseline
    unsigned char drop;   // Scan lines from TOC to lowermost pixel
};


The METRIC structure can be described visually as follows:

                      0 --+----------+----------+
                          |          |          |
                     TOP__|__________|__________|
                          | #        |          |
                          | #        |          |
                          | #        |          |
                     BOW__|_#________|___   _ __|
                          | # ###    |   ### #  |
                          | ##   #   |  #   ##  |
                          | #     #  | #     #  |
                          | #     #  | #     #  |
                          | #     #  | #     #  |
                          | #     #  |  #   ##  |
                    BASE__|_#_____#__|___###_#__|
                          |          |       #  |
                          |          |       #  |
                          |          |       #  |
                          |          |  #   #   |
                    DROP__|__________|___###____|
                          |          |          |
                    END --+----------+----------+

Notice that the topmost scan line of a font cell is not necessarily
the top of the character.  The top field of the structure contains
the vertical offset from the top of the cell for all fonts in that
set.


    Default Font (Font 0)               Triplex Font (Font 1)

Size  Top    Bow   Base   Drop     Size   Top   Bow     Base   Drop
------------------------------     --------------------------------
  1    0      2      6      7        1     6     10      18     22
  2    0      4     13     15        2     6     11      20     24
  3    0      6     20     23        3     8     13      23     28
  4    0      8     27     31        4     10    17      31     38
  5    0     10     34     39        5     13    23      41     50
  6    0     12     41     47        6     16    28      51     62
  7    0     14     48     55        7     20    34      62     76
  8    0     16     55     63        8     25    42      77     94
  9    0     18     62     71        9     30    51      93    114
 10    0     20     69     79       10     40    67     124    152


    Small Font (Font 2)                 Sans Serif Font (Font 3)

Size  Top    Bow   Base   Drop     Size   Top   Bow     Base   Drop
------------------------------     --------------------------------
  1    2      3      5      6        1      7    11      19     23
  2    2      4      6      7        2      7    12      21     25
  3    2      3      6      7        3      9    14      24     29
  4    3      5      9     11        4     11    18      32     39
  5    4      7     12     14        5     14    24      42     51
  6    5      9     15     18        6     18    30      53     64
  7    6     10     13     22        7     22    36      64     78
  8    7     12     22     27        8     28    45      80     97
  9    9     15     27     33        9     33    54      96    117
 10   12     20     36     44       10     74   102     158    186




     Gothic Font (Font 4)                Script Font (Font 5)

Size  Top    Bow   Base   Drop     Size   Top   Bow     Base   Drop
------------------------------     --------------------------------
  1    7     11     19     23        1     10    17      22     29
  2    7     12     21     25        2     10    18      24     32
  3    9     14     24     29        3     12    21      27     36
  4   11     18     32     39        4     16    28      37     49
  5   14     24     42     51        5     21    37      49     65
  6   18     30     53     64        6     26    46      61     80
  7   22     36     64     78        7     32    56      74     98
  8   28     45     80     97        8     40    70      92    122
  9   33     54     96    117        9     48    84     111    147
 10   44     72    128    156       10     63   111     147    195
    Simplex Font (Font 6)            Triplex Script Font (Font 7)

Size  Top    Bow   Base   Drop     Size   Top   Bow     Base   Drop
------------------------------     --------------------------------
  1    9     13     21     25        1      5     9      17     21
  2    9     14     23     27        2      5    10      19     23
  3   11     16     26     31        3      7    12      22     27
  4   14     21     35     42        4      9    16      30     37
  5   18     28     46     56        5     12    22      40     49
  6   23     35     58     69        6     15    27      50     61
  7   28     42     70     84        7     19    33      61     75
  8   35     52     87    104        8     24    41      77     93
  9   42     63    105    126        9     29    50      92    113
 10   56     84    140    168       10     39    67     123    151



    Complex Font (Font 8)               European Font (Font 9)

Size  Top    Bow   Base   Drop     Size   Top   Bow     Base   Drop
------------------------------     --------------------------------
  1    8     12     20     24        1      7    14      32     38
  2    8     13     22     26        2      7    15      35     41
  3   10     15     25     30        3      9    18      40     47
  4   13     20     34     41        4     12    24      54     64
  5   17     27     45     54        5     16    32      72     85
  6   22     34     57     68        6     20    40      96    106
  7   27     41     69     83        7     25    49     109    129
  8   34     51     86    103        8     31    61     136    161
  9   41     62    104    125        9     38    74     164    194
 10   54     83    139    167       10     51    99     219    259



     Bold Font (Font 10)

Size  Top    Bow   Base   Drop
------------------------------
  1   11     17     35     39
  2   13     19     39     43
  3   14     22     44     49
  4   19     29     59     66
  5   27     39     79     88
  6   33     49     99    110
  7   39     59    119    133
  8   49     74    149    166
  9   59     89    179    200
 10   79    199    239    267


The Chisel effect draws a dropshadowed line around the inside of the
button.  How far from the borders of the button are determined by
this table:

        Height of Button     X inset     Y inset
        ----------------------------------------
            0 - 11              1          1
           12 - 24              3          2
           25 - 39              4          3
           40 - 74              6          5
           75 - 149             7          5
          150 - 199             8          6
          200 - 249            10          7
          250 - 299            11          8
          300 -                13          9

This table describes the possible flag settings for the <flags2>
parameter:

Val Description of Flags Field #2    Icon Clip Plain Mouse No-Mouse
-------------------------------------------------------------------
 1  Button is in a check box group     Y    Y    Y     Y       N
 2  Highlight hotkey character         Y    Y    Y     Y       N
 4  Explode (zoom out when clicked)    Y    Y    Y     Y       N
 8  Left Justify Label (top/ctr/btm)   Y    Y    Y     Y       Y
16  Right Justify Label (top/ctr/btm)  Y    Y    Y     Y       Y
32  Don't fill-in button interior      N    N    Y     Y       Y      > v2.A0
64  Fill-in interior in fill pattern   N    N    Y     Y       Y      > v2.A0

Following is a more complete description of the flags described in    > v1.54
the <flags2> parameter:                                               > v1.54
                                                                      > v1.54
     BUTTON IS IN A CHECK BOX GROUP (flag 1) - When this flag is      > v1.54
     selected, then the button <group_no> is considered a Check-      > v1.54
     box group.  When in this mode, the Radio Group flag is not       > v1.54
     accessible - A Button Group can be a Radio Button, a Check-      > v1.54
     box button or neither, but not more than one at the same         > v1.54
     time.  A Check-box button group is a group of buttons where      > v1.54
     each button in the group can be either ON or OFF in any          > v1.54
     combination.  In this way, more than one button in the           > v1.54
     group can be clicked at the same time.  See the TEMPLATES        > v1.54
     section later on in this document for a complete discussion      > v1.54
     of how the Host Commands are processed for Check-Box buttons.    > v1.54
     If a check-box button is drawn as "pre-selected", then the       > v1.54
     Host Command is processed immediately upon inital drawing of     > v1.54
     the button (when it is received).                                > v1.54
                                                                      > v1.54
     HIGHLIGHT HOTKEY CHARACTER (flag 2) - When this flag is          > v1.54
     active, then the first occurence of the hotkey character         > v1.54
     in the label will be hilighted using the <uline_col> color.      > v1.54
     This gives the user a visual impression of what keystroke        > v1.54
     they need to type in order to activate the button without        > v1.54
     the mouse.                                                       > v1.54
     EXPLODE (ZOOM OUT WHEN CLICKED) (flag 4) - This optional         > v1.54
     flag is designed to "zoom out" from the button when the          > v1.54
     user clicks on it.  What is generally done is a dotted           > v1.54
     rectangle is drawn initially around the button and it is         > v1.54
     repeatedly redrawn over itself in XOR mode, constantly           > v1.54
     getting larger and larger until it hits the full size of         > v1.54
     the screen.  This gives the visual impression that the           > v1.54
     button is zooming out to another screen.  Each time another      > v1.54
     frame of the zooming rectangle is drawn, the previous            > v1.54
     rectangle on the inside of the new one is erased by XOR          > v1.54
     drawing the same rectangle over itself again.  This option       > v1.54
     does not need to be supported in order to be considered          > v1.54
     a RIPscrip terminal, although it would be nice.  In              > v1.54
     other words, this is not a "make or break" feature.              > v1.54

     LEFT JUSTIFY LABEL (TOP/CTR/BTM) (flag 8) - If this option       > v1.54
     is enabled, then any TOP, CENTER or BOTTOM label orientations    > v1.54
     will be left justified to the left edge of the button.  The      > v1.54
     exact indentation of the label from the interior of the          > v1.54
     button's base image depends on whether the chisel effect         > v1.54
     is active.  If chisel is OFF, then the indentation is 10         > v1.54
     pixel.  If chisel is ON, then the indentation is 20 pixels.      > v1.54
     This option can be combined with the Adjust Vertical Centering   > v1.54
     flag only if the label orientation is CENTER.                    > v1.54
                                                                      > v1.54
     RIGHT JUSTIFY LABEL (TOP/CTR/BTM) (flag 16) - If this option     > v1.54
     is enabled, then any TOP, CENTER or BOTTOM label orientations    > v1.54
     will be right justified to the right edge of the button.  The    > v1.54
     exact indentation of the label from the interior of the          > v1.54
     button's base image depends on whether the chisel effect         > v1.54
     is active.  If chisel is OFF, then the indentation is 10         > v1.54
     pixel.  If chisel is ON, then the indentation is 20 pixels.      > v1.54
     This option can be combined with the Adjust Vertical Centering   > v1.54
     flag only if the label orientation is CENTER.                    > v1.54

     DON'T FILL-IN BUTTON INTERIOR - If this option is enabled and    > v2.A0
     the button is a Plain Button, then the interior of the Button    > v2.A0
     will not be filled in with the surface color.  By default,       > v2.A0
     any plain button will have its interior filled in with the       > v2.A0
     surface color.  Use this option if you don't want the button     > v2.A0
     face to be drawn.                                                > v2.A0
                                                                      > v2.A0
     FILL-IN INTERIOR IN FILL PATTERN - If this option is enabled     > v2.A0
     in conjunction with a plain button, then the interior of the     > v2.A0
     button that would normally be filled in with the surface         > v2.A0
     color will instead, use the current Fill Color and Fill          > v2.A0
     Pattern to fill in the interior.  This allows for patterned      > v2.A0
     button faces.                                                    > v2.A0





---------------------------------------------------------------------
RIP_BUTTON
---------------------------------------------------------------------
         Function:  Define a Mouse Button
            Level:  1
          Command:  U
        Arguments:  x0:2 y0:2 x1:2 y1:2 hotkey:2 flags:1 slot:1
                    ...text
           Format:  !|1U <x0> <y0> <x1> <y1> <hotkey> <flags>
                    <slot> <text>
          Example:  !|1U010100003201iconfile<>Label<>HostCmd^m
  Uses Draw Color:  NO
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  NO
  Uses Font Sizes:  YES
    Uses Viewport:  YES                                               > v1.54

This command physically creates a new Button using a previously       > v2.A1
defined RIP_BUTTON_STYLE slot.  You may have at most 128              > v2.A1
different Mouse Buttons (you may have any number of non-Mouse         > v2.A1
Buttons).  The <slot> parameter determines which button style slot is > v2.A1
used to determine how this button appears.                            > v2.A1

The <x0> and <y0> parameters for this command designate the
upper-left corner of the Button.  This (X,Y) location may not be the
actual "absolute" corner position of the Button, as it may be
adjusted via the Special Effects functions that are part of the
RIP_BUTTON_STYLE command (see above).

The <x1> and <y1> parameters are only used for Plain Buttons when you
have not specified a specific Height and Width in the
RIP_BUTTON_STYLE command.  These parameters are used in Dynamically
Sized Buttons.  If the Height and Width in the RIP_BUTTON_STYLE are
non-zero, then these two parameters are set to zero.

The (x0,y0) and (x1,y1) parameters will be modified by the following
values for the different special effects:

  Effect Type   X0 Modifier   Y0 Modifier   X1 Modifier   Y1 Modifier
  -------------------------------------------------------------------
  Bevel         -bevel size   -bevel size   +bevel size   +bevel size
  Recess            -2            -2            +2            +2
  Sunken             0             0             0             0
  Chisel             0             0             0             0

The <hotkey> parameter is only used with Mouse Buttons.  It is the
ASCII code for the keystroke that will activate this Button.  It is
represented as a two-digit MegaNum.  If this character exists in the
text label, and the Underline flag or hilight hotkey flag is enabled  > v1.54
in the RIP_BUTTON_STYLE, then the character will be underlined in the
label.  Control codes are allowable, and a value of 255 (decimal)
corresponds to "any" key.


The <flags> parameter provides several different functions for each
button.  The possible "combinatorial" flags for this parameter are
listed in the following table.  Note that these values may be
combined together (by adding their values) to arrive at the final
flag parameter's value.
	
        Value  Description
        --------------------------------------------------
          1    Draw button as already selected
          2    Button is "default" when <ENTER> is pressed

Using a flag of 1 means that the Button is already "selected".  By
selected, we mean that it is already clicked and should be initially
drawn as clicked.  This is typically used for Radio Buttons and/or
Check Boxes.  This only affects the image.  The Host Command WILL NOT
be automatically sent to the host when a selected Button is drawn. If
this parameter is set to 0, then the Button will be drawn in normal,
unselected mode.

The <text> parameter for this command is somewhat different than
those found in previously described RIPscrip commands.  All other
RIPscrip commands only have one text parameter.  This command
requires  anywhere from 0-3 text parameters.  The way RIPscrip
accomplishes this is by separating each block in the <text> parameter
with the delimiter "<>".  This text parameter delimiter is not needed
before the first text block, but is necessary between the 1st and 2nd
blocks, and the 2nd and 3rd blocks.  Here is an example of a typical
text parameter for this command:

     ICONFILE.BMP<>TEXT LABEL<>HOST COMMAND                           > v2.A1

The actual syntax of this text parameter is as follows:

     [icon-file][[<>text-label][<>host-command]]

The block described as ICONFILE.BMP is actually the Icon Filename     > v2.A1
that will be used for the Button if it is an Icon Button.  If it is
not an Icon Button, then this block will read "<>" all by itself (a
"null" block).

Note that we actually specified a file extension of ".BMP" for our    > v2.A1
icon filename.  You shouldn't explicitly specify a filename extension > v2.A1
like this if it is the default extension of the filename.  The reason > v2.A1
for this is that some platforms don't use file extensions and their   > v2.A1
use is not really appropriate.  When in doubt, don't specify a file   > v2.A1
extension.                                                            > v2.A1

The .BMP file extension does not need to be included as part of the   > v2.A1
filename.  If omitted, it will automatically be appended to the
filename.  If an extension is provided, it will be used verbatim.

The "TEXT LABEL" block is actually the text that will be used to
descriptively label the Button.  You may also specify a "null" block
for no label (i.e., "<>").

The final block of the <text> parameter is the Host Command.  This
block contains any text that should be sent to the Host after this
Button is clicked.  This may contain any Control Characters,
Pick-List definitions, Text Variables or Template Definitions.  This
block might be "segmented" into multiple Host Command segments.  See
the section entitled HOST COMMANDS in this Manual for additional
information on these Host Command features.

When this command is stored in-memory, it is converted to global      > v1.54
screen coordinates (for internal storage only).  This makes it so     > v1.54
that if you have mouse button regions defined in multiple different   > v1.54
viewports, that each field will be properly inverted at the right     > v1.54
location regardless of the currently defined viewport.                > v1.54


NOTE: All Mouse Fields are scanned in "last in, first out" order.     > v1.54
      This means that the last-most received Mouse Button will be     > v1.54
      the first one scanned for a mouse click.                        > v1.54

Not all of the blocks in the <text> parameter need to be specified.
Here are examples of the valid combinations of text blocks:

  Parameter Example       Description of the Text Parameter
  -------------------------------------------------------------------
  icon<>label<>host_cmd   Specify all three blocks
    <>label<>host_cmd     2 blocks specified; no icon
      icon<>label<>       2 blocks specified; no host  command
       icon<>label        2 blocks specified; no host  command
      <><>host_cmd        1 block  specified; no icon  or label
       <>label<>          1 block  specified; no icon  or host command
        <>label           1 block  specified; no icon  or host command
       icon<><>           1 block  specified; no label or host command
        icon<>            1 block  specified; no label or host command
         icon             1 block  specified; no label or host command
        <><><>            A blank text parameter; all blocks omitted
         <><>             A blank text parameter; all blocks omitted
          <>              A blank text parameter; all blocks omitted

NOTE:  The <res> parameter is reserved for future use by TeleGrafix
       Communications, Inc..  It should be set to 0 for compatibility
       with future releases.





---------------------------------------------------------------------
RIP_DEFINE
---------------------------------------------------------------------
         Function:  Define a text variable
            Level:  1
          Command:  D
        Arguments:  flags:3 res:2 ...text
           Format:  !|1D <flags> <res> <text>
          Example:  !|1D00700text_var,60:?question?default data
  Uses Draw Color:  NO
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  NO
  Uses Font Sizes:  NO
    Uses Viewport:  NO                                                > v1.54

This command is used to create a text variable on the Client system
(i.e., the Terminal system).  A text variable is more fully covered
in the HOST COMMANDS section.  Simply put, a text variable is a piece
of information assigned to a 1-12 character identifier that can
either be saved to a local database file (static variables), or to
memory (dynamic variables).  Variable Identifiers can be 1-12
characters in length.  You may use any alphanumeric character and
underscores (_) in the identifier.  An underscore cannot be the first
character, nor can the first character of an identifier be a number.

The <flags> parameter of this command combines three separate values
into one MegaNum flag that determines how the variable definition
will operate.  Here are the possible flag values:

        Value     Description of Flag
        ---------------------------------------
        001     Save Variable to database
        002     Cannot specify a blank response
        004     Non-interactive query

When a variable is flagged as "Save to Database", it becomes a part
of the Client system's actual configuration.  The value is saved
indefinitely until either changed, or manually erased.  You may
choose not to allow the user to enter a blank response.  This
basically requires them to enter some piece of information for the
variable.

The last flag determines whether the definition is interactive or not.
An interactive definition will attempt to define the variable.  If it
does exist, it pops the value up on the screen asking the user to
confirm if the value is correct.  If it does not exist, a similar
pop-up box will appear asking the user to enter some data for the
given variable.

In a non-interactive situation, the Client system will check to see
if the variable exists.  If it does, then nothing happens (unless a
default response is specified in this command, whereby the Client's
variable is updated with the new information).  If the value is not
defined, then this definition becomes interactive by default, since
the user actually has to enter something anyway.


The <text> parameter for this command is also segmented in nature,
much like the RIP_BUTTON command is.  An example of a segmented
<text> parameter for the RIP_DEFINE command might be as follows:

          FULL_NAME,30:?What is your full name?John Doe

The actual syntax of the Variable Define text parameter is as
follows:

  variable-identifier[,field-width]:[?question-text?][default-value]

There are several different segments in this parameter as you can
see.  The first section is the variable- identifier.  Immediately
after it is an optional field-width.  If the field width is omitted,
it will default to a value of  60.  You should limit the values of
this width from 1-60.

Immediately following the identifier field-width parameter is a colon
(:).  The colon indicates that the variable identifier field is
completed and that the remainder of the text parameter is to contain
the question and/or the default response (if any).  If no question or
default response is provided, the text parameter would read
"TEXT_VAR,width:" with no additional data.

The question-text is specified by a question mark (?) followed by the
actual text of the question, followed by a trailing question mark.
The basic format of the question segment is as follows:

                    ?this is a question?

The remainder of the text parameter consists of a default-value for
the variable's contents.  It may be omitted if you wish, to make it
so that the user must enter his/her own value instead of some "canned
response".

NOTE:  The <res> parameter is reserved for future use by TeleGrafix
       Communications, Inc..  It should be set to 00 for
       compatibility with future releases.

       THIS COMMAND IS NOW OBSOLETE.  USE THE SPECIALLY ENHANCED      > v2.A1
       TEXT VARIABLE SYSTEM WITHIN QUERIES OR HOST COMMANDS TO        > v2.A1
       PRODUCE THE SAME RESULTS AS THIS COMMAND AND MUCH MORE!        > v2.A1

--------------------------------------------------------------------- > v2.A1
RIP_SCROLLER                                                          > v2.A1
--------------------------------------------------------------------- > v2.A1
         Function:  Defines a scroller interface object               > v2.A1
            Level:  1                                                 > v2.A1
          Command:  S                                                 > v2.A1
        Arguments:  id:1 x0:2 y0:2 x1:2 y1:2 entries:4 cur_ent:4      > v2.A1
                    page_size:4 flags:4 size:2 bright:2 dark:2        > v2.A1
                    surface:2 corner:2 res:4 host_string:...          > v2.A1
           Format:  !|1S <id> <x0> <y0> <x1> <y1> <entries> <cur_ent> > v2.A1
                    <page_size> <flags> <size> <bright> <dark>        > v2.A1
                    <surface> <corner> <res> <host_string>            > v2.A1
          Example:  !|1S010102040222211110008020F0807070000           > v2.A1
  Uses Draw Color:  NO                                                > v2.A1
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO                                                > v2.A1
  Uses Line Thick:  NO                                                > v2.A1
  Uses Fill Color:  NO                                                > v2.A1
Uses Fill Pattern:  NO                                                > v2.A1
  Uses Write Mode:  NO                                                > v2.A1
  Uses Font Sizes:  NO                                                > v2.A1
    Uses Viewport:  NO                                                > v2.A1
                                                                      > v2.A1
A scroller object is a rather high-level user interface object.  It   > v2.A1
is designed to allow a user to choose a setting from a range of valid > v2.A1
options.  For example, if you had a listing of 100 pieces of          > v2.A1
information, a scroller might be attached to this list initialized to > v2.A1
a current entry of 0 meaning that entry 0 in the list is the          > v2.A1
currently highlighted entry.  A scroller has the ability to move this > v2.A1
hilight up or down to a new current entry.  When the user is done     > v2.A1
moving the scroller to a new position, a new current entry is         > v2.A1
selected.  With this command, every time a new current setting is     > v2.A1
chosen, the host command is sent to the host system.  The contents of > v2.A1
the host command can be anything you wish, but it might be useful to  > v2.A1
have the special text variable $SCLCUR(id)$ to insert the current     > v2.A1
scroller entry number into the host command so that the host system   > v2.A1
can determine what the new choice is.                                 > v2.A1
                                                                      > v2.A1
A scroller object can be either a horizontal scroller or a vertical   > v2.A1
scroller.  This is specified as a particular <flag> value (see        > v2.A1
below).  A scroller consists of between three and five separate mouse > v2.A1
fields.  A scroller is actually defined as one complete mouse/button  > v2.A1
field, but it is sub-divided into several smaller sub-areas which do  > v2.A1
different things.  A scroller might appear something like the         > v2.A1
following:                                                            > v2.A1
                            ___ thumb                                 > v2.A1
   Down arrow              /    (drag bar)       Up arrow             > v2.A1
     ---------------------------------------------------              > v2.A1
    |     |             -----                     |     |             > v2.A1
    | <== |  PgDn area |     |      PgUp area     | ==> |             > v2.A1
    |     |            |_____|                    |     |             > v2.A1
     ---------------------------------------------------              > v2.A1
                                                                      > v2.A1
This shows the most general case of a scroller, with five separate    > v2.A1
scroller areas that can be clicked on.  The five separate areas are   > v2.A1
described as follows:                                                 > v2.A1
                                                                      > v2.A1
     1) DOWN ARROW - This arrow button is on one end of the           > v2.A1
        scroller.  Its purpose is to reduce the current entry         > v2.A1
        number by one.  The thumb (drag bar) is adjusted to           > v2.A1
        indicate the new position (if it makes any noticable          > v2.A1
        visual difference).  Also, the host command is transmitted    > v2.A1
        to the remote system.                                         > v2.A1
                                                                      > v2.A1

     2) UP ARROW - This arrow button is at the opposite end of the    > v2.A1
        scroller from the down arrow.  It increases the current       > v2.A1
        entry by one and updates the location of the thumb to         > v2.A1
        reflect the new current entry value.  The host command is     > v2.A1
        transmitted to the remote system upon completion of the       > v2.A1
        mouse click on the arrow.                                     > v2.A1
                                                                      > v2.A1
     3) THUMB (DRAG BAR) - The thumb is an object inside the          > v2.A1
        scroller that you can physically grab onto with the mouse     > v2.A1
        and drag up or down while the mouse button remains            > v2.A1
        depressed.  When the mouse button is released, then the       > v2.A1
        location of the thumb is compared to its original position.   > v2.A1
        If the new position corresponds to a new current entry        > v2.A1
        value, then the host command for the scroller is sent to      > v2.A1
        the remote system.                                            > v2.A1
                                                                      > v2.A1
     4) PGDOWN AREA - The page down area decrements the current       > v2.A1
        entry value by the value specified in the <page_size>         > v2.A1
        parmater of this command.  When the page down operation       > v2.A1
        is complete, the thumb's location is adjusted to reflect      > v2.A1
        the new current entry, and the host command is transmitted    > v2.A1
        to the remote system.  This clickable area will not be a      > v2.A1
        valid clickable area if the current entry is zero.  When      > v2.A1
        this is the case, the thumb is butted all the way up to       > v2.A1
        the down arrow and there is no page down region to click      > v2.A1
        on (the current entry cannot be decreased).                   > v2.A1
                                                                      > v2.A1
     5) PGDOWN AREA - The page up area increments the current         > v2.A1
        entry value by the value specified in the <page_size>         > v2.A1
        parmater of this command.  When the page up operation is      > v2.A1
        complete, the thumb's location is adjusted to reflect the     > v2.A1
        new current entry, and the host command is transmitted to     > v2.A1
        the remote system.  This clickable area will not be a         > v2.A1
        valid clickable area if the current entry is within one       > v2.A1
        <page_size> of the maximum number of entries.  When           > v2.A1
        this is the case, the thumb is butted all the way up to       > v2.A1
        the up arrow and there is no page down region to click        > v2.A1
        on (the current entry cannot be increased).                   > v2.A1
                                                                      > v2.A1
To define a scroller object, at the minimum, you need to specify the  > v2.A1
rectangular area on the screen that is to contain the scroller        > v2.A1
object.  Also, you must specify how many list entries this scroller   > v2.A1
is related to, what the current entry number is and what the page     > v2.A1
size is (for use with the page up and page down click areas).  Also,  > v2.A1
you need to specify a scroller ID number that uniquely identifies the > v2.A1
scroller in the RIPscrip system.  This makes it so the host can       > v2.A1
potentially identify which scroller is sending information to it.  In > v2.A1
addition, you specify some color values that help define how the      > v2.A1
scroller appears on the screen and some flags that determine how the  > v2.A1
scroller operations, and how it appears (special effects).  Each of   > v2.A1
these parameters (required values) is described in the following      > v2.A1
sub-sections.                                                         > v2.A1
                                                                      > v2.A1

The <flags> parameter defines the orientation of the scroller, and    > v2.A1
how it is to be drawn to the screen (ie, visual effects).  Some of    > v2.A1
effects are based on the effects used in the aforementioned button    > v2.A1
style command (refer to RIP_BUTTON_STYLE for a more complete          > v2.A1
description of these graphical special effects).                      > v2.A1
                                                                      > v2.A1
     Flags     Description                                            > v2.A1
     --------------------------------------------------------------   > v2.A1
         1     Scroller is a horizontal scroller object \ required    > v2.A1
         2     Scroler is a vertical scroller object    /   flag      > v2.A1
               ----------------------------------------------------   > v2.A1
         4     Display a recessed visual effect around scroller       > v2.A1
               area                                                   > v2.A1
         8     Display scroller area inside a beveled exterior        > v2.A1
               The <size> parameter defines the bevel thickness       > v2.A1
        16     Show the up/down arrows and the thumb with a sunken    > v2.A1
               attribute                                              > v2.A1
        32     Show the page up/page down areas as half-tone images   > v2.A1
               shown as the surface color and dark color in a         > v2.A1
               halftone bit pattern (every other dot).  In            > v2.A1
               RIP_LINE_STYLE definitions, the bit pattern for one    > v2.A1
               scan line of the area would be 0xAAAA and the other    > v2.A1
               line would be 0x5555 (in C syntax).                    > v2.A1
        64     Bevel the up/down arrow and thumb buttons based on     > v2.A1
               the <size> parameter (bevel size)                      > v2.A1
                                                                      > v2.A1
The <size> parameter defines how thick bevels should be for the       > v2.A1
outside of the scroller area, the increment and decrement arrows and  > v2.A1
also for the thumb buton.                                             > v2.A1
                                                                      > v2.A1
The <bright>, <dark>, <surface> and <corner> parameters define the    > v2.A1
colors used to specify the colors of the scroller object and its      > v2.A1
associated special effects (refer to RIP_BUTTON_STYLE for more        > v2.A1
detailed descriptions of these parameters).                           > v2.A1
                                                                      > v2.A1
The <entries> parameter defines how many list entries the scroller is > v2.A1
related to.  This important parameter determines how incrementing or  > v2.A1
decrementing the current entry responds.  For example, when the       > v2.A1
current entry hits the highest allowable entry, no more incrementing  > v2.A1
of the current entry should be allowed.                               > v2.A1
                                                                      > v2.A1
The <cur_ent> parameter defines which entry in the <entries> field    > v2.A1
is the current entry.  This defines where the thumb will be initially > v2.A1
drawn and where the current entry is located (for subsequent          > v2.A1
operations).                                                          > v2.A1
                                                                      > v2.A1
The <page_size> parameter defines how many entries should be added to > v2.A1
or deducted from the current entry when the page up or page down      > v2.A1
regions are clicked.  Typically, this is set to however many lines of > v2.A1
data are displayed on the screen (eg, the number of lines in a text   > v2.A1
window that the scroller is attached to, etc).  When the user clicks  > v2.A1
on the page up or page down areas, the current entry is modified by   > v2.A1
this amount and the thumb is redrawn and the host command is sent to  > v2.A1
the system (presumably to update the list on the user's screen).      > v2.A1
                                                                      > v2.A1
The <host_string> parameter is probably the most important parameter  > v2.A1
defining a scroller.  This identifies what information is sent to the > v2.A1
remote host system when the scroller object is modified (updated).    > v2.A1
Some kind of information needs to be transmitted to the host when a   > v2.A1
scroller is clicked to inform the host that the list positioning has  > v2.A1
changed.  There are a number of text variables defined which are      > v2.A1
specifically designed for scroller operation.  They are listed below, > v2.A1
but are described fully in the section on Built-in Text Variables.    > v2.A1
                                                                      > v2.A1

   Variables               Description                                > v2.A1
   -----------------------------------------------------------------  > v2.A1
   $SCLCUR(id)$            Returns the current entry number for a     > v2.A1
                           particular scroller "id" number.           > v2.A1
   $SCLID(id)$             Returns the scroller "id" number.          > v2.A1
                           -----------------------------------------  > v2.A1
   $SCLENTRIES(id)$        Returns the total number of scroller       > v2.A1
                           entries for a scroller "id" number.        > v2.A1
   $SCLCURSET(id,cur)$     Sets the current entry number for a        > v2.A1
                           particular scroller "id" number.           > v2.A1
   $SCLENTSET(id,tot)$     Sets the total number of scroller entries  > v2.A1
                           associated with a scroller "id" number.    > v2.A1
   $SCLPAGESET(id,size)$   Sets the page size for a particular        > v2.A1
                           scroller "id" number.                      > v2.A1
                                                                      > v2.A1
Notice how you can use a number of text variables to alter the        > v2.A1
settings of a currently defined scroller object.  The last four text  > v2.A1
variables are used for setting (updating) scroller configurations.    > v2.A1
The first two values though is paramount in retrieving scroller       > v2.A1
information when the user alters a scroller's settings.  See the text > v2.A1
variable section for complete descriptions of these variables.        > v2.A1
                                                                      > v2.A1
You are allowed up to 36 separate scrollers to be defined at the same > v2.A1
time in a scene.  You should make sure that each scroller has a       > v2.A1
different ID value so that no confusion occurs from the host system's > v2.A1
perspective.                                                          > v2.A1
                                                                      > v2.A1
NOTE:  Some discussion of special effects for this command have       > v2.A1
       been described.  The use of special effects for scrollers      > v2.A1
       is not required for the terminal program.  This is because     > v2.A1
       many GUI environments (Windows, Macintosh, etc) have built-    > v2.A1
       in scroller objects whose appearance cannot be (easily)        > v2.A1
       changed.  If you can support the special effects, great -      > v2.A1
       go for it.  If you cannot though, don't think the world is     > v2.A1
       coming to an end.                                              > v2.A1

---------------------------------------------------------------------
RIP_QUERY
---------------------------------------------------------------------
         Function:  Query the contents of a text variable
            Level:  1
          Command:  <escape>
        Arguments:  mode:1 window_num:1 res:2 ...text                 > v2.A0
           Format:  !|1<escape> <mode> <window_num> <res> <text>
          Example:  !|1<escape>2Q00this is a query $COMMAND$^m
  Uses Draw Color:  NO
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  NO
  Uses Font Sizes:  NO
    Uses Viewport:  NO                                                > v1.54

NOTE:  <escape> is used to indicate the Escape character (ASCII 27
       or ESC).

The Query Text Variable RIPscrip command instructs the terminal to
immediately respond with some piece of information, whether
statically stored (i.e., in a database), stored internally in RAM
(dynamic information), or pre-defined Text Variables.

This command is unique in RIPscrip in the fact that the command
character that is used is NOT a printable character.  We use the
escape character (ASCII 27) to introduce this command as a measure of
security.  Since the query command can query the terminal for some
critical (potentially private) information, you would not want a user
to be able to query another user's terminal for something like his
address information, or something that he wouldn't want to otherwise
divulge to unauthorized people.  Since most hosts do not allow the
user to enter an escape character, this character is ideal for this
purpose.  Using escape allows only the Host (under most
circumstances) to be in control of any queries.

NOTE:  This command is very flexible in that you can specify
       control characters, pick-list definitions and Text Variables.  > v2.A1
       See the section entitled HOST COMMANDS for a more detailed 
       explanation of these features.

Whether the information is transmitted instantly or not is dependent
on the <mode> parameter.  The <mode> parameter determines when data
queries are processed.  The possible settings for the <mode>
parameter are as follows:


    Mode     Description
    ----------------------------------------------------------------
     0    Process the query command NOW (upon receipt)
     1    Process when mouse clicked in the current Graphics          > v2.A0
          Viewport                                                    > v2.A0
     2    Process when mouse clicked in the current Text Window (any  > v2.A0
          text variables that return X or Y mouse coordinates return  > v2.A0
          TEXT coordinates, not graphics coordinates in this mode.    > v2.A0
          These coordinates are two-digit values instead of the       > v2.A0
          graphical values that are four digits).                     > v2.A0

     3    Process when mouse clicked in the Graphics Viewport         > v2.A0
          specified in the <window_num> parameter.  If that viewport  > v2.A0
          doesn't exist (hasn't been defined yet), then this query    > v2.A0
          command is ignored.                                         > v2.A0
     4    Process when mouse clicked in the Text Window specified     > v2.A0
          in the <window_num> parameter.  Any text variables that     > v2.A0
          return X or Y mouse coordinates return TEXT coordinates     > v2.A0
          based on that window's MicroANSI text font sizes, not       > v2.A0
          graphics coordinates in this mode.  These coordinates are   > v2.A0
          two-digit values instead of the graphical values that are   > v2.A0
          four digits).                                               > v2.A0

Note that modes 1-4 do not return the results of the Query instantly. > v2.A0
They query commands are processed when the user clicks the mouse
either in the text window, or in the graphics window respectively.
Which text window or graphics viewport is based both on the value of  > v2.A0
<mode> parameter and on the <window_num> parameter. If the <mode> is  > v2.A0
either a 1 or 2, then the current window/viewports are the areas that > v2.A0
are acted upon.  Modes 3 and 4 will take the window number from the   > v2.A0
<window_num> parameter as the text window/viewport to act upon.  If   > v2.A0
the associated window or viewport are not defined, then the query     > v2.A0
command is ignored.  These "queries after mouse clicks" are only      > v2.A0
acted upon if the user is clicking on something other than a Button
or a Mouse Field. To disable these two special "deferred" query
modes, issue the same command with the query string of $OFF$.  This
will disable this mode.  Providing a <text> parameter of anything
other than $OFF$ will produce a revised query command (active).

If more than one query command can be acted upon (ie, a query command > v2.A0
for the current graphics viewport is defined, and a query command     > v2.A0
specifically defined for that viewport is also defined), then the     > v2.A0
specific viewport query would be executed, followed immediately by    > v2.A0
the processing of the current window's query.                         > v2.A0

Basically put, a Query command will be immediately acted upon by the
Terminal program when received if the <mode> is 0.  The Query         > v2.A0
command's <text> parameter can contain any number of Host Command
"segments", which can instruct the terminal "how to" send data to the
host, and more specifically, what data to send to the host.

Some examples of query statements might be any of the following:

                        ^m     Send a carriage return to the BBS now!
  My name is $FULL_NAME$^m     Send text "My name is <insert-name-
                               here>" followed by a  carriage return
                               to the BBS.  The <insert-name-here>
                               will be replaced with whatever the
                               variable $FULL_NAME$ contains.

See the section entitled HOST COMMANDS for a detailed explanation of
Host Commands, and what you can do with the Query command.

NOTE:  The <res> parameter is reserved for future use by TeleGrafix
       Communications, Inc..  It should be set to 000 for
       compatibility with future releases.

       It should be mentioned that text window queries are performed  > v2.A1
       before any viewport queries when resident queries are          > v2.A1
       concerned.                                                     > v2.A1

---------------------------------------------------------------------
RIP_SCROLL                                                            > v2.A1
---------------------------------------------------------------------
         Function:  Copy (scroll) screen region up/down               > v2.A1
            Level:  1
          Command:  G
        Arguments:  x0:2 y0:2 x1:2 y1:2 mode:1 res:1 dest_line:2      > v2.A1
           Format:  !|1G <x0> <y0> <x1> <y1> <mode> <res> <dest_line> > v2.A1
          Example:  !|1G080G140M0005
  Uses Draw Color:  NO
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  NO
  Uses Font Sizes:  NO
    Uses Viewport:  NO                                                > v1.54

This command physically "copies" a rectangular region of the graphics
screen up or down.  The <dest_line> parameter is the Y position that
is the destination scan line to receive the region.  The Destination
of the copy can overlap the original region, but cannot be on the
same line.  You cannot move the image area left or right at all.  This
command is designated for vertical scrolling of graphical data either
up or down.

Due to hardware restrictions, the X0 and X1 parameters must be evenly
divisible by eight (8) (e.g., 0, 8, 16, etc.).  If the X0 and X1
parameters are NOT evenly divisible by eight, then the X0 parameter
will be reduced to the next most eight-pixel boundary, and the X1
parameter will be increased to the next eight-pixel boundary.  For
example, if X0=14, and X1=38, then X0 would be adjusted DOWN to 8,
and X1 would be adjusted UP to 40.  This is to ensure that the
desired graphical region is scrolled.

The original image area is left on the screen (is not cleared).  So if
you wish to perform some kind of scrolling effect, you will have to
clear the original area yourself.

If the destination region would place the image partially off-screen,
then the entire command is ignored!

This is one of the only graphical output commands that DOES NOT       > v1.54
adhere to the RIP_VIEWPORT command.  In other words, you can scroll   > v1.54
graphical data outside the current graphical viewport (even over the  > v1.54
text window!).                                                        > v1.54

The <mode> parameter instructs the terminal what to do with the       > v2.A1
part of the source rectangle that isn't covered up by the scrolled    > v2.A1
data.  You may specify several things to happen as defined by the     > v2.A1
mode values below:                                                    > v2.A1
                                                                     
     Mode  Description                                                > v2.A1
     -------------------------------------------------------------    > v2.A1
       0   Do nothing - leave the old graphics on the screen          > v2.A1
       1   Fill the old graphical area with the current drawing       > v2.A1
           color (solid fill in COPY mode).                           > v2.A1
       2   Fill the old graphical area with the current background    > v2.A1
           drawing color (solid fill in COPY mode).                   > v2.A1
       3   Fill the area with the current fill color (solid fill in   > v2.A1
           COPY mode).  Fill pattern/styles are not used for this.    > v2.A1
       4   Fill the old graphical area with the current fill          > v2.A1
           style/pattern in the current fill color.                   > v2.A1
       5   Erase the affected area entirely to black.                 > v2.A1
       6   Fill the affected area with the color of a pixel from      > v2.A1
           one of the corners of the affected rectangle.  If the      > v2.A1
           image area was scrolled up, then the color is taken        > v2.A1
           from the lower-right most pixel from the old graphical     > v2.A1
           rectangle (left exposed).  If the data is scrolled         > v2.A1
           down, then the rectangle is filled in with the color       > v2.A1
           of the pixel in the upper-left most pixel.  This is        > v2.A1
           mode is used so that if the area is a multi-colored        > v2.A1
           graphic, that a suitable fill color is used.               > v2.A1

--------------------------------------------------------------------- > v2.A1
RIP_COPY_BLIT                                                         > v2.A1
--------------------------------------------------------------------- > v2.A1
         Function:  Copy a screen area to a new location (bit blit)   > v2.A1
            Level:  1                                                 > v2.A1
          Command:  g                                                 > v2.A1
        Arguments:  x0:2 y0:2 x1:2 y1:2 dx0:2 dy0:2 mode:1 res:1      > v2.A1
           Format:  !|1g <x0> <y0> <x1> <y1> <dx0> <dy0> <mode> <res> > v2.A1
          Example:  !|1g080G140M112230
  Uses Draw Color:  YES
  Uses Back Color:  YES                                               > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  YES
Uses Fill Pattern:  YES
  Uses Write Mode:  NO
  Uses Font Sizes:  NO
    Uses Viewport:  NO                                                > v1.54

This command is similar to the RIP_SCROLL command but is more generic
in nature - it can move a rectangle of graphical information on the
screen from one position to another - not just up or down.  It does
this with high-speed bit-blit operations.  The rectangle contained in
(x0,y0) to (x1,y1) is copied so that its upper-left corner is now at
the location (dx0,dy0).

Some, part, or none of the original source image might be covered up
by the moved screen data.  The parts of the original image which are
still on the screen (unobscured) can be cleared to some color or
state if you wish by using the <mode> parameter (like RIP_SCROLL
does).  The possible settings for <mode> are:

     Mode  Description                                                > v2.A1
     -------------------------------------------------------------    > v2.A1
       0   Do nothing - leave the old graphics on the screen          > v2.A1
       1   Fill the old graphical area with the current drawing       > v2.A1
           color (solid fill in COPY mode).                           > v2.A1
       2   Fill the old graphical area with the current background    > v2.A1
           drawing color (solid fill in COPY mode).                   > v2.A1
       3   Fill the area with the current fill color (solid fill in   > v2.A1
           COPY mode).  Fill pattern/styles are not used for this.    > v2.A1
       4   Fill the old graphical area with the current fill          > v2.A1
           style/pattern in the current fill color.                   > v2.A1
       5   Erase the affected area entirely to black.                 > v2.A1
       6   Fill the affected area with the color of a pixel from      > v2.A1
           one of the corners of the affected rectangle.  If the      > v2.A1
           image area was scrolled up, then the color is taken        > v2.A1
           from the lower-right most pixel from the old graphical     > v2.A1
           rectangle (left exposed).  If the data is scrolled         > v2.A1
           down, then the rectangle is filled in with the color       > v2.A1
           of the pixel in the upper-left most pixel.  This is        > v2.A1
           mode is used so that if the area is a multi-colored        > v2.A1
           graphic, that a suitable fill color is used.               > v2.A1

---------------------------------------------------------------------
RIP_READ_SCENE
---------------------------------------------------------------------
         Function:  Playback local .RIP file
            Level:  1
          Command:  R
        Arguments:  res:8 filename...
           Format:  !|1R <res> <filename>
          Example:  !|1R00000000testfile.rip
  Uses Draw Color:  YES
  Uses Back Color:  YES                                               > v2.A1
Uses Line Pattern:  YES
  Uses Line Thick:  YES
  Uses Fill Color:  YES
Uses Fill Pattern:  YES
  Uses Write Mode:  YES
  Uses Font Sizes:  YES
    Uses Viewport:  NO                                                > v1.54

This command instructs the remote terminal to playback a local .RIP
file.  The current execution of RIPscrip commands will be temporarily
suspended and the contents of the designated RIP file will begin
executing.  Regardless of whether or not the current RIPscrip code
coming across the modem is in the middle of a line or not, the RIP
playback file will be assumed to start at the beginning of a line.
Therefore, if a RIP_READ_SCENE command is located in a .RIP file, it
must be the very last command on the line, followed by a carriage
return instead of a command delimiter (|).  This ensures that the
loaded .RIP file will begin executing properly with the correct
delimiters found in the correct places.

The RIP playback file can alter colors, fonts, or whatever.  Once the
playback of the file is complete, the remaining RIPscrip code that
was temporarily suspended will be resume execution.  Any changes that
appeared in the loaded playback file will remain in effect when the
resumed code is processed.  In other words, if you change a color or
a font in the playback file and leave them changed, they will remain
in effect during the resumed execution.

NOTE:  The <res> parameter is reserved for future development by
       TeleGrafix.  It should be set to "00000000" for compatibility
       with future releases.





---------------------------------------------------------------------
RIP_FILE_QUERY
---------------------------------------------------------------------
         Function:  Query existing information on a particular file
            Level:  1
          Command:  F
        Arguments:  mode:2 res:4 filename...
           Format:  !|1F <mode> <res> <filename>
          Example:  !|1F010000testfile.icn
  Uses Draw Color:  NO
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  NO
  Uses Font Sizes:  NO
    Uses Viewport:  NO                                                > v1.54

This command queries the existence of a particular file, regardless
of type.  It is intended for host systems to determine if a
particular Icon or RIP file exists on the terminal;s hard disk.

There are a variety of ways you can query for filenames.  The <mode>
parameter determines the command's response.  This command instructs
the terminal to send a response to the host immediately upon
execution.

The following table is a listing of the possible values for <mode>:

Mode  Description
----------------------------------------------------------------------
 00   Simply query the existence of the file.  If it exists, a "1" is
      returned.  Otherwise a "0" is returned to the Host (without a
      carriage return).
 01   Same as 0, except a carriage return is added after the response.
 02   Queries the existence of a file.  If it does not exist, a "0" is
      returned to the Host followed by a carriage return.  If it does
      exist, the returned text is a "1." followed by the file size (in
      decimal).  The return sequence is terminated by a carriage
      return.  An example of the returned text could be "1.20345".
 03   Queries extended return information.  If the file does not
      exist, a "0" is returned followed by a carriage return.  If it
      does exist, the text returned to the Host is in the Format:
      1.size.date.time <cr>.  An example of a return statement could
      be "1.20345.01/02/93.03:04:30<cr>"
 04   Queries extended return information.  If the file does not
      exist, a "0" is returned followed by a carriage return.  If it
      does exist, the text returned to the Host is in the Format:
      1.filename.size.date.time <cr>. An example of a return statement
      could be "1.MYFILE.RIP.20345.01/02/93.03:04:30 <cr>".  Note that
      the file extension adds another period into the return text.






--------------------------------------------------------------------- > v2.A1
RIP_SET_MOUSE_CURSOR                                                  > v2.A1
--------------------------------------------------------------------- > v2.A1
         Function:  Causes the Client Terminal to Pause               > v2.A1
            Level:  1                                                 > v2.A1
          Command:  c                                                 > v2.A1
        Arguments:  cursor_style:2 res:4                              > v2.A1
           Format:  !|1c <cursor_style> <res>                         > v2.A1
          Example:  !|1c030000                                        > v2.A1
  Uses Draw Color:  NO                                                > v2.A1
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO                                                > v2.A1
  Uses Line Thick:  NO                                                > v2.A1
  Uses Fill Color:  NO                                                > v2.A1
Uses Fill Pattern:  NO                                                > v2.A1
  Uses Write Mode:  NO                                                > v2.A1
  Uses Font Sizes:  NO                                                > v2.A1
    Uses Viewport:  NO                                                > v2.A1
                                                                      > v2.A1
This command allows you to alter the current mouse cursor shape that  > v2.A1
is shown on the screen.  This feature lets you change the cursor to   > v2.A1
another shape to give the user of the terminal an idea that something > v2.A1
is going on.  For example, changing the cursor to the shape of an     > v2.A1
hourglass or a watch could give the idea that they should wait for a  > v2.A1
moment because something is going on.                                 > v2.A1
                                                                      > v2.A1
The <cursor_style> parameter is an ID number that specifies which     > v2.A1
cursor style should be activated.  The possible values for this       > v2.A1
parameter are:                                                        > v2.A1
                                                                      > v2.A1
     Style     Description                                            > v2.A1
     ----------------------------------------------------------       > v2.A1
       00      Standard pointer cursor (default)                      > v2.A1
       01      Cross-hair cursor                                      > v2.A1
       02      Pointing finger cursor                                 > v2.A1
       03      Hand held up cursor                                    > v2.A1
       04      Hourglass cursor                                       > v2.A1
       05      Wrist watch cursor                                     > v2.A1
       06      I-bar cursor (for text editing)                        > v2.A1
                                                                      > v2.A1
When a RIP_RESET_WINDOWS or a RIP_HEADER command is executed, the     > v2.A1
mouse cursor is automatically reset to the default, standard pointer  > v2.A1
cursor.                                                               > v2.A1

=====================================================================
==                          LEVEL-2 COMMANDS                       ==
=====================================================================

--------------------------------------------------------------------- > v2.A0
RIP_SWITCH_TEXT_WINDOW                                                > v2.A0
--------------------------------------------------------------------- > v2.A0
         Function:  Switch to another Text Window (activate)          > v2.A0
            Level:  2                                                 > v2.A0
          Command:  S                                                 > v2.A0
        Arguments:  <window_num>:1 <res>:1                            > v2.A0
           Format:  !|2S <window_num> <res>                           > v2.A0
          Example:  !|2S30                                            > v2.A0
  Uses Draw Color:  NO                                                > v2.A0
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO                                                > v2.A0
  Uses Line Thick:  NO                                                > v2.A0
  Uses Fill Color:  NO                                                > v2.A0
Uses Fill Pattern:  NO                                                > v2.A0
  Uses Write Mode:  NO                                                > v2.A0
  Uses Font Sizes:  NO                                                > v2.A0
    Uses Viewport:  NO                                                > v2.A0
                                                                      > v2.A0
In RIPscrip, you are allowed to have up to 36 separate text windows   > v2.A0
on screen simultaneously (0-9, A-Z).  These windows maintain their    > v2.A0
own "current ANSI attributes", cursor position, text window           > v2.A0
dimensions/location, cursor ON/OFF status and whether the window is   > v2.A0
Active or Disabled.                                                   > v2.A0
                                                                      > v2.A0
When you switch to another window, if that window hasn't been defined > v2.A0
yet, then the current window definition is copied to the new window   > v2.A0
slot.  When you switch to another window, the cursor is hidden in the > v2.A0
previous window and re-drawn in the new window (if it was visible the > v2.A0
last time the window was used).                                       > v2.A0
                                                                      > v2.A0
If you switch to a window that is "disabled", it will hide the cursor > v2.A0
from whatever window was previously active and then execute the       > v2.A0
proper disable text window sequence for the newly selected window     > v2.A0
slot.                                                                 > v2.A0
                                                                      > v2.A0
When a RIP_RESET_WINDOWS command is acted upon, any previously        > v2.A0
defined text window slots are erased and Window #0 is set to full     > v2.A0
screen mode (using the User's selected MicroANSI font), and the       > v2.A0
current window number is set to window #0.                            > v2.A0





--------------------------------------------------------------------- > v2.A0
RIP_SWITCH_VIEWPORT                                                   > v2.A0
--------------------------------------------------------------------- > v2.A0
         Function:  Switch to another Graphics Viewport (activate)    > v2.A0
            Level:  2                                                 > v2.A0
          Command:  s                                                 > v2.A0
        Arguments:  <viewport_num>:1 <res>:1                          > v2.A0
           Format:  !|2s <viewport_num> <res>                         > v2.A0
          Example:  !|2s30                                            > v2.A0
  Uses Draw Color:  NO                                                > v2.A0
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO                                                > v2.A0
  Uses Line Thick:  NO                                                > v2.A0
  Uses Fill Color:  NO                                                > v2.A0
Uses Fill Pattern:  NO                                                > v2.A0
  Uses Write Mode:  NO                                                > v2.A0
  Uses Font Sizes:  NO                                                > v2.A0
    Uses Viewport:  NO                                                > v2.A0
                                                                      > v2.A0
In RIPscrip, you are allowed to have up to 36 separate graphical      > v2.A0
viewports on screen simultaneously (0-9, A-Z).  These viewports       > v2.A0
maintain their own viewport dimensions, locations and Drawing         > v2.A0
Coordinate Frame configurations.                                      > v2.A0
                                                                      > v2.A0
When you switch to another viewport, if that viewport hasn't been     > v2.A0
defined yet, then the current viewport definition is copied to the    > v2.A0
new viewport slot.                                                    > v2.A0
                                                                      > v2.A0
If you switch to a viewport that is "disabled", all further RIPscrip  > v2.A0
code that would normally be drawn, will be discarded until something  > v2.A0
is done that would perform a non-graphical operation, or set the      > v2.A0
viewport to something new that isn't disabled.  slot.                 > v2.A0
                                                                      > v2.A0
When a RIP_RESET_WINDOWS command is acted upon, any previously        > v2.A0
defined viewport slots are erased and viewport #0 is set to full      > v2.A0
screen mode, and the current viewport number is set to viewport #0.   > v2.A0





--------------------------------------------------------------------- > v2.A0
RIP_SWITCH_STYLE                                                      > v2.A0
--------------------------------------------------------------------- > v2.A0
         Function:  Switches to a new Drawing Style Context           > v2.A0
            Level:  2                                                 > v2.A0
          Command:  Y                                                 > v2.A0
        Arguments:  <style_num>:1 <res>:1                             > v2.A0
           Format:  !|2Y <style_num> <res>                            > v2.A0
          Example:  !|2YG0                                            > v2.A0
  Uses Draw Color:  YES                                               > v2.A0
  Uses Back Color:  YES                                               > v2.A1
Uses Line Pattern:  YES                                               > v2.A0
  Uses Line Thick:  YES                                               > v2.A0
  Uses Fill Color:  YES                                               > v2.A0
Uses Fill Pattern:  YES                                               > v2.A0
  Uses Write Mode:  YES                                               > v2.A0
  Uses Font Sizes:  YES                                               > v2.A0
    Uses Viewport:  YES                                               > v2.A0
                                                                      > v2.A0
This command switches to a particular "drawing style".  A drawing     > v2.A0
style is a combination of the following graphical settings:           > v2.A0
                                                                      > v2.A0
     - Current drawing color                                          > v2.A1
     - Current background drawing color                               > v2.A1
     - Current fill pattern number (or user-defined fill pattern)     > v2.A1
     - Current fill color                                             > v2.A1
     - Current line pattern number (or user-defined line pattern)     > v2.A1
     - Line pattern odd drawing rule (see RIP_LINE_STYLE)             > v2.A1
     - Current mouse cursor style number                              > v2.A1
     - Current font number (or font name for extended fonts)          > v2.A1
     - Current font size, orientation and horizontal/vertical         > v2.A1
       alignment                                                      > v2.A1
     - Current write mode (raster/transfer operation)                 > v2.A1
     - Current color mode (palette or direct RGB)                     > v2.A1
     - Current X/Y location (used with RIP_TEXT commands)             > v2.A1
     - Current image mode settings (see RIP_IMAGE_STYLE)              > v2.A1
                                                                      > v2.A0
By default, all commands that alter the above modes will change the   > v2.A0
settings of Style #0.  By switching Style Contexts, you are given the > v2.A0
ability to alter which Style Context is being manipulated.  After a   > v2.A0
given Style has been defined, you can quickly switch from one Style   > v2.A0
to another without having to re-transmit each and every mode command  > v2.A0
to recreate the environment.                                          > v2.A0
                                                                      > v2.A0
The first time you switch to a new Style Context, the contents of the > v2.A0
current Style are copied into the newly selected Style.  You are      > v2.A0
allowed up to 36 separate Styles (0-9, A-Z).                          > v2.A0
                                                                      > v2.A0
Whenever a RIP_RESET_WINDOWS function is executed, the contents of    > v2.A0
all Styles are reset to a default status which is the Status of the   > v2.A0
drawing environment after Resetting is complete.                      > v2.A0






--------------------------------------------------------------------- > v2.A1
RIP_SET_REFRESH                                                       > v2.A1
--------------------------------------------------------------------- > v2.A1
         Function:  Sets a sequence to send host to refresh display   > v2.A1
            Level:  2                                                 > v2.A1
          Command:  R                                                 > v2.A1
        Arguments:  res:4 refresh_string:...                          > v2.A1
           Format:  !|2R <res> <refresh_string>                       > v2.A1
          Example:  !|2R0000^m                                        > v2.A1
  Uses Draw Color:  NO                                                > v2.A1
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO                                                > v2.A1
  Uses Line Thick:  NO                                                > v2.A1
  Uses Fill Color:  NO                                                > v2.A1
Uses Fill Pattern:  NO                                                > v2.A1
  Uses Write Mode:  NO                                                > v2.A1
  Uses Font Sizes:  NO                                                > v2.A1
    Uses Viewport:  NO                                                > v2.A1
                                                                      > v2.A1
This command sets a host command sequence in the terminal that can be > v2.A1
sent to the host to refresh the current display screen.  This refresh > v2.A1
option would be chosen by the user to redisplay the screen in case    > v2.A1
line noise or some kind of corruption caused the screen to become     > v2.A1
distorted or corrupted.  This can only be altered (or cleared) by a   > v2.A1
RIP_SET_REFRESH command or via a hard reset.  To completely clear a   > v2.A1
refresh state, call this command with a $NULL$ text variable as its   > v2.A1
host command or use the text variable $NOREFRESH$.                    > v2.A1
                                                                      > v2.A1
The host command portion of this sequence can contain any kind of     > v2.A1
host command information including control characters, pick lists,    > v2.A1
text variables or many other things.                                  > v2.A1






=====================================================================
==                          LEVEL-3 COMMANDS                       ==
=====================================================================

--------------------------------------------------------------------- > v2.A0
RIP_DELAY                                                             > v2.A0
--------------------------------------------------------------------- > v2.A0
         Function:  Causes the Client Terminal to Pause               > v2.A0
            Level:  3                                                 > v2.A1
          Command:  D                                                 > v2.A0
        Arguments:  <delay_period>:4                                  > v2.A0
           Format:  !|3D <delay_period>                               > v2.A1
          Example:  !|3D002D                                          > v2.A1
  Uses Draw Color:  NO                                                > v2.A0
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO                                                > v2.A0
  Uses Line Thick:  NO                                                > v2.A0
  Uses Fill Color:  NO                                                > v2.A0
Uses Fill Pattern:  NO                                                > v2.A0
  Uses Write Mode:  NO                                                > v2.A0
  Uses Font Sizes:  NO                                                > v2.A0
    Uses Viewport:  NO                                                > v2.A0
                                                                      > v2.A0
This command will cause the remote terminal to Pause for              > v2.A0
<delay_period> number of "timer ticks".  A Timer Tick is defined as   > v2.A0
being 1/60th of a second.  So, a delay period of 60 would be equal to > v2.A1
one full second of delay.                                             > v2.A0
                                                                      > v2.A0
While the delay is occuring, the RIP_ANIMATE command can still be     > v2.A0
active and processing its data.                                       > v2.A0
                                                                      > v2.A0
During the time period of the delay, the remote terminal should be    > v2.A0
queueing up any incoming RIPscrip code or raw text (if any) into some > v2.A0
form of internal buffer to prevent character loss.  After the delay   > v2.A0
period is complete, the data in that buffer (if any) should be        > v2.A0
processed immediately and the terminal should resume processing the   > v2.A0
incoming stream of data.                                              > v2.A0





--------------------------------------------------------------------- > v2.A0
RIP_BAUD_EMULATION                                                    > v2.A0
--------------------------------------------------------------------- > v2.A0
         Function:  Set Baud Rate Emulation for Local RIP Playback    > v2.A0
            Level:  3                                                 > v2.A1
          Command:  e                                                 > v2.A1
        Arguments:  rate_val:2                                        > v2.A0
           Format:  !|3e <rate_val>                                   > v2.A1
          Example:  !|3e03                                            > v2.A1
  Uses Draw Color:  NO                                                > v2.A0
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO                                                > v2.A0
  Uses Line Thick:  NO                                                > v2.A0
  Uses Fill Color:  NO                                                > v2.A0
Uses Fill Pattern:  NO                                                > v2.A0
  Uses Write Mode:  NO                                                > v2.A0
  Uses Font Sizes:  NO                                                > v2.A0
    Uses Viewport:  NO                                                > v2.A0
                                                                      > v2.A0
This command will set the rate at which local RIP file playback is    > v2.A0
performed.  By default, local RIP playback is done at full speed      > v2.A0
which is dependent on your CPU, hard disk speed and many other        > v2.A0
factors.  With this command, you can set the speed at which the       > v2.A0
playback is performed so that it can approximate a particular baud    > v2.A0
rate.  This setting will remain in effect even after a                > v2.A0
RIP_RESET_WINDOWS command so that a Reset command inside a local RIP  > v2.A0
file will not drastically alter the playback speed in mid-stride.     > v2.A0
The setting remains in effect until changed explicitly by the user    > v2.A0
(if possible under the terminal software), or by the Host via another > v2.A0
RIP_BAUD_EMULATION command.                                           > v2.A0
                                                                      > v2.A0
The possible values for the <rate_val> parameter are as follows:      > v2.A0
                                                                      > v2.A0
     Value     Description                                            > v2.A0
     -------------------------------------------                      > v2.A0
       0       No Emulation (full speed)                              > v2.A0
       1       300 baud emlulation                                    > v2.A0
       2       1200 baud emlulation                                   > v2.A0
       3       2400 baud emlulation                                   > v2.A0
       4       4800 baud emlulation                                   > v2.A0
       5       9600 baud emlulation                                   > v2.A0
       6       14,400 baud emlulation                                 > v2.A0
       7       16,800 baud emlulation                                 > v2.A0
       8       19,200 baud emlulation                                 > v2.A0
       9       28,800 baud emlulation                                 > v2.A0
       A       38,400 baud emlulation                                 > v2.A0
       B       57,600 baud emlulation                                 > v2.A0
       C       115,200 baud emlulation                                > v2.A0






--------------------------------------------------------------------- > v2.A0
RIP_ANIMATE                                                           > v2.A0
--------------------------------------------------------------------- > v2.A0
         Function:  Begins a bitmap animated motion sequence          > v2.A0
            Level:  3                                                 > v2.A0
          Command:  A                                                 > v2.A0
        Arguments:  res:1 clipboard_no:1 pages:1 page_inc:2           > v2.A1
                    flags:4 invis_color:4 res:4 x0:2 y0:2 segments:2  > v2.A0
                    x1:2 y1:2 frames:2 delay_rate:2 ...               > v2.A0
           Format:  !|3A <res> <clipboard_no> <pages> <page_inc>      > v2.A1
                    <flags> <invis_color> <res> <x0> <y0> <segments>  > v2.A0
                    <x1> <y1> <frames> <delay_rate> ...               > v2.A0
          Example:  !|3A03100000000300000000013F0D0Z03                > v2.A1
  Uses Draw Color:  NO                                                > v2.A0
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO                                                > v2.A0
  Uses Line Thick:  NO                                                > v2.A0
  Uses Fill Color:  NO                                                > v2.A0
Uses Fill Pattern:  NO                                                > v2.A0
  Uses Write Mode:  NO                                                > v2.A0
  Uses Font Sizes:  NO                                                > v2.A0
    Uses Viewport:  YES                                               > v2.A0
                                                                      > v2.A0
     NOTE: Multiple Animation channels have been removed from         > v2.A1
           the animate command in revision 2.A1.  This was            > v2.A1
           due to exceeding complexity.  The 1 byte reserved          > v2.A1
           parameter corresponds to the channel parameter which       > v2.A1
           may be taken advantage of in the future.  For              > v2.A1
           compatibility, this reserved parameter should be           > v2.A1
           set to zero to indicate channel 0.                         > v2.A1
                                                                      > v2.A0
This command is quite complex in nature - but it brings the essence   > v2.A0
of multimedia to RIPscrip: Animation!  Animation is performed in      > v2.A0
RIPscrip in a bitmap fashion.  However, unlike some forms of bitmap   > v2.A0
animation, the form of animation in RIPscrip provides for a great     > v2.A0
deal of flexibility like different bitmaps for each frame of the      > v2.A0
animation, varied delay rates between frames, multiple path segments  > v2.A0
(ie, Poly-Line path segments), invisible (transparent) colors, etc.   > v2.A1
                                                                      > v2.A0
The image(s) used for the animation "object" are taken from pages on  > v2.A0
the clipboard.  Since the RIPscrip clipboard can contain more than    > v2.A0
one image on it (on different clipboard "pages"), you can use these   > v2.A0
pages for animation sequences.                                        > v2.A0
                                                                      > v2.A0
You can also specify how many consecutive clipboard pages are to be   > v2.A0
used in any one particular animation sequence.  What this means is    > v2.A1
an animation could use pages 3, 4 and 5 for its animation objects.    > v2.A1
Which page is used at whatever time depends on the various settings   > v2.A1
of the <clipboard_no>, <pages> and <page_inc> parameters.             > v2.A1
                                                                      > v2.A0
The <clipboard_no> parameter specifies the base clipboard page to use > v2.A0
for the animation.  The <pages> parameter specifies how many          > v2.A0
clipboard pages will be used throughout the animation sequence.  The  > v2.A0
<page_inc> option says how many frames must execute in order to       > v2.A0
switch to another clipboard page for the animation object.  For       > v2.A0
example, if you set the <clipboard_no> option to 3, the <pages> to 3  > v2.A0
and the <page_inc> to 2, then the animation will use clipboard pages  > v2.A0
3, 4 and 5.  In addition, the current clipboard page will change with > v2.A0
every other frame.  In other words, the first two frames would use    > v2.A0
page #3, the third and fourth frames would use page #4 and the fifth  > v2.A0
and sixth frames would use page #5.                                   > v2.A0
The <invis_color> parameter allows you to specify a color in the      > v2.A0
bitmap(s) that will be "transparent".  This parameter will only be    > v2.A0
used if the "Use Transparent Color" flag is specified in the <flags>  > v2.A0
parameter (see below under flags).  When this option is used,         > v2.A0
whatever color is specified in this parameter will be considered      > v2.A0
transparent - allowing anything underneath that color to "show        > v2.A0
through" the animation object's bitmap.                               > v2.A0

The <x0> and <y0> parameters are the starting point for the           > v2.A0
animation.  The image used for this animation will be placed with its > v2.A0
upper-left corner at this (X,Y) location at the beginning of the      > v2.A0
animation sequence.                                                   > v2.A0
                                                                      > v2.A0
The <segments> parameter specifies how many path segments are         > v2.A0
contained in the sequence.  The minimum value for this option is "1"  > v2.A0
for a single straight line.  You may specify up to 64 separate        > v2.A0
"segments" for the animation, similar in concept to a polyline.  This > v2.A0
allows the animation to traverse over a non-straight path allowing    > v2.A0
for the concept of complex animation motions.                         > v2.A0
                                                                      > v2.A0
After the <segments> parameter will follow blocks of four parameters. > v2.A0
The total number of blocks should be the total number of <segments>.  > v2.A0
So, if there are two segments, then there should be two blocks of     > v2.A0
four parameters (or eight parameters total) following the <segments>  > v2.A0
parameter.  The first two parameters in this block are <x1> and <y1>  > v2.A0
which specify the destination (X,Y) location of the path segment.     > v2.A0
This will be used with the base coordinate <x0> and <y0> to determine > v2.A0
the line segment that the object will traverse for the current        > v2.A0
segment.  When the segment is complete, the destination point (x1,y1) > v2.A0
will become the starting point of the next segment and the the        > v2.A0
process resumes as before.                                            > v2.A0
                                                                      > v2.A0
The <frames> parameter determines how many individual animation cells > v2.A0
should be generated for the particular path segment.  For example, if > v2.A0
the eight frames are used, then the bitmap will be drawn at eight     > v2.A0
distinct locations along the path segment before it reaches the end   > v2.A0
of that animation segment.  When the final frame in that segment has  > v2.A0
completed, the next segment is acted upon.                            > v2.A0
                                                                      > v2.A0
The <delay_rate> parameter is a frame delay, indicating how long to   > v2.A0
delay in between each frame of the segment.  This is included as a    > v2.A0
segment parameter and not a global animation parameter so that        > v2.A0
different path segments of a particular sequence can have different   > v2.A0
timing - giving full flexibility.  The <delay_rate> is specified in   > v2.A0
1/18th's of a second intervals like the RIP_DELAY command.  In other  > v2.A0
words, if you want a 1/2 second interval between frames, set the      > v2.A0
<delay_rate> parameter to 9.                                          > v2.A0
                                                                      > v2.A0
Whenever the bitmap is placed on the screen, it is always done so in  > v2.A0
COPY mode.  No "raster operations" are allowed on animation           > v2.A0
sequences.  In other words, no XOR, AND, OR or NOT operations are     > v2.A0
allowed on the animation bitmap object when it is placed on the       > v2.A0
screen.  This is for performance reasons.                             > v2.A0
The <flags> parameter determines the many various aspects of the      > v2.A0
animation sequence.  Each of these flags can be OR'd together to      > v2.A0
produce one final flag parameter.  The values and meanings of each    > v2.A0
flag are as follows:                                                  > v2.A0
                                                                      > v2.A0
   Flags  Description                                                 > v2.A0
   -----------------------------------------------------------------  > v2.A0
       1  Loop the animation endlessly - returning to the first       > v2.A0
          segment when the final one is complete.  If the last        > v2.A0
          segment's X/Y location are the sequence's original          > v2.A0
          starting point, then a smooth flowing loop will be          > v2.A0
          apparent.                                                   > v2.A0
       2  Do not erase the image after each frame.  By default,       > v2.A0
          before the animation bitmap is drawn to the screen,         > v2.A0
          the area that will be covered up is saved temporarily.      > v2.A0
          Once the frame is over, the image is restored so that       > v2.A0
          you can see what was originally behind the object as        > v2.A0
          it moves.  If you use this flag, then this preservation     > v2.A0
          act does not occur and the bitmap will remain on the        > v2.A0
          screen at the location of each frame.                       > v2.A0

       4  Instead of restoring the background image after the         > v2.A0
          end of each frame, simply black out the affected region.    > v2.A0
          This is significantly faster than restoring original image. > v2.A0
       8  Instead of restoring the background image after the         > v2.A0
          end of each frame, use the current fill color and fill      > v2.A0
          pattern to clear the area.                                  > v2.A0
          This is significantly faster than restoring original image. > v2.A0
      16  Use Transparency Color.  If this flag is not used, then     > v2.A0
          the bitmap image(s) are drawn on the screen verbatim.       > v2.A0
          If you do use this flag, then whatever color is specified   > v2.A0
          in the <invis_color> parameter will not be drawn on the     > v2.A0
          screen during each frame.  This allows for parts of the     > v2.A0
          bitmap to "show through" to what was behind it before       > v2.A0
          the object was drawn.  This can slow down the animation.    > v2.A0
      32  Use Page Inversion Sequencing.  Normally, if you specify    > v2.A0
          to use multiple clipboard pages for your animation, when    > v2.A0
          the last page is used, the next page will be the first      > v2.A0
          one again as in a simple loop (eg, Pages 3, 4, 5, 3, 4,     > v2.A0
          5).  If you use this flag however, the pages used will      > v2.A0
          reverse when the animation hits the end of the pages (eg,   > v2.A0
          1, 2, 3, 4, 3, 2, 1, 2, 3, 4).  This allows for less        > v2.A0
          pages to be used for some forms of animation.               > v2.A0
      64  Begin animation immediately (by default, the animation      > v2.A0
          is not started until a Begin Animation control sequence     > v2.A0
          is received via a RIP_ANIMATION_CONTROL command).           > v2.A0
     128  Draw initial frame at starting position.  This is really    > v2.A0
          only useful when the animation is not started immediatley.  > v2.A0
     256  When animation is complete, leave the last drawn frame on   > v2.A0
          the screen.  By default, when animation is complete, the    > v2.A0
          last frame's object is removed from the screen leaving no   > v2.A0
          trace of the animation on the screen at all (except for     > v2.A0
          possibly disturbed background images based on other flags). > v2.A0
                                                                      > v2.A1
An animation sequence is checked for a new frame (motion)             > v2.A1
during idle times in RIPscrip/text processing.  What this means is,   > v2.A0
all animation sequences are checked for refreshing/updating in-       > v2.A0
between RIPscrip command sequences.  Since some RIPscrip commands can > v2.A0
take a few moments to complete (like a Block File Transfer), timing   > v2.A0
may not be exact - but as close as possible.  This prevents from      > v2.A0
extreme architectural difficulties on many platforms (ie, animation   > v2.A0
is not interrupt level based).                                        > v2.A0
                                                                      > v2.A0
Since RIPscrip drawing can occur at the same time as animation, it is > v2.A0
possible for drawing primitives to interfere with animation objects   > v2.A0
as they progress through their motion.  If a drawing primitive would  > v2.A0
"overlap" on top of an animation object, then that animation object   > v2.A0
is "undrawn" temporarily, the graphics primitive executed (eg, Line), > v2.A0
then the object is redrawn over the newly updated background image.   > v2.A0
This prevents inadvertant disruption of background imagery.  Care     > v2.A0
should be taken when drawing graphics at the same time as an          > v2.A0
animation is occuring, since the operation of undrawing the animation > v2.A0
object, performing the graphics primitive, and restoring the object   > v2.A0
can significantly slow down the animation/drawing process.            > v2.A0
                                                                      > v2.A0
An animation sequence pays attention to the graphics viewport         > v2.A1
active at the moment the animation sequence was defined.  In other    > v2.A0
words, if the viewport is changed in "mid stride" during an           > v2.A0
animation, it will not affect the animation at all.                   > v2.A0
                                                                      > v2.A0
It is entirely possible that during an animation sequence that a      > v2.A0
piece of RIPscrip code could place an image onto a clipboard page     > v2.A0
that is currently being used by an animation.  If this happens, the   > v2.A0
animation will begin using that image when that page is accessed next > v2.A0
in the sequence.                                                      > v2.A0

--------------------------------------------------------------------- > v2.A0
RIP_ANIMATION_CONTROL                                                 > v2.A0
--------------------------------------------------------------------- > v2.A0
         Function:  Controls animation sequences                      > v2.A0
            Level:  3                                                 > v2.A1
          Command:  a                                                 > v2.A0
        Arguments:  mode:1 res:3                                      > v2.A1
           Format:  !|3a <mode> <res>                                 > v2.A1
          Example:  !|3a3000                                          > v2.A1
  Uses Draw Color:  NO                                                > v2.A0
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO                                                > v2.A0
  Uses Line Thick:  NO                                                > v2.A0
  Uses Fill Color:  NO                                                > v2.A0
Uses Fill Pattern:  NO                                                > v2.A0
  Uses Write Mode:  NO                                                > v2.A0
  Uses Font Sizes:  NO                                                > v2.A0
    Uses Viewport:  NO                                                > v2.A0
                                                                      > v2.A0
This command allows you to control the actions of an animation        > v2.A1
currently active in the scene.  You may perform the                   > v2.A1
following control operations by setting the given value in the        > v2.A0
<modes> parameter:                                                    > v2.A0
                                                                      > v2.A0
     Modes     Description                                            > v2.A0
     ----------------------------------------------------------       > v2.A0
       0       Start Animation (begin animation sequence)             > v2.A0
       1       Terminate Animation (stop animation and clear)         > v2.A0
       2       Pause Animation - The animation sequence is            > v2.A1
               paused, its objects left on the screen.                > v2.A1
               The pause is indefinite                                > v2.A0
       3       Suspend Animation - The animation sequence is          > v2.A1
               undrawn and the animation paused.  The pause           > v2.A0
               is indefinite.  This is exactly like mode 2,           > v2.A0
               except the animation images are removed from           > v2.A0
               the screen                                             > v2.A0
       4       Resume Animation - The animation sequence is           > v2.A1
               resumed.  This resumes animation that was              > v2.A0
               paused by a mode 2 or 3 command.                       > v2.A0
       5       Refresh Animation - The animation sequence is          > v2.A1
               redrawn and any new frames (if any) are updated.       > v2.A0
               This command is intended if something obliterates      > v2.A0
               the screen and you want to clean things up.            > v2.A0
       6       Reset animation back to the beginning and start        > v2.A1






=====================================================================
==                          LEVEL-9 COMMANDS                       ==
=====================================================================

---------------------------------------------------------------------
RIP_ENTER_BLOCK_MODE
---------------------------------------------------------------------
         Function:  Enter block transfer mode with host
            Level:  9 (system command)
          Command:  <escape>
        Arguments:  mode:1 proto:1 file_type:2 res:4
                    [filename:2] <>
           Format:  !|9<escape> <proto> <file_type> <res>
                    [filename] <>
          Example:  !|9<escape>00010000ICONFILE.BMP<>                 > v2.A1
  Uses Draw Color:  NO
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO
  Uses Line Thick:  NO
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  NO
  Uses Font Sizes:  NO
    Uses Viewport:  NO                                                > v1.54

NOTE:  <escape> is used to indicate the Escape character
       (ASCII 27 or ESC).

This command is used to auto-initiate any desired File Transfer
Protocol.  The <filename> parameter is optional on downloads,
required for uploads, and if omitted must be replaced with a <>
parameter (end of string).

The <mode> parameter is to specify upload or download.  Use "1" for
upload mode, or "0" (zero) for download mode.  A filename is required
for uploads.  If the user has Data Security enabled on the terminal,
they are prompted to OK the upload before it proceeds.  If the user
does not authorize the upload, ten <Ctrl-X>'s (ASCII 24 or CAN) are
sent at one-tenth second intervals.  The <file_type> parameter is
ignored for uploads.

The <proto> parameter is the file transfer protocol specifier.
Possible values, and the protocols they refer to are:

    Value   Protocol            Filename Required?
    ----------------------------------------------
      0     Xmodem (checksum)          Yes
      1     Xmodem (CRC)               Yes
      2     Xmodem-1K                  Yes
      3     Xmodem-1K (G)              Yes
      4     Kermit                     Yes
      5     Ymodem (batch)             No
      6     Ymodem-G                   No
      7     Zmodem (crash recovery)    No
      8     Zmodem (no crash recovery) No                             > v2.A0


The <file_type> parameter determines what type of files are to be
received during the block transfer.  These are the valid parameters:


    Value   Description of Block Transfer Contents
    ---------------------------------------------------------------
      0     RIP file sequence (display it)
      1     Generic file sequence (store files for future use)        > v2.A0
      2     BMP file sequence (store them in proper directories)      > v2.A1
      3     Image file sequence (display it)                          > v2.A0
      4     COMPOSITE DYNAMIC file sequence (batch protocols only)
      5     ACTIVE DYNAMIC file sequence (batch protocols only)

Whether the <filename> is specified or not, this command must have a
"<>" sequence after the filename (even if there is none).  Here are
examples of how it would look with and without a filename:

With a filename, using X-Modem/CRC:

     !|9<escape>01010000filename.icn<>

Without a filename, using Z-Modem

     !|9<escape>06040000<>

A File Type of 0 is intended for RIP files.  The received RIP file is > v2.A0
placed in the appropriate Host System directory and is played back    > v2.A0
like any other Local RIP file.  This gives you the ability to         > v2.A0
transmit a RIP scene and play it back without having to send two      > v2.A0
different commands.                                                   > v2.A0
                                                                      > v2.A0
A File Type of 1 is intended for generic files.  The files are placed > v2.A0
in the appropriate Host System directory and are left there for       > v2.A0
future use.  No processing is performed on any file(s) received.      > v2.A0
                                                                      > v2.A0
A File Type of 2 is identical in nature to File Type 1.  It is        > v2.A0
designated for Icon Files only (.BMP, .HIC and .MSK).  You should use > v2.A1
the Generic Mode 1 instead of this mode as they are identical and in  > v2.A0
future revisions, this File Type (2) might change.                    > v2.A0
                                                                      > v2.A0
A File Type of 3 is intended for various types of received bitmap     > v2.A0
images.  These image files (JPEG) are controlled with the             > v2.A1
RIP_IMAGE_STYLE command, which must be set prior to the image         > v2.A0
being received.  When the image file is received, it is displayed     > v2.A0
according to the given Image Mode settings.  If no previous image     > v2.A0
settings were received, the image is displayed at the full size of    > v2.A0
the current graphics viewport.  JPEG files have a file extension of   > v2.A0
.JPG.                                                                 > v2.A1
                                                                      > v2.A0
A File Type of 4 is for COMPOSITE DYNAMIC mode.  This is only useful  > v2.A0
for Batch File Transfers (ie, Zmodem and Ymodem).  When files are     > v2.A0
received by this mode, they are processed separately depending on the > v2.A0
files' extensions.  In this mode, the file(s) are simply stored in    > v2.A0
the proper location.  No further processing is done on the files      > v2.A0
after this point.  The recognized file extensions are:                > v2.A0
                                                                      > v2.A0
     RIP ... Store the RIP file locally in the proper directory       > v2.A0
     BMP ... Place icon in proper directory                           > v2.A1
     HIC ... Place hot icon in proper directory                       > v2.A0
     MSK ... Place mask icon in proper directory                      > v2.A0
     JPG ... Store and JPEG file in proper directory                  > v2.A0
                                                                      > v2.A0

A File Type of 5 is for ACTIVE DYNAMIC mode.  This is only useful for > v2.A0
Batch File Transfers (ie, Zmodem and Ymodem).  When files are         > v2.A0
received by this mode, they are processed separately depending on the > v2.A0
files' extensions.  Files received while in this mode are stored in   > v2.A0
their proper locations and then extra processing (if any) is done on  > v2.A0
the file based on file extension.  The recognized file extensions     > v2.A0
are:                                                                  > v2.A0
                                                                      > v2.A0
     RIP ... Store and playback RIP file locally                      > v2.A0
     BMP ... Place icon in proper directory                           > v2.A1
     HIC ... Place hot icon in proper directory                       > v2.A0
     MSK ... Place mask icon in proper directory                      > v2.A0
     JPG ... Store and display JPEG file based on image settings      > v2.A0
                                                                      > v2.A0
If you receive file(s) with extensions other than the ones listed     > v2.A0
above, then no processing will be done on the files other than        > v2.A0
placing them in the appropriate Host Directory.                       > v2.A0

NOTE:  This command must be terminated with a carriage return.
       A vertical bar (|) command delimiter cannot be used to
       separate this command from a subsequent one on the same
       line.  In other words, this command must be the last
       command on a line of text.  The protocol must begin on
       the very next line.




--------------------------------------------------------------------- > v2.A1
RIP_BEGIN_UUENCODE_BLOCK                                              > v2.A1
--------------------------------------------------------------------- > v2.A1
         Function:  Begin a generic UU-Encoded data block             > v2.A1
            Level:  9                                                 > v2.A1
          Command:  U                                                 > v2.A1
        Arguments:  file_type:2 res:8                                 > v2.A1
           Format:  !|9U <file_type> <res>                            > v2.A1
          Example:  !|9U0200000000                                    > v2.A1
  Uses Draw Color:  NO                                                > v2.A1
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO                                                > v2.A1
  Uses Line Thick:  NO                                                > v2.A1
  Uses Fill Color:  NO                                                > v2.A1
Uses Fill Pattern:  NO                                                > v2.A1
  Uses Write Mode:  NO                                                > v2.A1
  Uses Font Sizes:  NO                                                > v2.A1
    Uses Viewport:  NO                                                > v2.A1
                                                                      > v2.A1
This command must be the last RIPscrip command on the line of text.   > v2.A1
The very next line of text will be the beginning (header) information > v2.A1
of a UU-encoded data file block.  In this header is contained the     > v2.A1
filename associated with the binary UU-encoded data.  This            > v2.A1
information is decoded by the receiving terminal and the resulting    > v2.A1
filename is stored on the terminal's hard disk to be processed        > v2.A1
depending on the <file_type> parameter.  The <file_type> parameter is > v2.A1
identical in nature and values to the parameter by the same name in   > v2.A1
the RIP_ENTER_BLOCK_MODE command.  The file that results from the     > v2.A1
UU-Encoded data block might be a JPEG file, BMP file, sound file, or  > v2.A1
could be just about anything.                                         > v2.A1
                                                                      > v2.A1
Immediately after the last line of UU-Encoded data, either raw text   > v2.A1
or RIPscrip code should begin.  Some UU-Encoded data blocks have      > v2.A1
line-by-line CRC checking.  If this mode is specified in the header   > v2.A1
of the UU-encoded data block, then CRC checking on the lines should   > v2.A1
be performed as defined in the UU-Encoding specification.  If a       > v2.A1
single CRC fails, the terminal should kill the partial file and       > v2.A1
ignore remaining UU-Encoded data until a RIPscrip or raw text block   > v2.A1
is encountered that it can then subsequently process.                 > v2.A1






--------------------------------------------------------------------- > v2.A0
RIP_DISPLAY_RIF_IMAGE                                                 > v2.A0
--------------------------------------------------------------------- > v2.A0
         Function:  Begin RIF streamable image block                  > v2.A0
            Level:  9 (system command)                                > v2.A0
          Command:  I                                                 > v2.A0
        Arguments:  <none>                                            > v2.A0
           Format:  !|9I                                              > v2.A0
          Example:  !|9I                                              > v2.A0
  Uses Draw Color:  NO                                                > v2.A0
  Uses Back Color:  NO                                                > v2.A1
Uses Line Pattern:  NO                                                > v2.A0
  Uses Line Thick:  NO                                                > v2.A0
  Uses Fill Color:  NO                                                > v2.A0
Uses Fill Pattern:  NO                                                > v2.A0
  Uses Write Mode:  NO                                                > v2.A0
  Uses Font Sizes:  NO                                                > v2.A0
    Uses Viewport:  YES                                               > v2.A0
                                                                      > v2.A0
This command is unlike any other command in the RIPscrip protocol. It > v2.A0
sets up the terminal into receive RIF image data mode.  RIF stands    > v2.A0
for "RIPscrip Image Format".  This is a highly compressed bitmap      > v2.A0
image stored in a printable ASCII format.  The compressed image data  > v2.A0
is variable length and can be quite lengthy.  The actual raw image    > v2.A0
data will be received after this command is received.                 > v2.A0
                                                                      > v2.A0
A carriage return should follow this command, thus meaning that this  > v2.A0
must be the last command on a line of text.  Raw RIF image data will  > v2.A0
be streamed across the connection after this command.  Location of    > v2.A0
the displayed image will be specified in a RIF sub-header which will  > v2.A0
be the first pieces of information received in the RIF block.  Many   > v2.A0
things can appear in the header including:                            > v2.A0
                                                                      > v2.A0
     1) Location of image window on the viewport                      > v2.A0
     2) Invisible color(s) in the image - transparent colors          > v2.A0
     3) Color Mapping information (on-the-fly color translation)      > v2.A0
     4) Width & Height of image                                       > v2.A0
     5) Foreground color and background color                         > v2.A0
     6) Total number of colors in image                               > v2.A0
                                                                      > v2.A0
Processing of a RIF image block will terminate when one of two things > v2.A0
occur:                                                                > v2.A0
                                                                      > v2.A0
     1) An error occurs during processing - this could occur          > v2.A0
        if line noise or a corrupted RIF image is transmitted         > v2.A0
     2) An exclamation mark is received.  This is the "end of RIF"    > v2.A0
        marker.  This exclamation mark is not considered part of a    > v2.A0
        RIPscrip sequence.                                            > v2.A0
                                                                      > v2.A0
In the case of an error in processing, all remaining RIF code is      > v2.A0
"gobbled up" and discarded until the "end of RIF" sequence is         > v2.A0
detected.  This is to prevent unwanted garbage data from appearing in > v2.A0
the text window.                                                      > v2.A0
                                                                      > v2.A0
For detailed information on the RIF file format specification, see    > v2.A0
the end of this document under the section "RIF FILE FORMAT".         > v2.A0
                                                                      > v2.A0
The image data received by this command is displayed graphically as   > v2.A0
it is received.  No data is stored locally on the terminal's hard     > v2.A0
disk, so in effect this format is very efficient in that it doesn't   > v2.A0
require any temporary files or alternative storage other than         > v2.A0
decompression tables internally in memory.                            > v2.A0




=====================================================================
==          HOST COMMANDS - A TUTORIAL & REFERENCE SECTION         ==
=====================================================================

With Mouse regions, Buttons and Text Variable Query ability, you can
control the Terminal/Paint programs and how they react with the BBS
in many ways.  To accomplish this, there are several features of
RIPscrip that permit you to do special actions based on different
circumstances.  In effect, an "action language" of sorts.  The
following sections go into the available "action language" features
in more detail.

Among the various abilities are:

     1. Control-Character specification
     2. Pre-defined Text Variables & User-defined text variables
     3. Pop-up pick-lists
     4. A Host Command "Template" system for added intelligence.
     5. Query text variable contents (pre-defined & user variables)
     6. Text variable form generation for complex queries             > v2.A1





=====================================================================
==                        CONTROL CHARACTERS                       ==
=====================================================================

Not all BBS'es will allow you to use control characters on their
Service.  Regardless of that, the capability to send any Control
Character exists for your Host Commands.  The most commonly used
Control Characters are:

   INDIVIDUAL CONTROL CHARACTERS         SPECIAL KEYSTROKES
   ===========================================================
   ^@ ... Null (ASCII 0)                 ^[[A ... Up Arrow
   ^G ... Beep                           ^[[B ... Down Arrow
   ^L ... Clear Screen (Top of Form)     ^[[C ... Right Arrow
   ^M ... Carriage Return                ^[[D ... Left Arrow
   ^C ... Break (sometimes)              ^[[H ... Home Key
   ^H ... Backspace                      ^[[K ... End Key
   ^[ ... Escape character               ^[[L ... Control Home
   ^S ... Pause data transmission
   ^Q ... Resume data transmission

Some hosts use the ^ (caret) for their own purposes.  In these
cases, you can use the ` (backquote) character instead of the
caret.  Some systems allow you to specify the caret symbol as
two carets (^^).  Consult your Host Software documentation to
determine the best method for your needs.

NOTE:  RIPterm uses ^ or ` and a character to represent a control
       character.  IT IS NOT A CONTROL CHARACTER BY ITSELF, IT
       IS TRANSLATED BY RIPterm.  In other words, ^M does not send
       a ^ and then an M, it sends a carriage return (ASCII 13).
       Likewise, RIPscrip commands like Query do not use an ^[, an
       actual escape character (ASCII 27) is used.




=====================================================================
==                          TEXT VARIABLES                         ==
=====================================================================

A special feature of RIPterm allows it to understand what a Text
Variable is.  A text variable is a piece of text that both RIPaint
and RIPterm know something about.  For example, the Text Variable
$DATE$ is known to represent the current Date on your PC.  The host
may ask your system what the values of one or more of these variables
are, and if your terminal knows these particular Text Variables, it
will tell the host.

There are three types of Text Variables.

-- Built-In Text Variables that RIPscrip products will ALWAYS
   know about.  These include Text Variables like date and time
   that return a value

-- Another type of built-in Text Variables are Active Text
   Variables, which perform an action, but return nothing to
   the host.  These include turning the status bar on/off,
   clearing the graphics screen, and playing some simple
   sounds, and many more.  These variables are a very powerful
   aspect of RIPscrip, providing mechanisms for doing dialog          > v2.A1
   boxes and interactive GUI applications.                            > v2.A1

-- Then there are also User Text Variables that can contain
   a variety of information depending on what the user
   entered at the time the variable was created.  For
   example, the host might ask you what the contents of the
   $FULL_NAME$ variable is, and if RIPterm doesn't know, it
   could pop-up a field on the screen and ask you about it.
   From then on, RIPterm will remember that piece of
   information for the next time it is needed by a host.

You may use either the pre-defined Text Variables, or the User Text
Variables at any place that allows Text Variables.

Some built-in text variables have been extended in RIPscrip 2.0 to    > v2.A1
allow for parameters.  This extends text variables functionality in   > v2.A1
many ways.  If a text variable has a parameter, it is enclosed in     > v2.A1
paranthesis immediately after the text variable name as in the        > v2.A1
following example:                                                    > v2.A1
                                                                      > v2.A1
          $SAVE(8)$                                                   > v2.A1
                                                                      > v2.A1
This would be basically identical in nature to the older $SAVE8$ text > v2.A1
variable which saves the screen to the eighth slot.  The new method   > v2.A1
is more universal in design than having separate text variables for   > v2.A1
basically identical operations.  The older forms of these commands    > v2.A1
will remain in the specification but their use is not recommended     > v2.A1
because the new method is far superior.                               > v2.A1
                                                                      > v2.A1
Any text variables which take parameters don't necessarily need them. > v2.A1
In any case, these text variables will have their parameters          > v2.A1
described in the appropiate sections below.                           > v2.A1
                                                                      > v2.A1
If a variable takes more than one parameter, then they are separated  > v2.A1
by commas between the paranthesis (eg, $PCB(0,1)$).                   > v2.A1




===================================================================== > v2.A1
==               SAVE/RESTORE TEXT VARIABLES:  SLOTS               == > v2.A1
===================================================================== > v2.A1
                                                                      > v2.A1
Some of the active text variables defined in the next section are     > v2.A1
save/restore type actions.  All of these actions adhere to a          > v2.A1
fundamental system of storage organized around slots and slot-less    > v2.A1
save areas.                                                           > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
SLOT SAVE AREAS                                                       > v2.A1
---------------                                                       > v2.A1
A slot in the context of saving and restoring things allows you to    > v2.A1
save/restore many different things to various slots.  There are ten   > v2.A1
different slots (0-9) for each type of information and each slot can  > v2.A1
contain a complete saved data item (ie, clipboard, full screen        > v2.A1
graphics, text window definition, etc).                               > v2.A1
                                                                      > v2.A1
When something is saved to a slot, that information is saved until a  > v2.A1
corresponding restore operation accesses that slot again.  Once a     > v2.A1
restore operation is done on a slot, that slot is cleared for future  > v2.A1
use.  This means that if you save something to a slot, you can only   > v2.A1
restore that piece of information once.                               > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
SLOT-LESS SAVE AREA                                                   > v2.A1
-------------------                                                   > v2.A1
In addition to the ten slots, there is another area reserved for      > v2.A1
saved information.  It is called a slot-less area.  Slot-less areas   > v2.A1
have no slot number because they're not part of the slot system.      > v2.A1
                                                                      > v2.A1
The slot-less save area is different though.  When something is saved > v2.A1
to a slot-less area, it overwrites whatever is already there (if      > v2.A1
anything).  When it is restored, that slot is not cleared.  This      > v2.A1
means that you can restore the same thing many times if you wish.     > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
STACK SAVING - PUSH SAVING AND POP RESTORING                          > v2.A1
--------------------------------------------                          > v2.A1
Now that we have the slot and slot-less save areas understood, we     > v2.A1
introduce another concept that builds upon the slot system.  This is  > v2.A1
the concept of a stack.  Stacks use the slot system with operations   > v2.A1
called push and pop.  Pushing onto the stack is a form of saving and  > v2.A1
popping from the stack is a form of restoring.                        > v2.A1
                                                                      > v2.A1
When you push (save) something, you store the information in a slot   > v2.A1
number.  The slot number that is actually used is unimportant to you, > v2.A1
the application designer.  The first time you push something, it will > v2.A1
occupy slot #0.  If you then push something new into the save area,   > v2.A1
it will go into slot #1.  You can push up to ten things at a time.    > v2.A1
                                                                      > v2.A1
After something has been pushed, you may perform pop operations which > v2.A1
restore things.  A pop will restore the last-most pushed item.  In    > v2.A1
our example, a pop will restore from slot #1.  A second pop will      > v2.A1
restore from slot #0.                                                 > v2.A1
                                                                      > v2.A1
Push and pop operations are vital to the concept of multiple          > v2.A1
overlapping windows and dialog boxes in RIPscrip.  When you close a   > v2.A1
window, you need to restore the background graphics, mouse regions,   > v2.A1
text windows and any clipboards that were in use at the time.  What   > v2.A1
if that restored background is itself a window that is on top of some > v2.A1
background menu?  That window would also have stuff pushed (the       > v2.A1
background environment).  When that window closes, it will pop the    > v2.A1
information and restore the background environment's configuration.   > v2.A1

Let's examine the flow of push/pop/slot-# relationships with a series > v2.A1
of pushes and pops mixed together:                                    > v2.A1
                                                                      > v2.A1
     Operation      Slot accessed   Next slot                         > v2.A1
     -----------------------------------------                        > v2.A1
       <start>            n/a           0                             > v2.A1
       Push                0            1                             > v2.A1
       Push                1            2                             > v2.A1
       Pop                 1            1                             > v2.A1
       Push                1            2                             > v2.A1
       Push                2            3                             > v2.A1
       Pop                 2            2                             > v2.A1
       Pop                 1            1                             > v2.A1
       Pop                 0            0                             > v2.A1
       Pop             ILLEGAL - NO PUSHES LEFT                       > v2.A1
                                                                      > v2.A1
There is nothing preventing you from directly accessing a slot number > v2.A1
when you've been doing pushes and pops.  This is not recommended for  > v2.A1
general practice.  If however you know that you have complete control > v2.A1
over the entire slot system you could directly access a slot number   > v2.A1
with a restore operation.  If you do this however, that would clear   > v2.A1
that slot and if there are more things saved in higher slot numbers   > v2.A1
and you do some pop operations, you might hit the blank slot and      > v2.A1
things would get out of sync (nothing to restore).  A valid use of    > v2.A1
direct slot access in a push/pop situation would be to save over a    > v2.A1
particular slot that's already been loaded with information from a    > v2.A1
prior push operation.                                                 > v2.A1




=====================================================================
==                    PRE-DEFINED TEXT VARIABLES                   ==
=====================================================================

$RIPVER$ ... RIPscrip version (e.g., "RIPSCRIP015300")
------------------------------------------------------
This Text Variable returns a phrase which will identify a
RIPscrip-compatible software package.  It is designed to be used by a
host to detect what version of RIPscrip graphics your terminal can
support as well as the type (brand) of RIPscrip terminal that is in
use.  When this Text Variable is used, it will respond back with
"RIPSCRIP" followed by the Version Number (e.g., "01.54"), followed   > v1.54
by two digits identifying the Vendor of the terminal.  The first      > v1.54
digit of the Vendor ID field is the Vendor Code (1=RIPterm).  The     > v1.54
second digit is the Vendor's sub-version code identifying sub-        > v1.54
versions of the software that still support the same RIPscrip         > v1.54
software version.  Valid Vendor Codes are:                            > v1.54
                                                                      > v1.54
     CODE   VENDOR                                                    > v1.54
     =================================================                > v1.54
       0    Generic RIPscrip terminal (vendor unknown)                > v1.54
       1    RIPterm (from TeleGrafix Communications)                  > v1.54
       2    Qmodem Pro (from Mustang Software, Inc)                   > v1.54
                                                                      > v1.54
See the section earlier in this document on ANSI sequences for a      > v1.54
more robust description of the Vendor Codes and Auto-Sensing.         > v1.54

     Example:  $RIPVER$
     Returns:  RIPSCRIP015300


$DATE$ ... Date in short format
-------------------------------
This Text Variable returns the current date. in the format MM/DD/YY.

     Example:  $DATE$
     Returns:  12/19/93



$MONTH$ ... Month Name
----------------------
This Text Variable returns the full name of the current month.  It is
not abbreviated (e.g., "November" instead of "Nov")

     Example:  $MONTH$
     Returns:  December



$MONTHNUM$ ... Month Number
---------------------------
This Text Variable returns the number of the current month.
January=01 and December=12.

     Example:  $MONTHNUM$
     Returns:  12




$DAY$ ... Day of Month Number
-----------------------------
This Text Variable returns the current day of the month.  Possible
values for this Variable are from 01-31.

     Example:  $DAY$
     Returns:  05



$DOY$ ... Day of year
---------------------
This Text Variable returns the number of days so far in the year.  A
year has 365 days (except leap years which have 366).  $DOY$ can
return 001 - 366.

     Example:  $DOY$
     Returns:  214



$YEAR$ ... 2 digit year
-----------------------
This Text Variable returns the two-digit number of the current year.

     Example:  $YEAR$
     Returns:  93



$FYEAR$ ... 4 digit year
------------------------
This Text Variable returns the four-digit number of the current year.

     Example:  $FYEAR$
     Returns:  1993



$TIME$ ... Time in standard format
----------------------------------
This Text Variable returns the time in military format (hours from 00
- 23).  The format is hours, minutes, and seconds separated by
colons.  HH:MM:SS

     Example:  $TIME$
     Returns:  18:09:33



$HOUR$ ... Hour (format HH) - normal style
------------------------------------------
This Text Variable returns the two digit number of the current hour.
This variable range from 01 - 12.  This does not use military format.

     Example:  $HOUR$
     Returns:  11




$MHOUR$ ... Hour (format HH) - military style
---------------------------------------------
This Text Variable returns a two-digit number of the current hour in
military format.  This variable may range from 00 - 23.

     Example:  $MHOUR$
     Returns:  17



$MIN$ ... Minutes
-----------------
This Text Variable returns the two-digit number representing the
current minutes in the hour.  Possible values for this variable are
00-59.

     Example:  $MIN$
     Returns:  45



$SEC$ ... Seconds
-----------------
This Text Variable returns a 2-digit number representing the current
seconds of the minute.  Possible values for this variable are 00-59.

     Example:  $SEC$
     Returns:  59



$AMPM$ ... Returns AM or PM depending on time
---------------------------------------------
This Text Variable returns a two-character value of either "AM" or
"PM" depending on what time it is.

     Example:  $AMPM$
     Returns:  PM



$DATETIME$ ... Date and Time
----------------------------
This Text Variable returns a combination date and time.  The format
is somewhat different than standard time/date notation.  It is:

     DAY-OF-WEEK   MONTH   DAY-OF-MONTH  HH:MM:SS  YEAR

     Example:  $DATETIME$
     Returns:  Sat Dec 19 14:38:50 1993

        NOTE:  This is the standard Unix date/time notation.



$TIMEZONE$ ... Time Zone or "NONE" if unknown
---------------------------------------------
This Text Variable returns a word/phrase that describes the time-zone
the terminal is in.  This may be returned as anything like "PST" for
Pacific Standard Time, "EST" for Eastern Standard Time, etc.  If the
time zone is not set on your PC, this variable will respond with NONE

     Example:  $TIMEZONE$
     Returns:  PST

$DOW$ ... Day of week fully spelled out
---------------------------------------
This Text Variable returns the current day of the week.  The name is
fully spelled out.  Possible values are: Sunday, Monday, Tuesday,
Wednesday, Thursday, Friday and Saturday.

     Example:  $DOW$
     Returns:  Saturday



$ADOW$ ... Abbreviated Day of Week
----------------------------------
This Text Variable returns the current day of the week in abbreviated
form.  Possible values are: Sun, Mon, Tue, Wed, Thu, Fri and Sat.

     Example:  $ADOW$
     Returns:  Mon



$WDAY$ ... Day of Week
----------------------
This Text Variable returns a one-digit number representing the day of
the week.  Possible values are 0-6, where 0=Sunday (the first day in
the week).

     Example:  $WDAY$
     Returns:  2

$WOY$ ... Week of current year 00-53; Sunday=1st Day of Week
------------------------------------------------------------
This Text Variable returns a number from 00-53, representing the week
in the year.  Even though there are 52 weeks in a year, a week might
not begin exactly on the first day of the year, so a maximum value
for this variable can be 53 under these circumstances.  For this
variable, Sunday is considered to be the first day of the week.

     Example:  $WOY$
     Returns:  32



$WOYM$ ... Week of current year 00-53; Monday=1st Day of Week
-------------------------------------------------------------
This Text Variable returns a number from 00-53, representing the week
in the current year.  Even though there are 52 weeks in a year, a
week might not begin exactly on the first day of the year, so a
maximum value for this variable can be 53 under these circumstances.
For this variable, Monday is considered to be the first day of the
week.

     Example:  $WOYM$
     Returns:  32




$BEEP(freq,length)$ ... Beep Sound (ala Ctrl-G)                       > v2.A1
-----------------------------------------------
This Active Text Variable beeps the terminal, producing a Ctrl-G
sound.  No parameters are required.  If none are provided then the    > v2.A1
frequency is assumed to be 1000 Hertz and the length of time that it  > v2.A1
should play is 75 milliseconds.                                       > v2.A1

The C source code to play this sound is:

          sound(freq);     // the Hertz frequency to play             > v2.A1
          delay(length);   // millisecond delay                       > v2.A1
          nosound();       // turn the sound off
          delay(75);       // millisecond delay

     Example:  $BEEP(1000,75)$ ... equivalent to $BEEP$               > v2.A1
     Returns:  nothing



$BLIP(freq,length)$ ... Blipping Sound (like a hitting a barrier)     > v2.A1
-----------------------------------------------------------------
This Active Text Variable is like $BEEP$, except the sound is
different.  It produces a barrier sound; like you're running into a
wall.

No parameters are required.  If none are provided then the            > v2.A1
frequency is assumed to be 50 Hertz and the length of time that it    > v2.A1
should play is 25 milliseconds.                                       > v2.A1

The C source code to play this sound is:

          sound(freq);     // the Hertz frequency to play             > v2.A1
          delay(length);   // millisecond delay                       > v2.A1
          nosound();       // turn the sound off
          delay(10);

     Example:  $BLIP(50,10)$ ... equivalent to $BLIP$                 > v2.A1
     Returns:  nothing




$MUSIC(count)$ ... Musical (cheerful) sound                           > v2.A1
-------------------------------------------
This Active Text Variable produces a cheerful sound, indicating
success of an action.  This sound is used for successful downloads
and dialed connections.

This command doesn't require any parameters.  If none are provided,   > v2.A1
then the count is assumed to be 4.  The count parameter determines    > v2.A1
how many times the musical sound is repeated.                         > v2.A1

The C source code to play this sound is:

     for (i=0 ; i<count; i+=1)                                        > v2.A1
     {
          sound(1300);   delay(10);     // Hertz frequency to play
          sound(1200);   delay(10);     // millisecond delay
          sound(1100);   delay(10);
          sound(1000);   delay(10);
          sound(900);    delay(10);
          sound(800);    delay(10);
          sound(700);    delay(10);
          sound(850);    delay(10);
          sound(950);    delay(10);
     }
     nosound();                         // turn the sound off


     Example:  $MUSIC(4)$ ... equivalent to $MUSIC$                   > v2.A1
     Returns:  nothing



$ALARM(count)$ ... Warning!  This sound indicates failure!            > v2.A1
----------------------------------------------------------
This Active Text Variable produces a warning sound, indicating
failure of an action.  This sound is used for aborted downloads.

This command doesn't require any parameters.  If none are specified,  > v2.A1
then the count is assumed to be 3.  The count parameter is the number > v2.A1
of times that the warning sound is repeated.                          > v2.A1

The C source code to play this sound is:

     for (i=0 ; i<count ; i+=1)                                       > v2.A1
     {
          sound(320);  delay(200);     // the Hertz frequency to play
          sound(160);  delay(425);     // millisecond delay
     }
     nosound();                        // turn the sound off


     Example:  $ALARM(3)$ ... equivalent to $ALARM$
     Returns:  nothing




$PHASER(start,stop,inc,time)$ ... Fire phasers!                       > v2.A1
------------------------------------------------
This Active Text Variable produces a sound like firing your energy
weapons in a game.  Now you too can blast away with the best of them.
Trivia question:  What does phaser stand for?  See $REVPHASERS$ for
the answers.

This command doesn't require any parameters.  If none are specified   > v2.A1
then the START is assumed to be 2500 Hertz.  STOP is assumed to be 50 > v2.A1
Hertz, INC is assumed to be 20 Hertz increments and TIME is assumed   > v2.A1
to be 2 milliseconds.  START must be greater than STOP and INC must   > v2.A1
be greater than zero.  If none of these conditions are met then the   > v2.A1
defaults are used for the sound effect.                               > v2.A1

The C source code to play this sound is:

     for (i=start ; i>=stop ; i-=inc)                                 > v2.A1
     {
          sound(i);               // the Hertz frequency to play
          delay(time);            // millisecond delay                > v2.A1
     }
     nosound();                   // turn the sound off


     Example:  $PHASER(2500,50,20,2)$ ... equivalent to $PHASER$
     Returns:  nothing



$REVPHASER(start,stop,inc.time)$ ... Fire phasers!                    > v2.A1
--------------------------------------------------
This Active Text Variable produces a sound like firing your energy
weapons in a game.  Like $PHASER$ makes an ascending tone,
$REVPHASER$ makes a descending tone.  Answer to trivia question in
$PHASER$: Phaser stands for PHoton Amplification by Stimulated
Emission of Radiation.  Sound familiar?  Laser is Light Amplification
by Stimulated Emission of Radiation, and Maser is Microwave
Amplification by Stimulated Emission of Radiation.

This command doesn't require any parameters.  If none are specified   > v2.A1
then the START is assumed to be 50 Hertz.  STOP is assumed to be 2500 > v2.A1
Hertz, INC is assumed to be 20 Hertz increments and TIME is assumed   > v2.A1
to be 2 milliseconds.  START must be greater than STOP and INC must   > v2.A1
be greater than zero.  If none of these conditions are met then the   > v2.A1
defaults are used for the sound effect.                               > v2.A1

The C source code to play this sound is:

          for (i=start ; i<=stop ; i+=inc)                            > v2.A1
          {
               sound(i);               // the Hertz frequency to play
               delay(time);            // millisecond delay           > v2.A1
          }
          nosound();                   // turn the sound off

     Example:  $REVPHASER(50,2500,20,2)$ ... Same as $REVPHASER$      > v2.A1
     Returns:  nothing




$X(type)$ ... X Mouse location                                        > v2.A1
------------------------------
This Text Variable returns the current X coordinate of the mouse
pointer.  This can be used interactively (for example, by on-line
games) to determine the location of the mouse pointer.  Only the X
value of the mouse (X,Y) is returned.  The value is 0000-9999
depending on what the current position is.

The results are in current world coordinates if no parameter is       > v2.A1
specified.  If the TYPE parameter is equal to "VIEW" then the         > v2.A1
return value is in viewport coordinates.  If TYPE is "VIDEO" then the > v2.A1
result is in raw video device coordinates.  If TYPE is "WORLD" then   > v2.A1
the result is in desktop world coordinates.                           > v2.A1

     Example:  $X(WORLD)$ ... equivalent to $X$                       > v2.A1
     Returns:  0523



$Y(type)$ ... Y Mouse location                                        > v2.A1
------------------------------
This Text Variable returns the current Y coordinate of the mouse
pointer.  This can be used interactively (for example, by on-line
games) to determine the location of the mouse pointer.  Only the Y
value of the Mouse (X,Y) is returned.  The value is 0000-9999
depending on what the current position is.

The results are in current world coordinates if no parameter is       > v2.A1
specified.  If the TYPE parameter is equal to "VIEW" then the         > v2.A1
return value is in viewport coordinates.  If TYPE is "VIDEO" then the > v2.A1
result is in raw video device coordinates.  If TYPE is "WORLD" then   > v2.A1
the result is in desktop world coordinates.                           > v2.A1

     Example:  $Y(WORLD)$ ... equivalent to $Y$                       > v2.A1
     Returns:  0244



$XY(type)$ ... X/Y Mouse Location                                     > v2.A1
---------------------------------
This Text Variable returns both the X and Y coordinates of the mouse
pointer.  A colon (:) separates the two values.  The X and Y values
may range from 0000-9999.  The format that this value uses is:
XXXX:YYYY

The results are in current world coordinates if no parameter is       > v2.A1
specified.  If the TYPE parameter is equal to "VIEW" then the         > v2.A1
return value is in viewport coordinates.  If TYPE is "VIDEO" then the > v2.A1
result is in raw video device coordinates.  If TYPE is "WORLD" then   > v2.A1
the result is in desktop world coordinates.                           > v2.A1

     Example:  $XY(WORLD)$ ... equivalent to $XY$                     > v2.A1
     Returns:  0297:0321




$XYM(type)$ ... X, Y & button status                                  > v2.A1
------------------------------------
This Text Variable returns the X and Y coordinates of the mouse
pointer, and which mouse buttons are pressed (if any).  A colon (:)
separates the three values.  The X and Y values may range from
0000-9999.  LMR stands for Left/Middle/Right.  If any of these
buttons are depressed (clicked), then the corresponding position will
contain a 1.  If a button is NOT depressed, then it will contain a
0.  The format that this value uses is:  XXXX:YYYY:LMR

This means that the (X,Y) location of the cursor is (0123,0297), and
that the Left and Middle buttons are depressed, but that the Right
Mouse Button is not depressed.

The results are in current world coordinates if no parameter is       > v2.A1
specified.  If the TYPE parameter is equal to "VIEW" then the         > v2.A1
return value is in viewport coordinates.  If TYPE is "VIDEO" then the > v2.A1
result is in raw video device coordinates.  If TYPE is "WORLD" then   > v2.A1
the result is in desktop world coordinates.                           > v2.A1

     Example:  $XYM(WORLD)$ ... Equivalent to $XYM$                   > v2.A1
     Returns:  0123:0297:110



$M$ ... Mouse Button Status: LMR
--------------------------------
This Text Variable returns a 3-character code representing the status
of each mouse button.  This variable works with two button and three
button mice.  The format of the code is LMR where L=Left, M=Middle
(if any), and R=Right.  If any button is clicked, the code for that
button is "1".  If the button is not depressed, it is "0".  "100"
would mean the left mouse button is depressed, but none of the others
are.

     Example:  $M$
     Returns:  001



$MSTAT$ ... Mouse Status
------------------------
This Text Variable returns a "YES" if there is a mouse installed on
the RIPterm computer.  If no mouse is installed, this variable
returns "NO".

     Example:  $MSTAT$
     Returns:  YES



$RESET$ ... Performs RIP_RESET_WINDOWS (Identical to !|*)
---------------------------------------------------------
This Active Text Variable resets and clears the graphics screen,
resets the text window to full screen and clears it, resets the color
palette, deletes all mouse fields, and clears the clipboard.

     Example:  $RESET$
     Returns:  nothing




$SAVEALL(slot)$ ... Save all screen attributes                        > v2.A1
----------------------------------------------
This Active Text Variable saves the Text Windows coordinates, save
the contents of the clipboard, saves all mouse fields, and saves the
contents of the entire screen.  It is the same as doing a
"$STW(slot)$ $SCB(slot)$ $SMF(slot)$ $SAVE(slot)$".                   > v2.A1

This command does not require any parameters.  If none are specified  > v2.A1
then the saved information is slot-less and can be restored many      > v2.A1
times.  If you specify a slot number than that slot number is the     > v2.A1
slot that will be saved over.  You are allowed up to ten separate     > v2.A1
slots (0-9).                                                          > v2.A1
                                                                      > v2.A1
In place of a slot number, you can provide a parameter of "PUSH" to   > v2.A1
perform a push-type stack saving operation (eg, $SAVEALL(PUSH)$).     > v2.A1

     Example:  $SAVEALL(0)$                                           > v2.A1
     Returns:  nothing



$RESTOREALL(slot)$ ... Restore all screen attributes                  > v2.A1
----------------------------------------------------
This Active Text Variable restores the Text Windows coordinates,
restores the contents of the clipboard, restores all mouse fields,
and restores the contents of the screen.  It is equal to
"$RTW(slot)$ $RCB(slot)$ $RMF(slot)$ $RESTORE(slot)$".                > v2.A1

This command does not require any parameters.  If none are specified  > v2.A1
then the restore is slot-less and can be restored many times.  The    > v2.A1
ability to specify a slot gives you the ability to have restore one   > v2.A1
of many screen configurations.  You are allowed up to ten separate    > v2.A1
slots (0-9).                                                          > v2.A1
                                                                      > v2.A1
In place of a slot number, you can provide a parameter of "POP" to    > v2.A1
perform a stack-based pop operation to restore the last pushed        > v2.A1
SAVEALL (eg, $RESTOREALL(POP)$).                                      > v2.A1

     Example:  $RESTOREALL(0)$                                        > v2.A1
     Returns:  nothing



$SAVEx$ ... Save graphics screen                                      > v2.A1
--------------------------------
If you choose the SAVE0 through SAVE9 variations, the filename that
is saved to files RIPTERM0.SAV through RIPTERM9.SAV, allowing you to
have multiple screens saved simultaneously.

In addition to the Graphical data that is currently on-screen, the    > v1.54
current Graphical Viewport settings are saved as well so that when a  > v1.54
restore is done, the viewport will be properly restored as well.      > v1.54

If you wish to save the entire state of the RIPterm system, use
$SAVEALL$.

NOTE:  This method of saving graphical screens is obsolete.  Use      > v2.A1
       the $SAVE$ function (see below) with a parameter.              > v2.A1

     Example:  $SAVE7$
     Returns:  nothing




$SAVE(slot)$ ... Save graphics screen                                 > v2.A1
-------------------------------------
If no slot parameter is specified, then this command will save the    > v2.A1
contents of the entire graphics screen to a disk file called          > v2.A1
RIPTERM.SAV.  No mouse fields, text window locations or clipboard     > v2.A1
data is saved - just the graphics screen.                             > v2.A1
                                                                      > v2.A1
If you specify a slot parameter then that identifies a specific       > v2.A1
screen slot to overwrite (0-9).  The files that the screen is stored  > v2.A1
to are RIPTERM0.SAV through RIPTERM9.SAV allowing you up to ten       > v2.A1
separate screen slots saved simultaneously.                           > v2.A1
                                                                      > v2.A1
If you specify "PUSH" instead of a slot number then a stack-based     > v2.A1
save operation will be performed (eg, $SAVE(PUSH)$).                  > v2.A1

In addition to the Graphical data that is currently on-screen, the    > v1.54
current Graphical Viewport settings are saved as well so that when a  > v1.54
restore is done, the viewport will be properly restored as well.      > v1.54

If you wish to save the entire state of the RIPterm system, use
$SAVEALL$.

This command also saves the graphical style slots, button style slots > v2.A1
and any previously defined animation definition (not the clipboard    > v2.A1
cells of the animation though).                                       > v2.A1

     Example:  $SAVE(7)$
     Returns:  nothing



$RESTOREx$ ... Restore graphics screen                                > v2.A1
--------------------------------------
The RESTORE0 through RESTORE9 screen restore variations use a         > v2.A1
filename of RIPTERM0.SAV through RIPTERM9.SAV allowing you to         > v2.A1
restore from up to ten different saved files.  The disk file          > v2.A1
associated with the screen is deleted upon restoration.               > v2.A1

When the graphics screen is restored, the Graphics Viewport settings  > v1.54
that were in effect when the screen was saved will be restored as     > v1.54
well.                                                                 > v1.54

To restore the entire context of the graphics environment $RESTALL$.

This command also restores the graphical style slots, button slots    > v2.A1
and any previously defined animation (not the clipboard pages of the  > v2.A1
animation though).                                                    > v2.A1
                                                                      > v2.A1
NOTE:  This method of restoring graphical screens is obsolete.  Use   > v2.A1
       the $RESTORE$ function (see below) with a parameter.           > v2.A1

     Example:  $RESTORE3$
     Returns:  nothing




$RESTORE(slot)$ ... Restore graphics screen                           > v2.A1
-------------------------------------------
If no slot parameter is specified, then the graphical screen stored   > v2.A1
in the file RIPTERM.SAV will be restored to the screen (the file will > v2.A1
not be deleted).                                                      > v2.A1
                                                                      > v2.A1
If you specify a slot number (0-9), then the file restored to the     > v2.A1
screen will be RIPTERM0.SAV through RIPTERM9.SAV based on the slot    > v2.A1
number.  These files are deleted after restoration is complete.       > v2.A1
                                                                      > v2.A1
If you specify "POP" instead of a slot number then a stack-based pop  > v2.A1
operation will be performed (eg, $RESTORE(POP)$).                     > v2.A1

Only the graphics screen is restored, not the Clipboard, Mouse Fields
or Text Window settings.

When the graphics screen is restored, the Graphics Viewport settings  > v1.54
that were in effect when the screen was saved will be restored as     > v1.54
well.                                                                 > v1.54

To restore the entire context of the graphics environment $RESTALL$.

     Example:  $RESTORE(3)$
     Returns:  nothing



$SMF(slot)$ ... Save Mouse Fields                                     > v2.A1
---------------------------------
This Active Text Variable saves all defined Mouse Fields and Mouse
Buttons to a temporary file for later retrieval.  This is designed
especially for the graphical designer who wishes to pop-up a dialog
box on the screen with one or more mouse fields, and when finished,
to restore the screen and original mouse fields.  This command is
intended to be used with the Restore Mouse Fields text variable
$RMF$.

If no slot parameter is specified then the mouse field definitions    > v2.A1
will be stored to a non-slot specific file (similar to $SAVE$ with no > v2.A1
parameter).  This file can be restored multiple times.  If you        > v2.A1
specify a slot, then the fields are stored to slot-specific files.    > v2.A1
When a saved mouse field definition in a particular slot is restored, > v2.A1
the corresponding file is automatically deleted upon restoration.     > v2.A1
                                                                      > v2.A1
If you specify a slot number of "PUSH" then you will be performing a  > v2.A1
stack-based push operation (eg, $SMF(PUSH)$).                         > v2.A1

     Example:  $SMF(4)$
     Returns:  nothing




$RMF(slot)$ ... Restore Mouse Fields                                  > v2.A1
------------------------------------
This Active Text Variable restores any Mouse Fields saved with $SMF$.
You may have only one set of mouse fields saved at once.  If no mouse
fields were saved, or if the number of fields saved is 0, then no
mouse fields are  active.

If no slot parameter is specified, then the non-slot specific mouse   > v2.A1
fields saved with a $SMF$ command is restored (the saved mouse field  > v2.A1
file is not deleted).  If a slot parameter is specified then the      > v2.A1
mouse fields saved with $SMF(slot)$ is restored then the disk file is > v2.A1
deleted.                                                              > v2.A1
                                                                      > v2.A1
If you specify a slot number of "POP" then you will be performing a   > v2.A1
stack-based pop operation (eg, $RMF(POP)$).                           > v2.A1
                                                                      > v2.A1
NOTE:  You may restore slot-less saved Mouse Fields more than once    > v2.A1
       is you wish.  In other words, if you do a $SMF$ command, you   > v2.A1
       may execute $RMF$ one or more times.  But if you do a $SMF(1)$ > v2.A1
       you may only do a $RMF(1)$ once.                               > v2.A1

     Example:  $RMF(4)$
     Returns:  nothing



$STW(slot)$ ... Save Text Window information                          > v2.A1
--------------------------------------------
If no slot parameter is specified, then this command stores all       > v2.A1
currently defined text windows' settings.  The windows' X/Y           > v2.A1
dimensions are preserved, as are the current cursor location, ANSI    > v2.A1
attributes, cursor ON/OFF status and the vertical scrolling margins.  > v2.A1
Even the current System Fonts used for all windows are saved (if      > v2.A1
necessary).                                                           > v2.A1
                                                                      > v2.A1
If you specify a slot parameter, then you are specifying to save the  > v2.A1
text window definitions to one of up to ten different slots (0-9).    > v2.A1
These allow you to have up to ten different text window               > v2.A1
configurations saved at the same time.  If you save to a slot then    > v2.A1
when you restore that slot the saved definitions are deleted from the > v2.A1
disk.  If you don't specify a slot parameter (a slot-less save) then  > v2.A1
you can restore that definition file multiple times without the file  > v2.A1
being deleted.                                                        > v2.A1
                                                                      > v2.A1
If you specify a slot number of "PUSH" then you are performing a      > v2.A1
stack-based save operation (eg, $STW(PUSH)$).                         > v2.A1

NOTE:  The contents of the Text Window are not saved.

     Example:  $STW(5)$
     Returns:  nothing




$RTW(slot)$ ... Restore Text Window information                       > v2.A1
-----------------------------------------------
If no slot parameter is specified then this command restores all text > v2.A1
window definitions from the slot-less definition file saved with a    > v2.A1
$STW$ command (with no parameters).  The file is not deleted and you  > v2.A1
can restore many times.                                               > v2.A1
                                                                      > v2.A1
If you specify a slot parameter then that identifies which of the ten > v2.A1
different slots you wish to restore from (0-9).  Once the slot file   > v2.A1
is read it is deleted.                                                > v2.A1
                                                                      > v2.A1
If you specify a slot number of "POP" then you are performing a       > v2.A1
stack-based pop operation (eg, $RTW(POP)$).                           > v2.A1
                                                                      > v2.A1
In any case, the text window settings active when a $STW$ (Save Text  > v2.A1
Window) was executed are saved.  The current cursor location, window  > v2.A1
location, ANSI attributes, cursor ON/OFF status, vertical scrolling   > v2.A1
margins, and the System Font are restored.                            > v2.A1

NOTE:  The text contents of the window are not restored.

     Example:  $RTW(5)$
     Returns:  nothing



$SCB(slot)$ ... Save Clipboard                                        > v2.A1
------------------------------
This Active Text Variable saves the Clipboard to disk for later
retrieval by a Query or Host Command.  If the clipboard is empty, the
temporary file is deleted so Restore Clipboard knows there shouldn't
be a clipboard active.

If you do not specify a slot parameter then the clipboard is saved to > v2.A1
a slot-less file.  When it is restored the file is not deleted so you > v2.A1
can do multiple identical clipboard restorations.                     > v2.A1
                                                                      > v2.A1
If you do specify a slot parameter then you may save the clipboard to > v2.A1
one of ten different clipboard slots (0-9).  When you restore a       > v2.A1
clipboard slot, the clipboard file is deleted.                        > v2.A1
                                                                      > v2.A1
You may specify a slot number of "PUSH" to perform a stack-based push > v2.A1
operation (eg, $SCB(PUSH)$).                                          > v2.A1

     Example:  $SCB(4)$
     Returns:  nothing




$RCB$(slot) ... Restore Clipboard                                     > v2.A1
---------------------------------
This Active Text Variable restores the Clipboard from a previously
executed $SCB$ command.  Not only are the clipboard contents saved,
but so is the last clipboard location, so Paste Clipboard ($PCB$)
restores the clipboard's contents AND location.

If you do not specify a slot parameter then the clipboard is restored > v2.A1
from a slot-less file.  It is not deleted so you can do multiple      > v2.A1
identical clipboard restorations.                                     > v2.A1
                                                                      > v2.A1
If you do specify a slot parameter then you may restore the clipboard > v2.A1
from any of ten different clipboard slots (0-9).  Once restored, the  > v2.A1
clipboard slot file is deleted.                                       > v2.A1
                                                                      > v2.A1
You may specify a slot number of "POP" to perform a stack-based pop   > v2.A1
operation (eg, $RCB(POP)$).                                           > v2.A1

     Example:  $RCB(4)$
     Returns:  nothing



$PCB(clipno)$ ... Paste Clipboard at last location                    > v2.A1
--------------------------------------------------
This Active Text Variable pastes the clipboard at the last location
it was clipped from.  This also works with icons and bitmaps that are > v2.A1
placed on the clipboard.  The last location taken used is the         > v2.A1
location the icon was stamped when it was first loaded.  This text
variable is useful if you want to pop up a dialog box (saving the
previous area behind the dialog onto the clipboard), and when the
user clicks on the "OK" button, restoring the screen contents (by
using a $PCB$ in the host command string).

When the Clipboard is pasted back onto the screen, it adheres to the  > v1.54
Graphical Viewport that was in effect when the clipboard was clipped  > v1.54
initially.  In other words, the clipboard will be put in the same     > v1.54
location regardless of where it came from.                            > v1.54

If you do not specify the CLIPNO parameter, then the clipboard that   > v2.A1
is pasted in the original position is clipboard page 0.  If you do    > v2.A1
specify a CLIPNO parameter, it corresponds to a particular clipboard  > v2.A1
page number and that page is pasted at its last location.             > v2.A1

     Example:  $PCB(0)$ ... equivalent to $PCB$
     Returns:  nothing




$MKILL(x0,y0,x1,y1,inout)$ ... Kill Mouse Fields                      > v2.A1
------------------------------------------------
If no parameters are specified then all mouse fields currently        > v2.A1
defined are deleted (just like RIP_KILL_MOUSE_FIELDS does).  If you   > v2.A1
specify the five parameters, you are defining a box on the screen     > v2.A1
that should have the mouse fields inside or outside of it deleted.    > v2.A1
Whether mouse fields inside the box or outside the box are destroyed  > v2.A1
depends on the INOUT parameter.  If this parameter is specified as    > v2.A1
"IN" then all mouse fields inside the box are deleted.  If the        > v2.A1
parameter is set to "OUT" then all mouse fields outside the box       > v2.A1
are deleted.  Coordinates are specified in World coordinates.         > v2.A1

This Active Text Variable deletes all defined Mouse Fields exactly
like RIP_KILL_MOUSE_FIELDS does.  The benefit is when the user clicks
on a Mouse Fields or Button, the Mouse Fields are removed, but the
graphics remain on the screen.  The fields could be subsequently
re-defined quickly and easily without having to re-transmit an
identical menu over again.

     Example:  $MKILL$ ... Kill all mouse fields defined
               $MKILL(0,0,639,100,IN)$ ... Kill all mouse fields
                                           inside the box (0,0) to
                                           (639,100).
     Returns:  nothing



$EGW(slot)$ ... Erase Graphics viewport                               > v2.A1
---------------------------------------
This Active Text Variable erases the graphics viewport (much like a   > v2.A1
Reset Windows command does). This command is useful in Host
Commands.  When you click on a Mouse Field, it could erase the
viewport window THEN transmit the remainder of the return string (if
any) to the host.

Remember, this may not clear the entire screen (although it will
quite often since the Graphical Viewport is often full-screen).

This command does not require the slot parameter.  If it is omitted,  > v2.A1
then the current viewport is cleared.  If you specify a number (0-35) > v2.A1
then the corresponding viewport slot number is erased.  A special     > v2.A1
value of "ALL" may be used to erase all currently defined viewports.  > v2.A1

     Example:  $EGW(ALL)$ ... Erase all viewports                     > v2.A1
               $EGW$      ... Erase current viewport                  > v2.A1
               $EGW(5)$   ... Erase viewport slot #5                  > v2.A1
     Returns:  nothing



$ETW(slot)$ ... Erase Text Window                                     > v2.A1
---------------------------------
If no parameters are specified then the current text window in use is > v2.A1
cleared.  If you specify a slot from 0-35 then the corresponding text > v2.A1
window slot is erased.  You may also specify "ALL" to erase all       > v2.A1
currently defined text window slots.                                  > v2.A1

This command is useful in Host Commands when you click on a Mouse
Field, it could erase the text window THEN transmit the remainder of
the Host Command (if any).

     Example:  $ETW(ALL)$
     Returns:  nothing


$DTW(slot)$ ... Disable Text Window                                   > v2.A1
-----------------------------------
If no slot parameter is specified then the current text window is     > v2.A1
disabled, preventing any received raw text from being displayed in    > v2.A1
that window.  A text window slot change though can re-enable text     > v2.A1
displaying if that other slot is not "disabled".                      > v2.A1
                                                                      > v2.A1
If a slot is specified then that text window slot is disabled.  This  > v2.A1
may or may not affect the current status of received text.  If the    > v2.A1
slot specified just happens to be the current slot then all received  > v2.A1
text is disabled.  If the text window slot isn't the current active   > v2.A1
text window then that text window is disabled, but what is done with  > v2.A1
received raw text depends on the status of the current text window's  > v2.A1
status.                                                               > v2.A1
                                                                      > v2.A1
You may also specify a slot of "ALL" to disable all text window       > v2.A1
slots.  This would also disable any raw text that is received because > v2.A1
the act of disabling all windows will consequently disable the        > v2.A1
current one too.                                                      > v2.A1

This Active Text Variable disables the Text Window (preventing any
received text from showing up on screen).

This command is useful in Host Commands when you click on a Mouse
Field, it would halt any further output to the text window.

     Example:  $DTW$
     Returns:  nothing



$TWIN(window)$ ... Text  Window Status                                > v2.A1
--------------------------------------
This Text Variable checks to see if the specified Text Window exists,
and returns YES if there is a Text Window, or returns NO if there is
no Text Window or the Text Window has been disabled (with $DTW$).

If you do not specify a window parameter, then this command refers to > v2.A1
the current text window.  If you do specify a window parameter then   > v2.A1
this command specifically refers to that text window slot.            > v2.A1

     Example:  $TWIN(4)$                                              > v2.A1
     Returns:  YES



$TWFONT(window)$ ... Active Text Font                                 > v2.A1
-------------------------------------
This Text Variable returns which of the five Text Window Fonts is
active, or 0 (zero) if there is no Text Window.

          0 ... No Text Window          3 ... 80x25 font
          1 ... 80x43 font              4 ... 91x25 MicroANSI font
          2 ... 91x43 MicroANSI font    5 ... 40x25 font

If you do not specify a window parameter, then this command refers to > v2.A1
the current text window.  If you do specify a window parameter then   > v2.A1
this command specifically refers to that text window slot.            > v2.A1

     Example:  $TWFONT(4)$                                            > v2.A1
     Returns:  1




$TWH(window)$ ... Text Window Height                                  > v2.A1
------------------------------------
This Text Variable returns the height of the Text Window, or 0 (zero)
if there is no Text Window.  If a text window exists, the minimum
value is 1 and the maximum value is 43.  This may increase in the
future.

If you do not specify a window parameter, then this command refers to > v2.A1
the current text window.  If you do specify a window parameter then   > v2.A1
this command specifically refers to that text window slot.            > v2.A1

     Example:  $TWH(4)$                                               > v2.A1
     Returns:  25



$TWW(window)$ ... Text Window Width                                   > v2.A1
-----------------------------------
This Text Variable returns the width of the Text Window, or 0 (zero)
if there is no Text Window.  If a text window exists, the minimum
value is 1 and the maximum value is 91.  This may increase in the
future.

If you do not specify a window parameter, then this command refers to > v2.A1
the current text window.  If you do specify a window parameter then   > v2.A1
this command specifically refers to that text window slot.            > v2.A1

     Example:  $TWW(window)$                                          > v2.A1
     Returns:  80


$TWX0(window)$ ... Text Window Upper Left X Coordinate                > v2.A1
------------------------------------------------------
This Text Variable is the X coordinate of the upper left corner of
the Text Window.  The coordinates given are relative to the upper
left of the screen.  The values are given in cells, which is a block
the size of one character in the currently selected font.  A good
analogy is that a cell is equivalent to a square on a sheet of graph
paper.  The cell size may change depending on the font used, but the
relative position for that font remains constant.  If there is no
Text Window, this returns 0 (zero).  However, note that 0 (zero) is
also a valid coordinate.  Use $TWIN$ to determine if there is a Text
Window.

If you do not specify a window parameter, then this command refers to > v2.A1
the current text window.  If you do specify a window parameter then   > v2.A1
this command specifically refers to that text window slot.            > v2.A1

     Example:  $TWX0(4)$                                              > v2.A1
     Returns:  0


$TWY0(window)$ ... Text Window Upper Left Y Coordinate                > v2.A1
------------------------------------------------------
This Text Variable is the Y coordinate of the upper left corner of
the Text Window.  See $TWX0$ for an explanation of the coordinate
system.

If you do not specify a window parameter, then this command refers to > v2.A1
the current text window.  If you do specify a window parameter then   > v2.A1
this command specifically refers to that text window slot.            > v2.A1

     Example:  $TWY0(4)$                                              > v2.A1
     Returns:  40

$TWX1(window)$ ... Text Window Lower Right X Coordinate               > v2.A1
-------------------------------------------------------
This Text Variable is the X coordinate of the lower right corner of
the Text Window.  See $TWX0$ for an explanation of the coordinate
system.

If you do not specify a window parameter, then this command refers to > v2.A1
the current text window.  If you do specify a window parameter then   > v2.A1
this command specifically refers to that text window slot.            > v2.A1

     Example:  $TWX1(4)$                                              > v2.A1
     Returns:  80


$TWY1(window)$ ... Text Window Lower Right Y Coordinate               > v2.A1
-------------------------------------------------------
This Text Variable is the Y coordinate of the lower right corner of
the Text Window.  See $TWX0$ for an explanation of the coordinate
system.

If you do not specify a window parameter, then this command refers to > v2.A1
the current text window.  If you do specify a window parameter then   > v2.A1
this command specifically refers to that text window slot.            > v2.A1

     Example:  $TWY1(4)$                                              > v2.A1
     Returns:  43


$CURX(window)$ ... Text Cursor X Coordinate                           > v2.A1
-------------------------------------------
This Text Variable is the X coordinate of the text cursor in the Text
Window, relative to the upper left of the Text Window.  See $TWX0$
for an explanation of the coordinate system.

If you do not specify a window parameter, then this command refers to > v2.A1
the current text window.  If you do specify a window parameter then   > v2.A1
this command specifically refers to that text window slot.            > v2.A1

     Example:  $CURX(4)$                                              > v2.A1
     Returns:  2



$CURY(window)$ ... Text Cursor Y Coordinate                           > v2.A1
-------------------------------------------
This Text Variable is the Y coordinate of the text cursor in the Text
Window, relative to the upper left of the Text Window.  See $TWX0$
for an explanation of the coordinate system.

If you do not specify a window parameter, then this command refers to > v2.A1
the current text window.  If you do specify a window parameter then   > v2.A1
this command specifically refers to that text window slot.            > v2.A1

     Example:  $CURY(4)$                                              > v2.A1
     Returns:  5



$CON$ ... Enable the Text Cursor
--------------------------------
This Active Text Variable turns on the text cursor in the current
text window.

     Example:  $CON$
     Returns:  nothing

$COFF$ ... Disable the Text Cursor
----------------------------------
This Active Text Variable turns off the text cursor in the current
text window.  This is automatically reset when a Reset Windows
command is received.

     Example:  $COFF$
     Returns:  nothing



$CURSOR$ ... Text Cursor Status
-------------------------------
This Text Variable returns YES if the Text Cursor is enabled in the
current text window, and NO if the Text Cursor is disabled.  If there
no Text Window, it returns NO.

     Example:  $CURSOR$
     Returns:  YES



$STATBAR$ ... Status Bar Status
-------------------------------
This Text Variable returns YES if the Status Bar is visible in the
terminal.  If the Status Bar is not visible, then NO is returned.

     Example:  $STATBAR$
     Returns:  YES



$SBARON$ ... Turn ON the Status Bar
-----------------------------------
This Active Text Variable turns ON the Status Bar in the terminal.

     Example:  $SBARON$
     Returns:  nothing



$SBAROFF$ ... Turn OFF the Status Bar
-------------------------------------
This Active Text Variable turns OFF the Status Bar in the terminal.

     Example:  $SBAROFF$
     Returns:  nothing




$VT102ON$ ... Turn VT-102 keyboard mode ON
------------------------------------------
This Active Text Variable enables the VT-102 keystrokes ability.
This makes the following keystrokes send something to the host:

                  F1 - ESC [ M
                  F2 - ESC [ N
                  F3 - ESC [ O
                  F4 - ESC [ P
                  F5 - ESC [ Q
                  F6 - ESC [ R
                  F7 - ESC [ S
                  F8 - ESC [ T
                  F9 - ESC [ U
                 F10 - ESC [ V
                PGUP - ESC [ I
                PGDN - ESC [ G
                HOME - ESC [ H
                 END - ESC [ F
              INSERT - ESC [ L
           CURSOR UP - ESC [ A
           CURSOR DN - ESC [ B
         CURSOR LEFT - ESC [ C
        CURSOR RIGHT - ESC [ D


This text variable puts the terminal in VT-102 mode automatically,
making it simpler for the user.

     Example:  $VT102ON$
     Returns:  nothing



$VT102OFF$ ... Turn VT-102 keyboard mode OFF
--------------------------------------------
This Active Text Variable disables the VT-102 keystrokes mode,
returning your keyboard to the standard keyboard operation.

     Example:  $VT102OFF$
     Returns:  nothing



$DWAYON$ ... Turn Doorway Mode ON
---------------------------------
This Active Text Variable enables Doorway Mode.  This is intended to
be used by a Host system that wishes to take advantage of the Doorway
mode available in Marshall Dudley's Doorway (tm) software package.

     Example:  $DWAYON$
     Returns:  nothing



$DWAYOFF$ ... Turn Doorway Mode OFF
-----------------------------------
This Active Text Variable disables the Doorway keyboard mode.  This
will return the keyboard to normal operation.

     Example:  $DWAYOFF$
     Returns:  nothing



$HKEYON$ ... Enable Button Hotkeys
----------------------------------
This Active Text Variable turns on use of Button Hotkeys.  When
enabled, if the user presses a key associated with a button, it is
selected just as if it were clicked.  The Scroll Lock light on the
keyboard is turned on.

     Example:  $HKEYON$
     Returns:  nothing



$HKEYOFF$ ... Disable Button Hotkeys
------------------------------------
This Active Text Variable turns off Button Hotkeys.  This should be
done when entering a full-screen editor, or any part of the system
where the user is entering a string of text.  This is to prevent the
user from accidentally selecting a button when typing in text.

     Example:  $HKEYOFF$
     Returns:  nothing



$TABON$ ... Enable TAB key Mouse Field select
---------------------------------------------
This Active Text Variable turns on the use of the TAB key to jump
from one defined Mouse or Button Field to another.

     Example:  $TABON$
     Returns:  nothing



$TABOFF$ ... Disable TAB key Mouse Field select
-----------------------------------------------
This Active Text Variable turns off the use of the TAB key to jump
from one defined Mouse or Button Field to another.  If this command
is received when a field is highlighted, it is deselected.  This
should be done when entering a full-screen editor so that the user
can use the TAB key as a TAB, not a Mouse Field selector.

     Example:  $TABOFF$
     Returns:  nothing



$APP0$ - $APP9$ ... External Application Call
---------------------------------------------
This Active Text Variable instructs the terminal to execute an
external application.  By recommendation, $APP0$ is the user's text
editor.  There are ten external application slots available, numbered
0 - 9.  These are defined in the External menu in RIPterm.

This command is obsolete.  You should be using the $APP(appno)$       > v2.A1
command as it is more general in nature.  Other than that, the new    > v2.A1
APP command performs the exact same operation.  If you need to pass   > v2.A1
custom arguments to the external application, then use the more       > v2.A1
generic $APP(appno)$ command instead.                                 > v2.A1

     Example:  $APP1$
     Returns:  nothing

$APP(appno,argument)$ ... External Application Call                   > v2.A1
----------------------------------------------------                  > v2.A1
This text variable instructs the terminal to execute an external      > v2.A1
application.  If you do not specify any parameters, then application  > v2.A1
number zero will be executed.  If you do specify any parameters, you  > v2.A1
may specify one or both of them.  If you supply the ARGUMENT          > v2.A1
parameter, you must specify the APPNO option.  APPNO is a number from > v2.A1
0-9 indicating which application should be executed.  If used, the    > v2.A1
ARGUMENT parameter is an arbitrary command line argument that will be > v2.A1
added to the end of the application's command line string.  This      > v2.A1
gives the ability to allow the host to control portions of the        > v2.A1
external application's operation.                                     > v2.A1
                                                                      > v2.A1
     Example:  $APP(0,FILENAME.TXT)                                   > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$MCURSOR(cursor_no)$ ... Set the mouse cursor style number            > v2.A1
----------------------------------------------------------            > v2.A1
This command changes the current mouse cursor style to one of the     > v2.A1
pre-defined mouse cursor styles as defined in the                     > v2.A1
RIP_SET_MOUSE_CURSOR command.  The cursor_no parameter is identical   > v2.A1
to the cursor style numbers permitted for the RIPscrip command to     > v2.A1
alter the cursor.  If you omit the CURSOR_NO parameter, the default   > v2.A1
"pointer" cursor is activated.                                        > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$VIEWX0(viewno,coordtype)$ ... Viewport's upper left X coordinate     > v2.A1
-----------------------------------------------------------------     > v2.A1
This variable returns the X coordinate of the upper left corner of    > v2.A1
the specified viewport.  If no parameters are specified, then the     > v2.A1
current viewport's coordinate is return and the result is provided in > v2.A1
world coordinates.  If you specify a VIEWNO parameter, then you are   > v2.A1
specifying the viewport slot number to report on.                     > v2.A1
                                                                      > v2.A1
The COORDTYPE parameter allows you to request return values in        > v2.A1
particular formats.  The valid values for COORDTYPE are "WORLD" and   > v2.A1
"VIDEO".  The world coordinate choice returns values in world         > v2.A1
coordinates.  The video setting returns coordinates in raw video      > v2.A1
coordinates.  In order to specify a coordinate type, you must specify > v2.A1
a viewport number.  If you wish to access the current viewport, you   > v2.A1
can specify a viewno of "CUR" for current.                            > v2.A1
                                                                      > v2.A1
     Example:  $VIEWX0(5,WORLD)$                                      > v2.A1
     Returns:  50                                                     > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$VIEWY0(viewno,coordtype)$ ... Viewport's upper left Y coordinate     > v2.A1
-----------------------------------------------------------------     > v2.A1
This variable returns the Y coordinate of the upper left corner of    > v2.A1
the specified viewport.  If no parameters are specified, then the     > v2.A1
current viewport's coordinate is return and the result is provided in > v2.A1
world coordinates.  If you specify a VIEWNO parameter, then you are   > v2.A1
specifying the viewport slot number to report on.                     > v2.A1
                                                                      > v2.A1
The COORDTYPE parameter allows you to request return values in        > v2.A1
particular formats.  The valid values for COORDTYPE are "WORLD" and   > v2.A1
"VIDEO".  The world coordinate choice returns values in world         > v2.A1
coordinates.  The video setting returns coordinates in raw video      > v2.A1
coordinates.  In order to specify a coordinate type, you must specify > v2.A1
a viewport number.  If you wish to access the current viewport, you   > v2.A1
can specify a viewno of "CUR" for current.                            > v2.A1
                                                                      > v2.A1
     Example:  $VIEWY0(CUR,DEVICE)$                                   > v2.A1
     Returns:  0                                                      > v2.A1

$VIEWX1(viewno,coordtype)$ ... Viewport's lower right X coordinate    > v2.A1
-------------------------------------------------------------------   > v2.A1
This variable returns the X coordinate of the lower right corner of   > v2.A1
the specified viewport.  If no parameters are specified, then the     > v2.A1
current viewport's coordinate is return and the result is provided in > v2.A1
world coordinates.  If you specify a VIEWNO parameter, then you are   > v2.A1
specifying the viewport slot number to report on.                     > v2.A1
                                                                      > v2.A1
The COORDTYPE parameter allows you to request return values in        > v2.A1
particular formats.  The valid values for COORDTYPE are "WORLD" and   > v2.A1
"VIDEO".  The world coordinate choice returns values in world         > v2.A1
coordinates.  The video setting returns coordinates in raw video      > v2.A1
coordinates.  In order to specify a coordinate type, you must specify > v2.A1
a viewport number.  If you wish to access the current viewport, you   > v2.A1
can specify a viewno of "CUR" for current.                            > v2.A1
                                                                      > v2.A1
     Example:  $VIEWX1(0,DEVICE)$                                     > v2.A1
     Returns:  639                                                    > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$VIEWY1(viewno,coordtype)$ ... Viewport's lower right Y coordinate    > v2.A1
------------------------------------------------------------------    > v2.A1
This variable returns the Y coordinate of the lower right corner of   > v2.A1
the specified viewport.  If no parameters are specified, then the     > v2.A1
current viewport's coordinate is return and the result is provided in > v2.A1
world coordinates.  If you specify a VIEWNO parameter, then you are   > v2.A1
specifying the viewport slot number to report on.                     > v2.A1
                                                                      > v2.A1
The COORDTYPE parameter allows you to request return values in        > v2.A1
particular formats.  The valid values for COORDTYPE are "WORLD" and   > v2.A1
"VIDEO".  The world coordinate choice returns values in world         > v2.A1
coordinates.  The video setting returns coordinates in raw video      > v2.A1
coordinates.  In order to specify a coordinate type, you must specify > v2.A1
a viewport number.  If you wish to access the current viewport, you   > v2.A1
can specify a viewno of "CUR" for current.                            > v2.A1
                                                                      > v2.A1
     Example:  $VIEWY1(CUR,DEVICE)$                                   > v2.A1
     Returns:  349                                                    > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$VIEWX(viewno,coordtype)$ ... Width of viewport                       > v2.A1
-----------------------------------------------                       > v2.A1
This variable returns the width of the specified viewport.            > v2.A1
If no parameters are specified, then the value returned is provided   > v2.A1
world coordinates.  If you specify a VIEWNO parameter, then you are   > v2.A1
specifying the viewport slot number to report on.                     > v2.A1
                                                                      > v2.A1
The COORDTYPE parameter allows you to request return values in        > v2.A1
particular formats.  The valid values for COORDTYPE are "VIEW",       > v2.A1
"WORLD" and "VIDEO".  View coordinates report coordinates in          > v2.A1
viewport coordinate values.  The world coordinate choice returns      > v2.A1
values in world coordinates.  The video setting returns coordinates   > v2.A1
in raw video coordinates.  In order to specify a coordinate type, you > v2.A1
must specify a viewport number.  If you wish to access the current    > v2.A1
viewport, you can specify a viewno of "CUR" for current.              > v2.A1
                                                                      > v2.A1
     Example:  $VIEWX(0,DEVICE)$                                      > v2.A1
     Returns:  640                                                    > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1

$VIEWY(viewno,coordtype)$ ... Height of viewport                      > v2.A1
------------------------------------------------                      > v2.A1
This variable returns the height of the specified viewport.           > v2.A1
If no parameters are specified, then the value returned is provided   > v2.A1
world coordinates.  If you specify a VIEWNO parameter, then you are   > v2.A1
specifying the viewport slot number to report on.                     > v2.A1
                                                                      > v2.A1
The COORDTYPE parameter allows you to request return values in        > v2.A1
particular formats.  The valid values for COORDTYPE are "VIEW",       > v2.A1
"WORLD" and "VIDEO".  View coordinates report coordinates in          > v2.A1
viewport coordinate values.  The world coordinate choice returns      > v2.A1
values in world coordinates.  The video setting returns coordinates   > v2.A1
in raw video coordinates.  In order to specify a coordinate type, you > v2.A1
must specify a viewport number.  If you wish to access the current    > v2.A1
viewport, you can specify a viewno of "CUR" for current.              > v2.A1
                                                                      > v2.A1
     Example:  $VIEWY(0,WORLD)$                                       > v2.A1
     Returns:  1000                                                   > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$BASEMATH(setting)$ ... Sets the base math for numerical parameters   > v2.A1
-------------------------------------------------------------------   > v2.A1
This command allows you to alter the current base math setting of     > v2.A1
subsequent RIPscrip graphics.  the SETTING parameter is not required. > v2.A1
If it is specified, it must be set to either 36 or 64.  This text     > v2.A1
variable does the same thing as the RIPscrip command                  > v2.A1
RIP_SET_BASE_MATH.  If you omit the setting parameter then the        > v2.A1
current base math setting is returned to the host (eg, 36 or 64).     > v2.A1
                                                                      > v2.A1
     Example:  $BASEMATH(36)$                                         > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$RESX$ ... Horizontal resolution of current video device              > v2.A1
--------------------------------------------------------              > v2.A1
This variable returns the horizontal resolution of the video device   > v2.A1
in pixels.  Typical results for this might be 640, 800, 1024 or 1280. > v2.A1
But this might be different depending on the various possible video   > v2.A1
devices in existance.                                                 > v2.A1
                                                                      > v2.A1
     Example:  $RESX$                                                 > v2.A1
     Returns:  640                                                    > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$RESY$ ... Vertical resolution of current video device                > v2.A1
------------------------------------------------------                > v2.A1
This variable returns the vertical resolution of the video device     > v2.A1
in scan lines.  Typical results for this might be 350, 480, 600,      > v2.A1
768 or 1024.  But this might be different depending on the various    > v2.A1
possible video devices in existance.                                  > v2.A1
                                                                      > v2.A1
     Example:  $RESY$                                                 > v2.A1
     Returns:  768                                                    > v2.A1

$WORLDX$ ... Horizontal resolution of world coordinate system         > v2.A1
-------------------------------------------------------------         > v2.A1
Returns the horizontal width of the current world coordinate config.  > v2.A1
                                                                      > v2.A1
     Example:  $WORLDX$                                               > v2.A1
     Returns:  4096                                                   > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$WORLDY$ ... Vertical resolution of world coordinate system           > v2.A1
-----------------------------------------------------------           > v2.A1
Returns the vertical height of the current world coordinate config.   > v2.A1
                                                                      > v2.A1
     Example:  $WORLDY$                                               > v2.A1
     Returns:  4096                                                   > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$COLORS$ ... Total number of colors of current video device           > v2.A1
-----------------------------------------------------------           > v2.A1
This variable returns the total number of colors available on the     > v2.A1
destination video hardware device.  Typical results are 2, 16, 256,   > v2.A1
32768, 65536 and 16,777,216 (24 bit color).  These aren't the         > v2.A1
only possible values, but are typical ones.                           > v2.A1
                                                                      > v2.A1
     Example:  $COLORS$                                               > v2.A1
     Returns:  256                                                    > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$COLORMODE$ ... Returns if color mode is Direct RGB or Palette        > v2.A1
--------------------------------------------------------------        > v2.A1
If the current terminal is in Direct RGB mode then this variable      > v2.A1
returns "DIRECT".  Otherwise it is in standard color palette mode and > v2.A1
it would return "PALETTE".                                            > v2.A1
                                                                      > v2.A1
     Example:  $COLORMODE$                                            > v2.A1
     Returns:  PALETTE                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$ISPALETTE$ ... Reports if a color palette exists or not              > v2.A1
--------------------------------------------------------              > v2.A1
If the destination terminal is operating with a video device that has > v2.A1
an actual color palette then this variable returns "YES".  If         > v2.A1
however, the terminal is running on a device that's in 24-bit color   > v2.A1
mode where there is no color palette then this variable returns "NO". > v2.A1
                                                                      > v2.A1
     Example:  $ISPALETTE$                                            > v2.A1
     Returns:  YES                                                    > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$PALENTRY(palno)$ ... Returns RGB settings of color palette entry     > v2.A1
-----------------------------------------------------------------     > v2.A1
This variable returns the RGB values associated with a particular     > v2.A1
color palette index on the destination terminal.  The purpose of this > v2.A1
variable is so that a host can find out what colors are defined on    > v2.A1
the terminal.  The return value is in Red, Green then Blue order      > v2.A1
separated by colons.  Each value is from 0-255 and is exactly three   > v2.A1
bytes wide (eg, 023:234:001).  If the destination terminal does not   > v2.A1
have a color palette or the palette entry number is out of range then > v2.A1
the value "000:000:000" is returned.  If you do not specify a PALNO   > v2.A1
entry then all palette entries are returned with commas between       > v2.A1
each entry (eg, "000:000:000,021:021:021, ... 255:255:255").          > v2.A1
                                                                      > v2.A1
     Example: $PALENTRY(15)$                                          > v2.A1
     Returns: 255:255:255                                             > v2.A1

$BAUDEMUL(newbaud)$ ... Returns baud rate emulation for playback      > v2.A1
----------------------------------------------------------------      > v2.A1
This variable allows the host to determine the current baud rate      > v2.A1
emulation setting for use with local RIP file playback.  A return     > v2.A1
value of "0" means that playback should occur at full speed.  Values  > v2.A1
that can be returned are 0, 300, 1200, 2400, 4800, 9600, 14400,       > v2.A1
16800, 19200, 28800, 38400, 57600 and 115200.                         > v2.A1
                                                                      > v2.A1
If you specify no parameters (as described above) then this command   > v2.A1
returns the current setting.  If you specify the NEWBAUD parameter    > v2.A1
then you are manually setting a baud rate (see above for valid        > v2.A1
rates).  If you are setting the baud rate, nothing is returned to the > v2.A1
host.                                                                 > v2.A1
                                                                      > v2.A1
     Example:  $BAUDEMUL$                                             > v2.A1
     Returns:  9600                                                   > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$STACKCLEAR(which,count)$ ... Clears the save/restore stack to start  > v2.A1
--------------------------------------------------------------------  > v2.A1
This text variable clears the settings of the specified save/restore  > v2.A1
stack.  By default, all stacks are cleared if no WHICH parameter is   > v2.A1
specified.  You may specify one of several types of stacks to clear.  > v2.A1
When cleared, all previously saved entries in all of the slots for    > v2.A1
that stack type are cleared and the current slot number for           > v2.A1
subsequent push operations is set to zero (unless a COUNT parameter)  > v2.A1
parameter is specified.  The types of stacks that can be cleared      > v2.A1
(WHICH parameter) are:                                                > v2.A1
                                                                      > v2.A1
             ALL ... Clear all stacks (default)                       > v2.A1
           MOUSE ... Clear only the saved mouse field stacks          > v2.A1
            TEXT ... Clear only the saved text window stacks          > v2.A1
            CLIP ... Clear only the saved clipboard stacks            > v2.A1
          SCREEN ... Clear only the saved graphics screen stacks      > v2.A1
                                                                      > v2.A1
The second parameter (COUNT) indicates how many entires to pop.  If   > v2.A1
omitted then all entires are popped until the stack is empty.  For    > v2.A1
example, if you specified a count of 2 then two pop operations are    > v2.A1
performed.                                                            > v2.A1
                                                                      > v2.A1
     Example:  $STACKCLEAR(ALL,3)$                                    > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1

$STACKPOS(which,pos)$ ... Next available slot # for push operation    > v2.A1
------------------------------------------------------------------    > v2.A1
This variable sets the next available slot number for push operations > v2.A1
for a given stack type.  By default, all stacks are set by this       > v2.A1
operation unless the WHICH parameter is specified.  Valid settings    > v2.A1
for the POS parameter which specifies the next used slot number are   > v2.A1
0-9.  This could be used to reset push/pop levels to a setting that   > v2.A1
you need.  This is a fairly advanced option.  No slot entries are     > v2.A1
explicitly cleared - only the stack position counter is altered.      > v2.A1
                                                                      > v2.A1
The available settings for the WHICH parameter are as follows (if     > v2.A1
omitted, ALL is assumed):                                             > v2.A1
                                                                      > v2.A1
             ALL ... Clear all stacks (default)                       > v2.A1
           MOUSE ... Clear only the saved mouse field stacks          > v2.A1
            TEXT ... Clear only the saved text window stacks          > v2.A1
            CLIP ... Clear only the saved clipboard stacks            > v2.A1
          SCREEN ... Clear only the saved graphics screen stacks      > v2.A1
                                                                      > v2.A1
This option is a bit different in nature to the $STACKCLEAR$          > v2.A1
operation.  This command gives you direct slot number control over    > v2.A1
the stack system.  The $STACKCLEAR$ permits you "relative" access     > v2.A1
to the stack system.  When you work with the $STACKCLEAR$ function    > v2.A1
you can clear (pop) a certain number of entries from the stack        > v2.A1
without having to know exactly which slot number is current.  Use     > v2.A1
this command if you precisely what slot number is current and want    > v2.A1
to have direct control over slot number control.                      > v2.A1
                                                                      > v2.A1
     Example:  $STACKPOS(4, SCREEN)$                                  > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$BEGINFORM(name,x0,y0,x1,y1)$ ... Begin a text variable data form     > v2.A1
-----------------------------------------------------------------     > v2.A1
This variable begins a text variable data entry form.  It must be     > v2.A1
followed by an $ENDFORM$ variable to signify the end of the form      > v2.A1
definition.  After the $BEGINFORM$ variable is encountered, any       > v2.A1
subsequent text variable definitions actually define data entry       > v2.A1
fields to be placed on the form.  The design considerations and       > v2.A1
syntax of the data entry form are described in a subsequent section   > v2.A1
on "Data Entry Forms".                                                > v2.A1
                                                                      > v2.A1
If specified, the NAME parameter gives the form an actual name.  The  > v2.A1
name can be used to identify the form to the host system.  For        > v2.A1
example, if you have several buttons defined on a menu and each of    > v2.A1
them have different forms defined in the host commands, the name can  > v2.A1
be used to identify to the host which button the user chose (and more > v2.A1
directly, the form "type" being transmitted).  If no name parameter   > v2.A1
is specified then the form is an unnamed form.                        > v2.A1
                                                                      > v2.A1
The X0 and Y0 parameter allow you to specify the upper left corner    > v2.A1
of the form dialog on the screen.  If omitted (then all X/Y           > v2.A1
parameters are omitted) then the dialog auto-sizes itself based       > v2.A1
upon the specified data fields.  If you specify the X0 and Y0         > v2.A1
parameters you have the option of specifying the X1 and Y1 parameters > v2.A1
to indicate the lower left corner of the dialog.  If you omit these   > v2.A1
then the width and height of the dialog are determined by the         > v2.A1
data fields defined for the form and a suitable width and height are  > v2.A1
calculated.                                                           > v2.A1
                                                                      > v2.A1
     Example:  $BEGINFORM(USERINFO)$                                  > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1

$ENDFORM(filename)$ ... End a text variable data entry form           > v2.A1
-----------------------------------------------------------           > v2.A1
This variable signifies the end of a data entry form definition.      > v2.A1
What happens when this variable is encountered depends on one thing - > v2.A1
is a filename parameter specified.  If specified, then the form       > v2.A1
definition is saved to a local form data file by the terminal.  This  > v2.A1
form definition can then be used and reused at a later date without   > v2.A1
having to transmit the form over and over again.                      > v2.A1
                                                                      > v2.A1
If no filename parameter is specified then the form is actually       > v2.A1
activated.  When activated, a dialog box will appear which is sized   > v2.A1
just large enough to accomodate all data fields.  The user is then    > v2.A1
allowed to fill-in all of the fields and they are then transmitted to > v2.A1
the host system in the order they were defined with possible          > v2.A1
additional raw text delimiters.  See the section later on covering    > v2.A1
the topic of Data Entry Forms for more information.                   > v2.A1
                                                                      > v2.A1
     Example:  $ENDFORM(USERINFO.FRM)$                                > v2.A1
     Returns:  The contents of the data entry fields (if no filename) > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$FORMNAME$ ... Returns the name of the current form                   > v2.A1
---------------------------------------------------                   > v2.A1
This variable can be used inside a form definition.  It is a special  > v2.A1
variable that can be used to insert the name of the current form into > v2.A1
the host return sequence.  Its use outside of forms is not allowed    > v2.A1
and will return nothing.  If no name was defined for the form then    > v2.A1
nothing is inserted into the host return sequence.                    > v2.A1
                                                                      > v2.A1
     Example:  $FORMNAME$                                             > v2.A1
     Returns:  Name of the current form (or nothing if none defined)  > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$RUNFORM(filename,output_file)$ ... Executes a form saved to disk     > v2.A1
-----------------------------------------------------------------     > v2.A1
This variable is used to execute a local form data file that was      > v2.A1
previously saved by a BEGINFORM/ENDFORM(filename) definition.  The    > v2.A1
FILENAME parameter is required.  If omitted, this variable will do    > v2.A1
nothing.  If the file exists, then the form is loaded and executed.   > v2.A1
                                                                      > v2.A1
If the OUTPUT_FILE parameter is specified then the results of the     > v2.A1
form execution are written to a text file of the specified filename   > v2.A1
in OUTPUT_FILE.  If this parameter is not present, then the results   > v2.A1
of the form execution are sent to the host.  See the later section    > v2.A1
on Data Entry Forms for more details on how information is formatted  > v2.A1
and transmitted to the host.  If you specify any X/Y parameters then  > v2.A1
you must specify a NAME parameter.                                    > v2.A1
                                                                      > v2.A1
     Example:  $RUNFORM(USERINFO.FRM,FILENAME.TXT)$                   > v2.A1
     Returns:  The form's data contents if no output file specified   > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$FRAMELESS$ ... Place form's fields directly on screen, not on dialog > v2.A1
--------------------------------------------------------------------- > v2.A1
This is useful only in a form definition - if used prior to any       > v2.A1
normal text variable, then it specifies that no dialog should be      > v2.A1
created to place the fields upon; the fields are placed inside the    > v2.A1
current viewport on top of whatever graphics you already have.  When  > v2.A1
the form is complete, the fields are not erased.  It's up to the host > v2.A1
to clear the fields in this case.  If you do not specify this text    > v2.A1
variable then when the form is complete, the dialog box is removed.   > v2.A1
                                                                     > v2.A1
$TWGOTO(winno,x,y)$ ... Move cursor to position in text window        > v2.A1
--------------------------------------------------------------        > v2.A1
This variable allows you to move the cursor position in a given text  > v2.A1
window to a specified X/Y position.  If no parameters are given or no > v2.A1
X/Y parameters are given then nothing happens when this is executed.  > v2.A1
                                                                      > v2.A1
The WINNO parameter specifies a text window slot to move the cursor   > v2.A1
in.  Valid settings for WINNO are 0-35.  If the specified window is   > v2.A1
not the current text window then the cursor in that window's          > v2.A1
definition is moved but no visible things occur on the screen.  If    > v2.A1
the specified window slot is "CUR" or the window number happens to be > v2.A1
the current text window, then the cursor that is (potentially) on the > v2.A1
screen is moved to the new location.                                  > v2.A1
                                                                      > v2.A1
The X/Y coordinates are text coordinates (1 based).  Specifying both  > v2.A1
coordinates allows you to place the cursor anywhere in the chosen     > v2.A1
window.  You may omit the Y parameter entirely to move the cursor     > v2.A1
horizontally only.  Either the X or Y parameter (or both) may be      > v2.A1
specified as "CUR" to indicate the the row or column is not to        > v2.A1
change.  In other words, if you wanted to move the cursor to line 2   > v2.A1
in the text window 5, but leave its column unchanged, you would       > v2.A1
use $TWGOTO(5,CUR,2)$.                                                > v2.A1
                                                                      > v2.A1
If the goto sequence would put the cursor outside the dimensions of   > v2.A1
the text window then the cursor is placed at the closest point to the > v2.A1
given location at the windows border.  If the window is currently     > v2.A1
disabled, then nothing happens when this command is executed.         > v2.A1
                                                                      > v2.A1
     Example:  $TWGOTO(CUR,10,2)$                                     > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$TWHOME(winno)$ ... Move cursor to home position in text window       > v2.A1
---------------------------------------------------------------       > v2.A1
This command moves the cursor in the specified text window slot to    > v2.A1
the upper-left corner of the window.  WINNO may be any value from     > v2.A1
0-35 to indicate the desired slot number.  If the WINNO slot number   > v2.A1
happens to correspond to the current text window or the WINNO         > v2.A1
parameter is specified as "CUR" then the cursor that is on the        > v2.A1
screen (potentially) will be visibly moved.  If the WINNO parameter   > v2.A1
specifies a window that is not the current text window then the       > v2.A1
cursor position definition for that non-current window is altered     > v2.A1
only - no visible thing would happen on the screen.  If the specified > v2.A1
window is disabled then nothing happens.  If the WINNO parameter is   > v2.A1
omitted then the current text window is assumed.                      > v2.A1
                                                                      > v2.A1
     Example:  $TWHOME(5)$                                            > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$TWERASEEOL(winno)$ ... Erase to end of line in text window           > v2.A1
-----------------------------------------------------------           > v2.A1
This variable clears the current line in the specified text window    > v2.A1
from the cursor to the end of the line in the current ANSI color      > v2.A1
attributes.  If the WINNO parameter is omitted then the current text  > v2.A1
window is used for the destination window.  WINNO may be any value    > v2.A1
from 0-35 to indicate an explicit text window slot number.  A value   > v2.A1
of "CUR" is allowed but is redundant (you don't need any parameter at > v2.A1
all to specify the current text window).  Note that the line is       > v2.A1
cleared from the current cursor location (inclusive) to the end of    > v2.A1
the line.  If the respective window is disabled then nothing happens. > v2.A1
                                                                      > v2.A1
     Example:  $TWERASEEOL(5)$                                        > v2.A1
     Returns:  nothing                                                > v2.A1

$STYLE(styleno)$ ... Select graphics style as active style            > v2.A1
----------------------------------------------------------            > v2.A1
This command allows you to specify a graphical style slot to activate > v2.A1
as the current style.  Once activated, all subsequent graphics        > v2.A1
operations will use the graphics operations defined for that style    > v2.A1
(ie, fonts, color, patterns, etc).  If you do not specify the styleno > v2.A1
parameter then the current style slot that is in use will be returned > v2.A1
as a number from 0-35.                                                > v2.A1
                                                                      > v2.A1
     Example:  $STYLE(4)$                                             > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$TEXTWIN(slot)$ ... Select text window slot as active window          > v2.A1
------------------------------------------------------------          > v2.A1
This command allows you to activate a particular text window slot     > v2.A1
number as the currently active text window.  All subsequently         > v2.A1
received raw text will be directed to the specified window (providing > v2.A1
that window isn't disabled).  If you omit the slot number then this   > v2.A1
command returnes the current text window slot number in use as a      > v2.A1
number from 0-35.                                                     > v2.A1
                                                                      > v2.A1
     Example:  $TWSET(5)$                                             > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$VIEWPORT(slot)$ ... Select viewport slot as active viewport          > v2.A1
------------------------------------------------------------          > v2.A1
This command selects a particular graphics viewport slot number as    > v2.A1
the active graphics viewport.  All subsequent graphical operations    > v2.A1
will be directed to this viewport (unless that window is disabled).   > v2.A1
If you omit the slot parameter then the viewport slot number that is  > v2.A1
current will be returned as a number from 0-35.                       > v2.A1
                                                                      > v2.A1
     Example:  $VIEWSET(4)$                                           > v2.A1
     Returns:  nothing                                                > v2.A1

$DELAY(time)$ ... Delay for a number of milliseconds                  > v2.A1
----------------------------------------------------                  > v2.A1
This command causes a delay to occur.  During this time, the terminal > v2.A1
program "stops" everything except for possible animation activity.    > v2.A1
The TIME parameter must be specified.  Its value is specified in      > v2.A1
60ths of a second.  This command is useful to pause for a short time  > v2.A1
for things like prompts to go by or whatever.                         > v2.A1                                 > v2.A1
                                                                      > v2.A1
     Example:  $DELAY(60)$                                            > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$ANIMSTATUS$ ... Returns the status of the current animation          > v2.A1
------------------------------------------------------------          > v2.A1
This command returns the status of the current animation.  The        > v2.A1
possible return values and their meanings is as follows:              > v2.A1
                                                                      > v2.A1
           Value      Description                                     > v2.A1
          -----------------------------------------------------       > v2.A1
             NONE ... No animation defined                            > v2.A1
           ACTIVE ... Animation is in progress (active)               > v2.A1
           PAUSED ... Animation is paused (object is displayed)       > v2.A1
          STOPPED ... Animation is stopped (object not visible)       > v2.A1
                                                                      > v2.A1
     Example:  $ANIMSTATUS$                                           > v2.A1
     Returns:  ACTIVE                                                 > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$ANIMSTART$ ... Resumes an animation                                  > v2.A1
------------------------------------                                  > v2.A1
This command starts up an animation that was previously stopped or    > v2.A1
paused.  If the animation object isn't visible then it is drawn to    > v2.A1
the screen.  If it is visible then animation simply proceeds where it > v2.A1
was paused.  If no animation is defined then this command does        > v2.A1
nothing.                                                              > v2.A1
                                                                      > v2.A1
     Example:  $ANIMSTART$                                            > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$ANIMSTOP$ ... Stops an animation (erases object)                     > v2.A1
-------------------------------------------------                     > v2.A1
This command stops an animation in its tracks.  The animation object  > v2.A1
is removed from the screen, restoring whatever was behind it at the   > v2.A1
time.  If no animation is defined or the animation is already stopped > v2.A1
then this command does nothing.  If the animation is already paused   > v2.A1
then this command removes its object from the screen.                 > v2.A1
                                                                      > v2.A1
     Example:  $ANIMSTOP$                                             > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$ANIMPAUSE$ ... Pause an animation (doesn't erase object)             > v2.A1
---------------------------------------------------------             > v2.A1
This command pauses an animation.  The animation object remains on    > v2.A1
the screen, presumably to have the animation restored shortly.  If no > v2.A1
animation is defined, or it is already stopped/paused, then this      > v2.A1
command does nothing.                                                 > v2.A1
                                                                      > v2.A1
     Example:  $ANIMPAUSE$                                            > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1

$ANIMRESET$ ... Resets animation to the beginning                     > v2.A1
-------------------------------------------------                     > v2.A1
This command starts the animation over from the very beginning.  The  > v2.A1
animation actually begins, is drawn to the screen and things start to > v2.A1
go as normal.  If the animation was already active then its object is > v2.A1
removed from its current position and everything is reset back to the > v2.A1
beginning.  If no animation is currently defined then this command    > v2.A1
does nothing.                                                         > v2.A1
                                                                      > v2.A1
     Example:  $ANIMRESET$                                            > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$TERMNAME$ ... Returns the name of the RIPscrip terminal program      > v2.A1
----------------------------------------------------------------      > v2.A1
This text variable will return the name of the software package that  > v2.A1
is being used as the RIPscrip terminal.  The value that is returned   > v2.A1
will be different for different manufacturer's products.              > v2.A1
TeleGrafix's response to this command will be "RIPterm".              > v2.A1
                                                                      > v2.A1
     Example:  $TERMNAME$                                             > v2.A1
     Returns:  RIPterm                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$TERMVER$ ... Returns the version number of the RIPscrip terminal     > v2.A1
-----------------------------------------------------------------     > v2.A1
This is another vendor-specific text variable.  It is used to query   > v2.A1
the version number of the terminal being used by the caller.  This    > v2.A1
version number is not the same as the $RIPVER$ variable which is used > v2.A1
to query the version of RIPscrip that is supported.  The version      > v2.A1
number is the actual official version number of the software package  > v2.A1
itself (not the RIPscrip revision supported).  For TeleGrafix's       > v2.A1
RIPterm program, this response will be "2.00.00".                     > v2.A1
                                                                      > v2.A1
     Example:  $TERMVER$                                              > v2.A1
     Returns:  2.00.00                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$TERMMFG$ ... Returns the manufacturer's name of the terminal         > v2.A1
-------------------------------------------------------------         > v2.A1
This is another vendor-specific text variable.  It returns the name   > v2.A1
of the manufacturer who created the terminal program.  For the        > v2.A1
RIPterm product, this response will be "TeleGrafix Communications,    > v2.A1
Inc.".  This will obviously be different for different vendors (eg,   > v2.A1
"Mustang Software, Inc.", "deltaComm Development", etc.               > v2.A1
                                                                      > v2.A1
     Example:  $TERMMFG$                                              > v2.A1
     Returns:  TeleGrafix Communications, Inc.                        > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$TERMDATA$ ... Returns vendor specific data (freeform)                > v2.A1
------------------------------------------------------                > v2.A1
This is the last-vendor specific text variable.  The purpose of this  > v2.A1
variable is entirely up to the discretion of the vendor.  It can      > v2.A1
return any kind of information the terminal wishes.  This might       > v2.A1
return things like supported ANSI modes, supported protocols, or just > v2.A1
about anything that the terminal wants to send.  This is used so that > v2.A1
vendors can supply particular bits of information to the host once    > v2.A1
the host knows who's terminal it is, what version it is and so on.    > v2.A1
RIPterm currently returns the sequence "<none>".  If a terminal       > v2.A1
vendor does not use this variable then the generic "<none>" value     > v2.A1
should be returned.                                                   > v2.A1
                                                                      > v2.A1
     Example:  $TERMDATA$                                             > v2.A1
     Returns:  <none>                                                 > v2.A1

$COORDSIZE(size)$ ... Set the byte-size of X/Y coordinates            > v2.A1
----------------------------------------------------------            > v2.A1
This command allows you alter the byte-size of X/Y coordinates in     > v2.A1
subsequent RIPscrip commands.  It is identical in nature to the       > v2.A1
RIP_SET_COORDINATE_SIZE command, except that this command allows you  > v2.A1
to alter the setting from within a host command.  Typical settings    > v2.A1
for this will be 2, 3 or 4.  If the size parameter is omitted, then   > v2.A1
the current coordinate size setting is returned as a number.          > v2.A1
                                                                      > v2.A1
     Example:  $COORDSIZE(2)$                                         > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$WORLDSET(width,height)$ ... Sets the World coordinate frame's size   > v2.A1
-------------------------------------------------------------------   > v2.A1
This command allows you to alter the width and height of the world    > v2.A1
coordinate frame.  This might be useful if a button takes you to an   > v2.A1
area of the host where some piece of header information wasn't        > v2.A1
provided in the RIPscrip code and you need to set it before going     > v2.A1
there.  This command is identical in nature to the                    > v2.A1
RIP_SET_WORLD_FRAME command.  If you do not specify any parameters at > v2.A1
all, then the default values for this depend on what the base math    > v2.A1
setting is.  If MegaNums are currently in use, then the world frame   > v2.A1
is set to 1296x972.  If it is UltraNums, it is set to 4096x3072.      > v2.A1
                                                                      > v2.A1
     Example:  $WORLDSET(1000,1000)$                                  > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$WORLDCOMPAT$ ... Sets the world frame to compatible mode (640x350)   > v2.A1
-------------------------------------------------------------------   > v2.A1
This command is similar in nature to the $WORLDSET$ command except    > v2.A1
that its purpose is for backward compatibility operation.  Using this > v2.A1
command sets the world coordinate frame to the older 640x350          > v2.A1
resolution for use with earlier RIPscrip 1.x format files which had   > v2.A1
no idea what a world frame was.  Use this mode when branching off to  > v2.A1
a 1.x RIPscrip file.                                                  > v2.A1
                                                                      > v2.A1
     Example:  $WORLDCOMPAT$                                          > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$RESETHARD$ ... Performs a hard reset                                 > v2.A1
-------------------------------------                                 > v2.A1
Performs a hard reset of the environment.  This resets everything     > v2.A1
including clearing all save/restore slots and slot-less areas.  See   > v2.A1
the RIP_HEADER command for a complete description of a hard reset.    > v2.A1
                                                                      > v2.A1
     Example:  $RESETHARD$                                            > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$KCB$(page1,page2,...) ... Kills a particular clipboard page          > v2.A1
------------------------------------------------------------          > v2.A1
This command clears a specific page from the clipboard.  This makes   > v2.A1
it so that the specified page in the clipboard no longer exists.  If  > v2.A1
an operation attempts to paste that clipboard page onto the screen,   > v2.A1
it will fail.  You may specify "ALL" instead of a page number to      > v2.A1
explicitly destroy all clipboard pages at once.  To kill more then    > v2.A1
one page at the same time without killing all pages, simply specify   > v2.A1
more then one page number parameter.                                  > v2.A1
                                                                      > v2.A1
     Example:  $KCB(5)$                                               > v2.A1
     Returns:  nothing                                                > v2.A1

$KQUERY(which,slot_no) ... Kills a particular resident query          > v2.A1
------------------------------------------------------------          > v2.A1
This command allows you to delete the definition of one or more       > v2.A1
resident query expressions.  The WHICH parameter determines which     > v2.A1
resident queries are to be erased.  A value of "ALL" will delete all  > v2.A1
resident queries.  Possible values for the WHICH parameter are:       > v2.A1
                                                                      > v2.A1
         ALL ... Delete all resident queries currently defined        > v2.A1
     CURVIEW ... Delete the "current viewport" query                  > v2.A1
     CURTEXT ... Delete the "current text window" query               > v2.A1
        VIEW ... Delete a specific viewport's query                   > v2.A1
        TEXT ... Delete a specific text window's query                > v2.A1
                                                                      > v2.A1
ALL, CURVIEW and CURTEXT do not utilize the SLOT_NO parameter, so it  > v2.A1
can safely be omitted in these cases.  For the VIEW and TEXT          > v2.A1
selections, you need to specify a viewport/window slot number for the > v2.A1
viewport or text window to clear.  You can specify a value of ALL for > v2.A1
the slot number if you wish to delete all specific viewport or text   > v2.A1
window queries.                                                       > v2.A1
                                                                      > v2.A1
     Example:  $KQUERY(VIEW, 10)$                                     > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$KSAVE(which)$ ... Kills particular slot-less save region             > v2.A1
---------------------------------------------------------             > v2.A1
This command allows you to delete a particular slot-less save region. > v2.A1
You may specify one of several types of slot-less data types to       > v2.A1
delete, or you may specify ALL to delete all slot-less save regions   > v2.A1
at once for all data types.  If you do not specify a WHICH parameter, > v2.A1
then all slot-less regions are deleted.  The possible WHICH parameters> v2.A1
are:                                                                  > v2.A1
                                                                      > v2.A1
             ALL ... Delete all slot-less regions (default).          > v2.A1
           MOUSE ... Delete only the saved mouse field region         > v2.A1
            TEXT ... Delete only the saved text window region         > v2.A1
            CLIP ... Delete only the saved clipboard region           > v2.A1
          SCREEN ... Delete only the saved graphics screen region     > v2.A1
                                                                      > v2.A1
     Example:  $KSAVE(MOUSE)$                                         > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$SOUNDSTOP$ ... Stops playing any sound or music                      > v2.A1
------------------------------------------------                      > v2.A1
This command will stop any currently running sound or musical score.  > v2.A1
                                                                      > v2.A1
     Example:  $SOUNDSTOP$                                            > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$CLS$ ... Clears the entire screen to background color (no reset)     > v2.A1
-----------------------------------------------------------------     > v2.A1
This command physically erases the entire screen to the current       > v2.A1
background color (color #0).  No resetting of anything is performed.  > v2.A1
All this does is simply clear the screen.                             > v2.A1
                                                                      > v2.A1
     Example:  $CLS$                                                  > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1

$DVP(which1,which2,...) ... Disables a particular viewport definition > v2.A1
--------------------------------------------------------------------- > v2.A1
This command allows you to disable a particular viewport definition.  > v2.A1
If the definition happens to be the current definition, then all      > v2.A1
graphical output will stop.  The possible settings for the WHICH      > v2.A1
command are:                                                          > v2.A1
                                                                      > v2.A1
            ALL ... Disable all viewports at once                     > v2.A1
            CUR ... Disable only the current viewport                 > v2.A1
         number ... Disable a particular viewport slot number         > v2.A1
                                                                      > v2.A1
To disable more then one slot at the same time without disable        > v2.A1
all slots, simply specify more then one slot number parameter.        > v2.A1
                                                                      > v2.A1
     Example:  $DVP(CUR)$                                             > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$AVP(which1,which2,...)$ ... Activates a viewport definition          > v2.A1
------------------------------------------------------------          > v2.A1
This command does the exact opposite of the $DVP$ text variable which > v2.A1
disables a viewport.  When a viewport is activated, it no longer      > v2.A1
discards graphical commands that are sent to it.  This does not make  > v2.A1
any visual changes on the screen immediately - they only affect       > v2.A1
subsequent graphical RIPscrip operations that are received when that  > v2.A1
viewport is selected as the current viewport.  You may activate more  > v2.A1
then one viewport by specifying multiple viewport slot numbers.  You  > v2.A1
may also specify the following:                                       > v2.A1
                                                                      > v2.A1
            ALL ... Activate all viewports at once                    > v2.A1
            CUR ... Activate only the current viewport                > v2.A1
                                                                      > v2.A1
     Example:  $AVP(CUR)$                                             > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$MVP(which1,which2,...) ... Maximizes viewport to full screen         > v2.A1
-------------------------------------------------------------         > v2.A1
This command will take the specified viewport and make it full-screen > v2.A1
regardless of its current settings.  This does not affect any current > v2.A1
graphics on the screen, only the internal viewport definition.  The   > v2.A1
possible settings for the WHICH parameter are:                        > v2.A1
                                                                      > v2.A1
            ALL ... Maximize all viewports at once                    > v2.A1
            CUR ... Maximize only the current viewport                > v2.A1
         number ... Maximize a particular viewport slot number        > v2.A1
                                                                      > v2.A1
To maximize more then one slot at the same time without maximizing    > v2.A1
all slots, simply specify more then one slot number parameter.        > v2.A1
                                                                      > v2.A1
     Example:  $MVP(5)$                                               > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1

$MTW(which1,which2,...) ... Maximizes text window to full screen      > v2.A1
----------------------------------------------------------------      > v2.A1
This command maximizes a particular text window to full screen using  > v2.A1
whatever text window font is associated with that text window.  This  > v2.A1
does not affect any text that is already on the screen, only the      > v2.A1
internal definition of the text window (any scroll margins are        > v2.A1
reset).  The cursor is moved to the home position and enabled.  ANSI  > v2.A1
color attributes are not changed.  The possible settings for the      > v2.A1
WHICH parameter are:                                                  > v2.A1
                                                                      > v2.A1
            ALL ... Maximize all text windows at once                 > v2.A1
            CUR ... Maximize only the current text window             > v2.A1
         number ... Maximize a particular text window slot number     > v2.A1
                                                                      > v2.A1
To maximize more then one slot at the same time without maximizing    > v2.A1
all slots, simply specify more then one slot number parameter.        > v2.A1
                                                                      > v2.A1
     Example:  $MTW(ALL)$                                             > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$KGS(which1,which2,...) ... Kills a particular graphical style slot   > v2.A1
-------------------------------------------------------------------   > v2.A1
This command clears a particular graphical style slot.  By clearing,  > v2.A1
we mean that it is reset to default parameters (same thing that would > v2.A1
happen if a hard or soft reset were performed).  The possible values  > v2.A1
of the WHICH parameter are:                                           > v2.A1
                                                                      > v2.A1
            ALL ... Kill all graphical style slots                    > v2.A1
            CUR ... Kill only the current graphical style slot        > v2.A1
         number ... Kill a particular graphical style slot number     > v2.A1
                                                                      > v2.A1
To kill more then one slot at the same time without killing all       > v2.A1
slots, simply specify more then one slot number parameter.            > v2.A1
                                                                      > v2.A1
     Example:  $KGS(10)$                                              > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$KBS(which1,which2,...) ... Kills a particular button style slot      > v2.A1
----------------------------------------------------------------      > v2.A1
This command deletes the internal definition of a particular Button   > v2.A1
style slot.  By deleting, we mean that the button style that is       > v2.A1
defined for the associated slot number is deleted and any buttons     > v2.A1
that are attempted will fail because of no button style defined.      > v2.A1
The possible values for the WHICH parameter are:                      > v2.A1
                                                                      > v2.A1
            ALL ... Kill all button style slots                       > v2.A1
            CUR ... Kill only the current button style slot           > v2.A1
         number ... Kill a particular button style slot number        > v2.A1
                                                                      > v2.A1
To kill more then one slot at the same time without killing all       > v2.A1
slots, simply specify more then one slot number parameter.            > v2.A1
                                                                      > v2.A1
     Example:  $KBS(CUR)$                                             > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1

$CLIPINUSE(which)$ ... Is a clipboard page/slot in use?               > v2.A1
------------------------------------------------------                > v2.A1
This command allows you to determine if a particular clipboard slot   > v2.A1
(page) number is in use.  If it is, then a return value of "YES" is   > v2.A1
sent to the host.  A "NO" is sent if the slot is not in use.  If you  > v2.A1
specify a WHICH command of "COUNT" then this command returns a number > v2.A1
which indicates how many slots are currently defined and in use.      > v2.A1
If you omit the WHICH parameter, then this command returns the first  > v2.A1
slot number that is not in use.                                       > v2.A1
                                                                      > v2.A1
     Example:  $CLIPINUSE(10)$                                        > v2.A1
     Returns:  NO                                                     > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$CLIPSAVEOK(which,x0,y0,x1,y1)$ ... Can data be stored to clipboard?  > v2.A1
--------------------------------------------------------------------  > v2.A1
This command is intended to find out if a particular screen region    > v2.A1
can be stored onto a clipboard slot.  All five parameters must be     > v2.A1
specified.  The WHICH parameter determines which clipboard slot is to > v2.A1
contain the clipboard image.  The remaining X/Y coordinates define    > v2.A1
the upper left and lower right coordinates of the image area in the   > v2.A1
current viewport (in viewport coordinates).  If there is sufficient   > v2.A1
memory to store the image onto the desired clipboard page, this       > v2.A1
command returns a "YES".  A "NO" is returned if there isn't enough    > v2.A1
memory to store the image onto the clipboard page.                    > v2.A1
                                                                      > v2.A1
     Example:  $CLIPSAVEOK(5,10,10,50,50)$                            > v2.A1
     Returns:  YES                                                    > v2.A1


$CLIP2CLIPOK(which1,which2)$ ... Can one clipboard page be copied?    > v2.A1
------------------------------------------------------------------    > v2.A1
This command determines if one clipboard page can be successfully     > v2.A1
copied over another page.  If there is sufficient memory to make the  > v2.A1
copy, then this command returns a value of "YES".  If insufficient    > v2.A1
memory exists for the copy, this command returns "NO".                > v2.A1
                                                                      > v2.A1
     Example:  $CLIP2CLIPOK(4, 5)$                                    > v2.A1
     Returns:  YES                                                    > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$CLIP2CLIP(src,which1,which2,...)$ ... Copies clipboard page to page  > v2.A1
--------------------------------------------------------------------  > v2.A1
This command copies a clipboard page from one page number (slot) to   > v2.A1
another.  SRC specifies the source page slot and WHICH1 is the        > v2.A1
destination slot.  If the source page is empty then the destination   > v2.A1
page is deleted (if any).  If there is insufficient memory to contain > v2.A1
the duplicated page, nothing happens.  Use the $CLIP2CLIPOK$ variable > v2.A1
to determine if there is sufficient space for the copy.  Note, both   > v2.A1
parameters are required.                                              > v2.A1
                                                                      > v2.A1
To make multiple identical copies of the source clipboard slot into   > v2.A1
multiple destination slots, simply specify more then one destination  > v2.A1
slot number parameter.  To make all identical copies of the           > v2.A1
source slot, specify a destination slot of ALL.                       > v2.A1
                                                                      > v2.A1
     Example:  $CLIP2CLIP(3, 4)$                                      > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1

$PROTCLIP(which)$ ... Protects a particular clipboard slot number     > v2.A1
-----------------------------------------------------------------     > v2.A1
This command will protect a particular clipboard page slot from being > v2.A1
cleared or overwritten.  If you specify a WHICH value from 0-35 then  > v2.A1
you are protecting a specific clipboard page/slot.  Once a page is    > v2.A1
protected, it is considered non-vacant.  You may specify a value of   > v2.A1
ALL to protect all clipboard pages at once.  If you omit the WHICH    > v2.A1
parameter, then this command defaults to ALL and protects all         > v2.A1
clipboard pages.                                                      > v2.A1
                                                                      > v2.A1
     Example:  $PROTCLIP(10)$                                         > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$UNPROTCLIP(which)$ ... Unprotects a particular clipboard slot number > v2.A1
--------------------------------------------------------------------- > v2.A1
This command unprotects a particular clipboard page (from 0-35).      > v2.A1
Once a clipboard page is unprotected, it can then be deleted or       > v2.A1
overwritten.  You may also specify a value of ALL to unprotect all    > v2.A1
clipboard pages at once.  If you omit the WHICH parameter, then a     > v2.A1
default value of ALL will be assumed which will unprotect all entries > v2.A1
at once.                                                              > v2.A1
                                                                      > v2.A1
     Example:  $UNPROTCLIP(ALL)$                                      > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$ISCLIPPROT(which)$ ... Is a clipboard slot protected?                > v2.A1
------------------------------------------------------                > v2.A1
This command determines if a particular clipboard page/slot is        > v2.A1
currently protected or not.  If the specified slot (0-35) is          > v2.A1
currently protected, then this command returns "YES".  If it isn't    > v2.A1
protected, it returns "NO".  You may specify ALL for the WHICH        > v2.A1
parameter, or omit the WHICH parameter, all slots are checked to see  > v2.A1
if any are protected.  If even one of them is protected, YES is       > v2.A1
returned.  If none of them are protected, NO is returned.             > v2.A1
                                                                      > v2.A1
     Example:  $ISCLIPPROT(10)$                                       > v2.A1
     Returns:  YES                                                    > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$VIEWINUSE(which)$ ... Is a viewport slot in use?                     > v2.A1
------------------------------------------------                      > v2.A1
This command allows you to determine if a particular viewport slot    > v2.A1
number is in use.  If it is, then a return value of "YES" is sent to  > v2.A1
the host.  A "NO" is sent if the slot is not in use.  If you specify  > v2.A1
a WHICH command of "COUNT" then this command returns a number which   > v2.A1
indicates how many slots are currently defined and in use.  If you    > v2.A1
omit the WHICH parameter, then this command returns the first slot    > v2.A1
number that is not in use.                                            > v2.A1
                                                                      > v2.A1
     Example:  $VIEWINUSE$                                            > v2.A1
     Returns:  4                                                      > v2.A1

$VIEW2VIEW(src,which1,which2,...)$ ... Copies viewport slot to slot   > v2.A1
-------------------------------------------------------------------   > v2.A1
This command copies a viewport slot from one slot number to another.  > v2.A1
SRC specifies the source slot and WHICH1 is the destination slot.     > v2.A1
If the source slot is disabled then the destination page is disabled  > v2.A1
(if any).  Note, both parameters are required.                        > v2.A1
                                                                      > v2.A1
To make multiple identical copies of the source viewport slot into    > v2.A1
multiple destination slots, simply specify more then one destination  > v2.A1
slot number parameter.  To make all identical copies of the           > v2.A1
source slot, specify a destination slot of ALL.                       > v2.A1
                                                                      > v2.A1
     Example:  $VIEW2VIEW(3, 4)$                                      > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$PROTVIEW(which)$ ... Protects a particular viewport slot number      > v2.A1
-----------------------------------------------------------------     > v2.A1
This command will protect a particular viewport slot from being       > v2.A1
cleared or modified.  If you specify a WHICH value from 0-35 then you > v2.A1
are protecting a specific viewport slot.  Once a slot is protected,   > v2.A1
it is considered non-vacant.  You may specify a value of ALL to       > v2.A1
protect all viewport slots at once.  If you omit the WHICH parameter, > v2.A1
then this command defaults to ALL and protects all viewport slots.    > v2.A1
                                                                      > v2.A1
To protect more then one viewport slot in one operation, simply       > v2.A1
specify more then one viewport slot number parameter.                 > v2.A1
                                                                      > v2.A1
     Example:  $PROTVIEW(ALL)$                                        > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$UNPROTVIEW(which)$ ... Unprotects a particular viewport slot number  > v2.A1
--------------------------------------------------------------------- > v2.A1
This command unprotects a particular viewport slot (from 0-35). Once  > v2.A1
a viewport slot is unprotected, it can then be deleted or modified.   > v2.A1
You may also specify a value of ALL to unprotect all viewport slots   > v2.A1
at once.  If you omit the WHICH parameter, then a default value of    > v2.A1
ALL will be assumed which will unprotect all viewports at once.       > v2.A1
                                                                      > v2.A1
To unprotect more then one viewport slot in one operation, simply     > v2.A1
specify more then one viewport slot number parameter.                 > v2.A1
                                                                      > v2.A1
     Example:  $UNPROTVIEW(ALL)$                                      > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$ISVIEWPROT(which)$ ... Is a viewport slot protected?                 > v2.A1
------------------------------------------------------                > v2.A1
This command determines if a particular viewport slot is              > v2.A1
currently protected or not.  If the specified slot (0-35) is          > v2.A1
currently protected, then this command returns "YES".  If it isn't    > v2.A1
protected, it returns "NO".  You may specify ALL for the WHICH        > v2.A1
parameter, or omit the WHICH parameter, all slots are checked to see  > v2.A1
if any are protected.  If even one of them is protected, YES is       > v2.A1
returned.  If none of them are protected, NO is returned.             > v2.A1
                                                                      > v2.A1
     Example:  $ISVIEWPROT(10)$                                       > v2.A1
     Returns:  YES                                                    > v2.A1

$TEXTINUSE(which)$ ... Is a text window slot in use?                  > v2.A1
---------------------------------------------------                   > v2.A1
This command allows you to determine if a particular text window      > v2.A1
slot number is in use.  If it is, then a return value of "YES" is     > v2.A1
sent to the host.  A "NO" is sent if the slot is not in use.  If you  > v2.A1
specify a WHICH command of "COUNT" then this command returns a number > v2.A1
which indicates how many slots are currently defined and in use.      > v2.A1
If you omit the WHICH parameter, then this command returns the first  > v2.A1
slot number that is not in use.                                       > v2.A1
                                                                      > v2.A1
     Example:  $TEXTINUSE(COUNT)$                                     > v2.A1
     Returns:  14                                                     > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$TEXT2TEXT(src,which1,which2,...)$ ... Copies text slot to other slot > v2.A1
--------------------------------------------------------------------- > v2.A1
This command copies a text window slot from one slot number to        > v2.A1
another. SRC specifies the source slot and WHICH1 is the              > v2.A1
destination slot. If the source slot is disabled then the destination > v2.A1
slot is disabled (if any).  Note, both parameters are required.       > v2.A1
                                                                      > v2.A1
To make multiple identical copies of the source text window slot into > v2.A1
multiple destination slots, simply specify more then one destination  > v2.A1
slot number parameter.  To make all identical copies of the           > v2.A1
source slot, specify a destination slot of ALL.                       > v2.A1
                                                                      > v2.A1
     Example:  $TEXT2TEXT(3, 4)$                                      > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$PROTTEXT(which)$ ... Protects a particular text window slot number   > v2.A1
-------------------------------------------------------------------   > v2.A1
This command will protect a particular text window slot from being    > v2.A1
cleared or modified.  If you specify a WHICH value from 0-35 then you > v2.A1
are protecting a specific text window slot.  Once a slot is           > v2.A1
protected, it is considered non-vacant.  You may specify a value of   > v2.A1
ALL to protect all text windows slots at once.  If you omit the WHICH > v2.A1
parameter, then this command defaults to ALL and protects all text    > v2.A1
window slots.                                                         > v2.A1
                                                                      > v2.A1
To protect more then one text window slot in one operation, simply    > v2.A1
specify more then one text window slot number parameter.              > v2.A1
                                                                      > v2.A1
     Example:  $PROTTEXT(ALL)$                                        > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1

$UNPROTTEXT(which1,which2,...)$ ... Unprotects a text window slot     > v2.A1
-----------------------------------------------------------------     > v2.A1
This command unprotects a particular text window slot (from 0-35).    > v2.A1
Once a text window slot is unprotected, it can then be deleted or     > v2.A1
modified. You may also specify a value of ALL to unprotect all text   > v2.A1
window slots at once.  If you omit the WHICH parameter, then a        > v2.A1
default value of ALL will be assumed which will unprotect all text    > v2.A1
windows at once.                                                      > v2.A1
                                                                      > v2.A1
To unprotect more then one text window slot in one operation, simply  > v2.A1
specify more then one text window slot number parameter.              > v2.A1
                                                                      > v2.A1
     Example:  $UNPROTTEXT(ALL)$                                      > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$ISTEXTPROT(which)$ ... Is a text window slot protected?              > v2.A1
--------------------------------------------------------              > v2.A1
This command determines if a particular text window slot is           > v2.A1
currently protected or not.  If the specified slot (0-35) is          > v2.A1
currently protected, then this command returns "YES".  If it isn't    > v2.A1
protected, it returns "NO".  You may specify ALL for the WHICH        > v2.A1
parameter, or omit the WHICH parameter, all slots are checked to see  > v2.A1
if any are protected.  If even one of them is protected, YES is       > v2.A1
returned.  If none of them are protected, NO is returned.             > v2.A1
                                                                      > v2.A1
     Example:  $ISVIEWPROT(10)$                                       > v2.A1
     Returns:  YES                                                    > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$STYLEINUSE(which)$ ... Is a graphical style slot in use?             > v2.A1
--------------------------------------------------------              > v2.A1
This command allows you to determine if a particular graphical style  > v2.A1
slot number is in use.  If it is, then a return value of "YES" is     > v2.A1
sent to the host.  A "NO" is sent if the slot is not in use.  If you  > v2.A1
specify a WHICH command of "COUNT" then this command returns a number > v2.A1
which indicates how many slots are currently defined and in use.      > v2.A1
If you omit the WHICH parameter, then this command returns the first  > v2.A1
slot number that is not in use.                                       > v2.A1
                                                                      > v2.A1
     Example:  $STYLEINUSE(0)$                                        > v2.A1
     Returns:  YES                                                    > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$STYLE2STYLE(src,which1,which2,...)$ ... Copies style slot to slot    > v2.A1
------------------------------------------------------------------    > v2.A1
This command copies a graphical style slot from one slot number to    > v2.A1
another.  SRC specifies the source slot and WHICH1 is the             > v2.A1
destination slot.  If the source slot is disabled then the            > v2.A1
destination slot is disabled (if any).  Note, both parameters are     > v2.A1
required.                                                             > v2.A1
                                                                      > v2.A1
You can make multiple identical copies of the source slot into        > v2.A1
several destination slots at the same time by supplying more then     > v2.A1
one destination slot number.  If you wish to make all style slots     > v2.A1
contain identical information as the source slot, specify a           > v2.A1
destination slot number of ALL.                                       > v2.A1
                                                                      > v2.A1
     Example:  $STYLE2STYLE(3, 4)$                                    > v2.A1
     Returns:  nothing                                                > v2.A1

$PROTSTYLE(which1,which2,...)$ ... Protects a style slot number       > v2.A1
---------------------------------------------------------------       > v2.A1
This command will protect a particular graphical style slot from      > v2.A1
being cleared or modified.  If you specify a WHICH value from 0-35    > v2.A1
then you are protecting a specific style slot.  Once a slot is        > v2.A1
protected, it is considered non-vacant.  You may specify a value of   > v2.A1
ALL to protect all style slots at once.  If you omit the WHICH        > v2.A1
parameter, then this command defaults to ALL and protects all style   > v2.A1
slots.                                                                > v2.A1
                                                                      > v2.A1
To protect more then one style slot number without specifying ALL,    > v2.A1
simply provide more then one slot number parameter.                   > v2.A1
                                                                      > v2.A1
     Example:  $PROTSTYLE(ALL)$                                       > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$UNPROTSTYLE(which1,which2,...)$ ... Unprotects a style slot number   > v2.A1
-------------------------------------------------------------------   > v2.A1
This command unprotects a particular graphical style slot (from 0-35).> v2.A1
Once a style slot is unprotected, it can then be deleted or           > v2.A1
modified.  You may also specify a value of ALL to unprotect all style > v2.A1
slots at once.  If you omit the WHICH parameter, then a default value > v2.A1
of ALL will be assumed which will unprotect all style slots at once.  > v2.A1
                                                                      > v2.A1
To unprotect more then one style slot at once without using the ALL   > v2.A1
parameter, simply specify more then one slot number parameter.        > v2.A1
                                                                      > v2.A1
     Example:  $UNPROTSTYLE(ALL)$                                     > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$ISSTYLEPROT(which)$ ... Is a style slot protected?                   > v2.A1
---------------------------------------------------                   > v2.A1
This command determines if a particular graphical style slot is       > v2.A1
currently protected or not.  If the specified slot (0-35) is          > v2.A1
currently protected, then this command returns "YES".  If it isn't    > v2.A1
protected, it returns "NO".  You may specify ALL for the WHICH        > v2.A1
parameter, or omit the WHICH parameter, all slots are checked to see  > v2.A1
if any are protected.  If even one of them is protected, YES is       > v2.A1
returned.  If none of them are protected, NO is returned.             > v2.A1
                                                                      > v2.A1
     Example:  $ISSTYLEPROT(10)$                                      > v2.A1
     Returns:  YES                                                    > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$BUTTONINUSE(which)$ ... Is a button style slot in use?               > v2.A1
------------------------------------------------------                > v2.A1
This command allows you to determine if a particular button style     > v2.A1
slot number is in use.  If it is, then a return value of "YES" is     > v2.A1
sent to the host.  A "NO" is sent if the slot is not in use.  If you  > v2.A1
specify a WHICH command of "COUNT" then this command returns a number > v2.A1
which indicates how many slots are currently defined and in use.      > v2.A1
If you omit the WHICH parameter, then this command returns the first  > v2.A1
slot number that is not in use.                                       > v2.A1
                                                                      > v2.A1
     Example:  $BUTTONINUSE$                                          > v2.A1
     Returns:  1                                                      > v2.A1

$BUTTON2BUTTON(src,which1,which2,...)$ ... Copies button slot to slot > v2.A1
--------------------------------------------------------------------- > v2.A1
This command copies a button style slot from one slot number to       > v2.A1
another.  SRC specifies the source slot and WHICH1 is the             > v2.A1
destination slot.  If the source slot is empty then the destination   > v2.A1
slot is empty (if any).  Note, both parameters are required.          > v2.A1
                                                                      > v2.A1
If you wish to make multiple identical copies of a button style slot  > v2.A1
into many destination style slots, simply specify multiple            > v2.A1
destination slot numbers or ALL to make all slots contain the same    > v2.A1
value.                                                                > v2.A1
                                                                      > v2.A1
     Example:  $BUTTON2BUTTON(3, 4)$                                  > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$PROTBUTTON(which1,which2,...)$ ... Protects a button slot number     > v2.A1
-----------------------------------------------------------------     > v2.A1
This command will protect a particular button style slot from being   > v2.A1
cleared or modified.  If you specify a WHICH value from 0-35 then you > v2.A1
are protecting a specific style slot.  Once a slot is protected, it   > v2.A1
is considered non-vacant.  You may specify a value of ALL to protect  > v2.A1
all style slots at once.  If you omit the WHICH parameter, then this  > v2.A1
command defaults to ALL and protects all style slots.                 > v2.A1
                                                                      > v2.A1
To protect more then one button slot at once without specifying ALL,  > v2.A1
you can specify more then one slot number parameter.                  > v2.A1
                                                                      > v2.A1
     Example:  $PROTBUTTON(ALL)$                                      > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$UNPROTBUTTON(which1,which2,...)$ ... Unprotects a button slot number > v2.A1
--------------------------------------------------------------------- > v2.A1
This command unprotects a particular button style slot (from 0-35).   > v2.A1
Once a style slot is unprotected, it can then be deleted or           > v2.A1
modified.  You may also specify a value of ALL to unprotect all style > v2.A1
slots at once.  If you omit the WHICH parameter, then a default value > v2.A1
of ALL will be assumed which will unprotect all style slots at once.  > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
You can unprotect multiple button style slots at once by specifying   > v2.A1
more then one slot number (eg, $UNPROTBUTTON(1,3,5)$).                > v2.A1
                                                                      > v2.A1
     Example:  $UNPROTBUTTON(ALL)$                                    > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$ISBUTTONPROT(which)$ ... Is a button slot protected?                 > v2.A1
-----------------------------------------------------                 > v2.A1
This command determines if a particular button style slot is          > v2.A1
currently protected or not.  If the specified slot (0-35) is          > v2.A1
currently protected, then this command returns "YES".  If it isn't    > v2.A1
protected, it returns "NO".  You may specify ALL for the WHICH        > v2.A1
parameter, or omit the WHICH parameter, all slots are checked to see  > v2.A1
if any are protected.  If even one of them is protected, YES is       > v2.A1
returned.  If none of them are protected, NO is returned.             > v2.A1
                                                                      > v2.A1
     Example:  $ISBUTTONPROT(10)$                                     > v2.A1
     Returns:  YES                                                    > v2.A1

$SLOTINUSE(type,which)$ ... Is a slot save area in use?               > v2.A1
-------------------------------------------------------               > v2.A1
This command allows you to determine if a particular slot save region > v2.A1
is currently holding some data.  You are allowed to specify a         > v2.A1
particular slot data type to inquire about.  If you specify a value   > v2.A1
of "ALL", then this command checks all data types for the slot number > v2.A1
you requested.  If any of them are holding data then a "YES" is       > v2.A1
returned.  Otherwise a "NO" is returned to indicate the given slot is > v2.A1
vacant.  If you omit the WHICH parameter which normally indicates     > v2.A1
which slot number to inquire about, then the first available empty    > v2.A1
slot is returned.  You may specify a WHICH parameter of COUNT to      > v2.A1
return the number of slots that are in use (completly or partially).  > v2.A1
If no parameters are specified, then a type of ALL will be assumed    > v2.A1
and the first available vacant slot number will be returned as a      > v2.A1
number from 0-9.  The possible values for TYPE are:                   > v2.A1
                                                                      > v2.A1
             ALL ... All data types                                   > v2.A1
           MOUSE ... Mouse field type                                 > v2.A1
            TEXT ... Text window type                                 > v2.A1
            CLIP ... Clipboard type                                   > v2.A1
          SCREEN ... Graphical screen type                            > v2.A1
                                                                      > v2.A1
     Example:  $SLOTINUSE(CLIP,5)$                                    > v2.A1
     Returns:  NO                                                     > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$SLOTLESSINUSE$(type)$ ... Is slotless save area in use?              > v2.A1
--------------------------------------------------------              > v2.A1
This command determines if a particular slot-less save area is in use > v2.A1
or not.  If the designated area is holding some data, then a "YES" is > v2.A1
returned to indicate that it is currently in use.  A "NO" value means > v2.A1
the area is vacant.  You may specify a type of ALL to indicate that   > v2.A1
you wish to see if any of the slotless areas are in use.  Specifying  > v2.A1
no type parameter implies a default value of ALL and a YES or NO is   > v2.A1
returned to indicate whether any slot-less areas are currently in     > v2.A1
use.  The possible values for TYPE are:                               > v2.A1
                                                                      > v2.A1
             ALL ... All data types                                   > v2.A1
           MOUSE ... Mouse field type                                 > v2.A1
            TEXT ... Text window type                                 > v2.A1
            CLIP ... Clipboard type                                   > v2.A1
          SCREEN ... Graphical screen type                            > v2.A1
                                                                      > v2.A1
     Example:  $SLOTLESSINUSE(CLIP)$                                  > v2.A1
     Returns:  YES                                                    > v2.A1

$SLOT2SLOTLESS(type,which)$ ... Move slot number to slotless area     > v2.A1
-----------------------------------------------------------------     > v2.A1
This command transfers some data from a saved slot to the slot-less   > v2.A1
area for that data type.  The TYPE and WHICH parameters are required  > v2.A1
for this command.  All data from the specified slot TYPE is copied    > v2.A1
from the slot region to the slot-less region.  If you specify a TYPE  > v2.A1
of ALL then all data objects in that slot are copied to the slot-less > v2.A1
area.  Otherwise, only the particular data type is copied.  If the    > v2.A1
slot is currently blank, then the slot-less area(s) are cleared as    > v2.A1
well.  The possible values of the TYPE parameter are:                 > v2.A1
                                                                      > v2.A1
             ALL ... All data types                                   > v2.A1
           MOUSE ... Mouse field type                                 > v2.A1
            TEXT ... Text window type                                 > v2.A1
            CLIP ... Clipboard type                                   > v2.A1
          SCREEN ... Graphical screen type                            > v2.A1
                                                                      > v2.A1
     Example:  $SLOT2SLOTLESS(MOUSE,4)$                               > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$SLOT2SLOT(type,src,which1,which2,...)$ ... Move slot to another slot > v2.A1
--------------------------------------------------------------------- > v2.A1
This command is similar to $SLOT2SLOTLESS$ except that instead of     > v2.A1
copying the data from one slot to a slot-less area, the data is       > v2.A1
copied to another slot.  The TYPE parameter can be set to ALL to copy > v2.A1
all data types from slot SRC1 to slot WHICH1.  The two which          > v2.A1
parameter must be supplied.  The possible data types for the TYPE     > v2.A1
parameter are:                                                        > v2.A1
                                                                      > v2.A1
             ALL ... All data types                                   > v2.A1
           MOUSE ... Mouse field type                                 > v2.A1
            TEXT ... Text window type                                 > v2.A1
            CLIP ... Clipboard type                                   > v2.A1
          SCREEN ... Graphical screen type                            > v2.A1
                                                                      > v2.A1
You can make more then one copy of the source slot and place them     > v2.A1
into multiple destination slots.  To do so, simply specify more then  > v2.A1
one destination slot number after the first destination slot.  You    > v2.A1
may specify ALL to make copies of the data into all slots.            > v2.A1
                                                                      > v2.A1
     Example:  $SLOT2SLOT(ALL, 5, 3)$                                 > v2.A1
     Returns:  nothing                                                > v2.A1

$SLOTLESS2SLOT(type,which1,which2,...)$ ... Move slotless to slot(s)  > v2.A1
--------------------------------------------------------------------  > v2.A1
This command is the opposite to the $SLOT2SLOTLESS$ text variable in  > v2.A1
that it moves (copies) one or more pieces of data from the slot-less  > v2.A1
save region into a particular slot number.  The TYPE and WHICH        > v2.A1
parameters are required for this command to function.  If any data    > v2.A1
type segment of the slot-less save area are vacant, then the          > v2.A1
corresponding data type area in the slot area is cleared as well.     > v2.A1
The possible values for the TYPE parameter are:                       > v2.A1
                                                                      > v2.A1
             ALL ... All data types                                   > v2.A1
           MOUSE ... Mouse field type                                 > v2.A1
            TEXT ... Text window type                                 > v2.A1
            CLIP ... Clipboard type                                   > v2.A1
          SCREEN ... Graphical screen type                            > v2.A1
                                                                      > v2.A1
You can also move the slotless are to more then one slot at the       > v2.A1
same time by specifying multiple destination slots in the WHICH2      > v2.A1
and beyond parameters (eg, $SLOTLESS2SLOT(CLIP,2,3,4,5)$ makes        > v2.A1
four copies of the slotless clipboard area into slots 2, 3, 4 and 5.  > v2.A1
If you use ALL as the destination slot, then you are making copies    > v2.A1
of the slotless area into all destination slots.                      > v2.A1
                                                                      > v2.A1
     Example:  $SLOTLESS2SLOT(MOUSE,4)$                               > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$PROTSLOT(type,which1,which2,...)$ ... Protects a slot from deletion  > v2.A1
--------------------------------------------------------------------  > v2.A1
This command allows you to protect one or more data type segments of  > v2.A1
a slot save region.  This protection prevents unauthorized deletion   > v2.A1
of a particular slot number.  If a PUSH or POP operation occur that   > v2.A1
would normally affect the protected slot, the push or pop operation   > v2.A1
skips over the slot that is protected.  A protected slot is           > v2.A1
considered not-vacant regardless of whether it is holding any data or > v2.A1
not.  A hard reset of the RIPscrip environment will clear any         > v2.A1
protected slots and clear the protected attribute of them.  Normal    > v2.A1
soft resets and slot clearing will not clear protected slots.  The    > v2.A1
WHICH parameter normally should be set to a slot number from 0-9.     > v2.A1
You can specify a value of "ALL" to protect all slots at once.        > v2.A1
A protected slot cannot be the destionation of a $SLOTLESS2SLOT$      > v2.A1
operation.  The TYPE parameter can be set to any of the following     > v2.A1
data types:                                                           > v2.A1
                                                                      > v2.A1
             ALL ... All data types                                   > v2.A1
           MOUSE ... Mouse field type                                 > v2.A1
            TEXT ... Text window type                                 > v2.A1
            CLIP ... Clipboard type                                   > v2.A1
          SCREEN ... Graphical screen type                            > v2.A1
                                                                      > v2.A1
You can protect more then one slot without specifying ALL.  If        > v2.A1
you wish to do this, simply specify more then one slot number to      > v2.A1
protect (eg, $PROTSLOT(MOUSE,3,5,9,10)$).                             > v2.A1
                                                                      > v2.A1
     Example:  $PROTSLOT(MOUSE,4)$                                    > v2.A1
     Returns:  nothing                                                > v2.A1

$UNPROTSLOT(type,which1,which2,...)$ ... Unprotects a slot            > v2.A1
----------------------------------------------------------            > v2.A1
This command allows you to unprotect a slot save area.  This once     > v2.A1
again allows the slot to be cleared by a clear slot operation.        > v2.A1
This is the logical inverse to the $PROTSLOT$ function.  Once this is > v2.A1
executed, the specified slot can once again have data copied into it, > v2.A1
can be cleared, etc.  You may specify a WHICH area of ALL to          > v2.A1
unprotect all slot numbers at once.  The possible settings of the     > v2.A1
TYPE parameter are:                                                   > v2.A1
                                                                      > v2.A1
             ALL ... All data types                                   > v2.A1
           MOUSE ... Mouse field type                                 > v2.A1
            TEXT ... Text window type                                 > v2.A1
            CLIP ... Clipboard type                                   > v2.A1
          SCREEN ... Graphical screen type                            > v2.A1
                                                                      > v2.A1
You can unprotect more then one slot without specifying ALL.  If      > v2.A1
you wish to do this, simply specify more then one slot number to      > v2.A1
unprotect (eg, $UNPROTSLOT(MOUSE,3,5,9,10)$).                         > v2.A1
                                                                      > v2.A1
     Example:  $UNPROTSLOT(ALL,ALL)$                                  > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$ISSLOTPROT(type,which)$ ... Is a slot area protected?                > v2.A1
------------------------------------------------------                > v2.A1
This command allows you to determine if a particular data area of a   > v2.A1
slot save area is protected or not.  If it is, then "YES" will be     > v2.A1
returned, otherwise "NO" will be sent.  A which value normally        > v2.A1
specifies which slot area you wish to check.  If you specify an ALL   > v2.A1
parameter (or omit the while parameter) then all slots are checked    > v2.A1
and if any are protected, "YES" will be returned.  A "NO" result in   > v2.A1
this situation indicates that there aren't any protected slots at     > v2.A1
this time.  Type TYPE field specifies which data type segment of a    > v2.A1
slot area you wish to check.  If a value of ALL is specified, then    > v2.A1
all data areas for that slot are checked - if even so much as one of  > v2.A1
those data areas is protected, then "YES" will be returned.  "NO"     > v2.A1
means that no data type in that slot area is protected.  The possible > v2.A1
values for the TYPE parameter are:                                    > v2.A1
                                                                      > v2.A1
             ALL ... All data types                                   > v2.A1
           MOUSE ... Mouse field type                                 > v2.A1
            TEXT ... Text window type                                 > v2.A1
            CLIP ... Clipboard type                                   > v2.A1
          SCREEN ... Graphical screen type                            > v2.A1
                                                                      > v2.A1
     Example:  $ISSLOTPROT(CLIP,5)$                                   > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1

$PROTSLOTLESS(type)$ ... Protect a slot-less area from deletion       > v2.A1
---------------------------------------------------------------       > v2.A1
This command allows you to protect one or more data type segments of  > v2.A1
a slot-less save region.  This protection prevents unauthorized       > v2.A1
deletion of a particular slot-less save area.  A protected area is    > v2.A1
considered not-vacant regardless of whether it is holding any data or > v2.A1
not.  A hard reset of the RIPscrip environment will clear any         > v2.A1
protected areas and clear the protected attribute of them.  Normal    > v2.A1
soft resets and slot-less clearing will not clear protected areas.  A > v2.A1
protected area cannot be the destionation of a $SLOTL2SLOTESS2$       > v2.A1
operation.  The TYPE parameter can be set to any of the following     > v2.A1
data types:                                                           > v2.A1
                                                                      > v2.A1
             ALL ... All data types                                   > v2.A1
           MOUSE ... Mouse field type                                 > v2.A1
            TEXT ... Text window type                                 > v2.A1
            CLIP ... Clipboard type                                   > v2.A1
          SCREEN ... Graphical screen type                            > v2.A1
                                                                      > v2.A1
     Example:  $PROTSLOT(MOUSE,4)$                                    > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$UNPROTSLOTLESS(type)$ ... Unprotects a slot-less area from deletion  > v2.A1
--------------------------------------------------------------------  > v2.A1
This command allows you to unprotect a slot-less save area.  This     > v2.A1
once again allows the area to be cleared by a clear slot-less area    > v2.A1
operation.  This is the logical inverse to the $PROTSLOTLESS$         > v2.A1
function.  Once this is executed, the specified area can once again   > v2.A1
have data copied into it, can be cleared, etc.  The possible settings > v2.A1
of the TYPE parameter are:                                            > v2.A1
                                                                      > v2.A1
             ALL ... All data types                                   > v2.A1
           MOUSE ... Mouse field slot                                 > v2.A1
            TEXT ... Text window slot                                 > v2.A1
            CLIP ... Clipboard slot                                   > v2.A1
          SCREEN ... Graphical screen slot                            > v2.A1
                                                                      > v2.A1
     Example:  $UNPROTSLOT(ALL,ALL)$                                  > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$ISSLOTLESSPROT(type)$ ... Is a slot area protected?                  > v2.A1
----------------------------------------------------                  > v2.A1
This command allows you to determine if a particular data area of the > v2.A1
slot-less save area is protected or not.  If it is, then "YES" will   > v2.A1
be returned, otherwise "NO" will be sent.  The TYPE field specifies   > v2.A1
which data type segment of the slot-less area you wish to check.  If  > v2.A1
a value of ALL is specified, then all data areas for that slot-less   > v2.A1
area are checked - if even so much as one of those data areas is      > v2.A1
protected, then "YES" will be returned.  "NO" means that no data type > v2.A1
in that area is protected.  The possible values for the TYPE          > v2.A1
parameter are:                                                        > v2.A1
                                                                      > v2.A1
             ALL ... All data types                                   > v2.A1
           MOUSE ... Mouse field type                                 > v2.A1
            TEXT ... Text window type                                 > v2.A1
            CLIP ... Clipboard type                                   > v2.A1
          SCREEN ... Graphical screen type                            > v2.A1
                                                                      > v2.A1
     Example:  $ISSLOTLESSPROT(CLIP,5)$                               > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1

$SCLID(id)$ ... Returns the scroller "id" number                      > v2.A1
------------------------------------------------                      > v2.A1
This variable is predominantly used to return the ID number for a     > v2.A1
particular scroller.  Technically, this command isn't truly required  > v2.A1
because its usefulness is when its used in a scroller's host command. > v2.A1
When you use this command in this situation, you already know the     > v2.A1
scroller's ID number.  But for an important aspect of generality,     > v2.A1
this command can be used in the scroller's host command to "look-up"  > v2.A1
the scroller's ID value (you wouldn't specify an ID parameter in      > v2.A1
these situations - although you could).                               > v2.A1
                                                                      > v2.A1
If you specify an ID parameter, then this command searches through    > v2.A1
the list of scrollers for the appropriate ID value.  When found, that > v2.A1
value is returned.  This could potentially be used in a host command  > v2.A1
for a mouse or button to return a scroller's ID value, but its use is > v2.A1
redundant technically - but theoretically, more recommendable in      > v2.A1
nature.                                                               > v2.A1
                                                                      > v2.A1
     Example:  $SCLID$                                                > v2.A1
     Returns:  5                                                      > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$SCLCUR(id,cur)$ ... Sets current entry number for a scroller         > v2.A1
-------------------------------------------------------------         > v2.A1
This text variable allows you to alter the current entry number       > v2.A1
associated with a particular scroller "id" number.  When the new      > v2.A1
current entry is recorded, the last "most recent" current entry       > v2.A1
setting is checked - if the new value differs from the older value    > v2.A1
then the thumb for the affected scroller is updated to the new        > v2.A1
position (the scroller's host command is not transmitted in this      > v2.A1
case).                                                                > v2.A1
                                                                      > v2.A1
If you omit the CUR parameter then the current entry number for the   > v2.A1
scroller is returned to the host.                                     > v2.A1
                                                                      > v2.A1
     Example:  $SCLCURSET(5,100)$                                     > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$SCLENT(id,tot)$ ... Sets total entries for a scroller                > v2.A1
------------------------------------------------------                > v2.A1
This command allows you to alter the total number of entries          > v2.A1
associated with a particular scroller "id" number.  If the new total  > v2.A1
entries differs from the number of entries in the scroller, then the  > v2.A1
thumb is updated to reflect the new proportional location of the      > v2.A1
current entry based on the total number of entries.  This command     > v2.A1
reuiqes both parameters.  Upon updating the scroller's total entries  > v2.A1
field, the host command for that scroller is not transmitted to the   > v2.A1
remote system.                                                        > v2.A1
                                                                      > v2.A1
If you omit the TOT parameter, then the total number of entries       > v2.A1
associated with the scroller is returned to the host.                 > v2.A1
                                                                      > v2.A1
     Example:  $SCLENTSET(9234,200)$                                  > v2.A1
     Returns:  nothing                                                > v2.A1

$SCLPAGE(id,size)$ ... Sets a scroller's page size                    > v2.A1
--------------------------------------------------                    > v2.A1
This command allows you to alter the page size increment/decrement    > v2.A1
value for a particular scroller "id" number.  This affects what       > v2.A1
happens when the user clicks on the page up or page down fields of a  > v2.A1
scroller.  When this command is received, the internal scroller       > v2.A1
definition is updated with the new page size parameter.  The thumb is > v2.A1
not updated (it doesn't need to be moved), and the scroller's host    > v2.A1
command is not sent to the remote system.                             > v2.A1
                                                                      > v2.A1
If the SIZE parameter is omitted then the current page size setting   > v2.A1
for the associated scroller is returned to the host.                  > v2.A1
                                                                      > v2.A1
     Example:  $SCLPAGESET(9234,20)$                                  > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$SCROLLER(id)$ ... Returns composite scroller information             > v2.A1
---------------------------------------------------------             > v2.A1
This command returns composite information on a specific scroller ID. > v2.A1
The ID number, total entries, current entry and page size settings    > v2.A1
are returned to the host as number separated by colons in the format: > v2.A1
                                                                      > v2.A1
          id_number:entries:current:page_size                         > v2.A1
                                                                      > v2.A1
     Example:  $SCROLLER(5)$                                          > v2.A1
     Returns:  5:100:50:10                                            > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$NULL$ ... A null text variable (returns nothing)                     > v2.A1
------------------------------------------------- This text variable  > v2.A1
is a special variable.  It always returns nothing to the host         > v2.A1
system.  It doesn't prompt the user or any information and it doesn't > v2.A1
set anything.  It is intended to be a place-holder for commands that  > v2.A1
require a text parameter (RIP_MOUSE, RIP_BUTTON, RIP_QUERY and        > v2.A1
RIP_SCROLLER).  When you have this text variable all by itself in a   > v2.A1
host command, it makes the host command do absolutely nothing, but    > v2.A1
has something defined for the host command to satisfy the RIPscrip    > v2.A1
interpreter (which expects something to be defined in host command    > v2.A1
text parameters).                                                     > v2.A1
                                                                      > v2.A1
     Example:  $NULL$                                                 > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1

$NOREFRESH$ ... Disables screen refresh expression                    > v2.A1
--------------------------------------------------                    > v2.A1
This command disables a host defined refresh expression.  When you do > v2.A1
this, the refresh option for the terminal is disabled and cannot be   > v2.A1
selected (or if it can be selected, does nothing).  This is           > v2.A1
equivalent to issuing a RIP_SET_REFRESH with a $NULL$ parameter to    > v2.A1
disable refreshing.                                                   > v2.A1
                                                                      > v2.A1
     Example:  $NOREFRESH$                                            > v2.A1
     Returns:  none                                                   > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$REFRESH$ ... Forces the terminal to transmit the refresh sequence    > v2.A1
------------------------------------------------------------------    > v2.A1
This text variable instructs the terminal to transmit the refresh     > v2.A1
host command to the remote host system if the refresh expression is   > v2.A1
non-NULL.  The host has the ability to set a refresh expression that  > v2.A1
will, when sent, redisplay the current screen.                        > v2.A1
                                                                      > v2.A1
     Example:  $REFRESH$                                              > v2.A1
     Returns:  ^m                                                     > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$SLOTREFRESH(slot1,slot2,...)$ ... Refreshes buttons using a slot     > v2.A1
-----------------------------------------------------------------     > v2.A1
This command allows you to refresh (re-display) all buttons that are  > v2.A1
defined using a particular button style slot.  The SLOT parameter     > v2.A1
specifies which slot number to refresh.  You may specify a value of   > v2.A1
ALL to refresh all buttons using any slot.                            > v2.A1
                                                                      > v2.A1
No parameters are required (ALL is assumed).  If you specify one or   > v2.A1
more parameters, each of them indicate a particular slot number to    > v2.A1
refresh.                                                              > v2.A1
                                                                      > v2.A1
     Example:  $SLOTREFRESH(1,5,10,12)$                               > v2.A1
     Returns:  nothing                                                > v2.A1


$ATW(which1,which2,...)$ ... Activates a text window definition       > v2.A1
---------------------------------------------------------------       > v2.A1
This command does the exact opposite of the $DTW$ text variable which > v2.A1
disables a text window.  When a window is activated, it no longer     > v2.A1
discards raw ANSI text that is sent to it.  This does not make        > v2.A1
any visual changes on the screen immediately unless the current text  > v2.A1
window is the one activated, whereby the cursor might appear all of a > v2.A1
sudden.  You may activate more then one windowt by specifying         > v2.A1
multiple text window slot numbers.  You may also specify the          > v2.A1
following:                                                            > v2.A1
                                                                      > v2.A1
            ALL ... Activate all viewports at once                    > v2.A1
            CUR ... Activate only the current viewport                > v2.A1
                                                                      > v2.A1
     Example:  $ATW(CUR)$                                             > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                     > v2.A1
$ENVSAVE$ ... Records (snapshots) environmental configuration         > v2.A1
-------------------------------------------------------------         > v2.A1
This command takes a snapshot of the RIPscrip configuration.  This    > v2.A1
includes recording the values of:                                     > v2.A1
                                                                      > v2.A1
          - Current viewport number                                   > v2.A1
          - Current text window number                                > v2.A1
          - World coordinate configuration                            > v2.A1
          - Base math setting                                         > v2.A1
          - Coordinate byte-width setting                             > v2.A1
          - Color mode (Direct RGB or Palette Mapping)                > v2.A1
          - Current mouse cursor style                                > v2.A1
                                                                      > v2.A1
     Example:  $ENVSAVE$                                              > v2.A1
     Returns:  nothing                                                > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
$ENVRESTORE$ ... Activates a previously snapshotted environment       > v2.A1
---------------------------------------------------------------       > v2.A1
This command does the exact opposite of the $ENVSAVE$ text variable.  > v2.A1
It restores the values of many RIPscrip environmental settings        > v2.A1
previously saved with the $ENVSAVE$ text variable function.           > v2.A1
                                                                      > v2.A1
     Example:  $ENVRESTORE$                                           > v2.A1
     Returns:  nothing                                                > v2.A1


$TEXTQUERY(window)$ ... Returns composite information on text window  > v2.A1
--------------------------------------------------------------------  > v2.A1
This is a combination of other text window text variables.  When this > v2.A1
command is used, all four coordinates of a text window are returned   > v2.A1
as well as the text window font number and a value stating whether    > v2.A1
wrap mode is enabled or not.  The format of the return string is:     > v2.A1
                                                                      > v2.A1
     x0:y0:x1:y1:font:wrap                                            > v2.A1
                                                                      > v2.A1
The X/Y coordinates are returned in text coordinates just like the    > v2.A1
$TWX0$ - $TWY1$ variables do.  The font field is the current          > v2.A1
MicroANSI font number.  If wrap is enabled then the wrap field will   > v2.A1
contain a 1, or a 0 for chop.  The X/Y fields will always be two      > v2.A1
bytes wide (0 padded on the left if needed).                          > v2.A1
                                                                      > v2.A1
If you do not specify a text window number or you specfiy a window of > v2.A1
"CUR" then the current text window will be returned.  If the window   > v2.A1
is disabled, then all fields will be set to zeros.                    > v2.A1
                                                                      > v2.A1
     Example:  $TEXTQUERY(5)$                                         > v2.A1
     Returns:  00:00:79:24:2:1                                        > v2.A1
                                                                     
$VIEWQUERY(viewno,type)$ ... Returns composite viewport information   > v2.A1
-------------------------------------------------------------------   > v2.A1
This functions similarly to the $TEXTQUERY$ variable in that it       > v2.A1
returns several pieces of information about a viewport.  This command > v2.A1
returns four values which are the current viewport coordinates of the > v2.A1
upper-left corner and the lower right corner.  The format of the      > v2.A1
return string is:                                                     > v2.A1
                                                                      > v2.A1
     x0:y0:x1:y1                                                      > v2.A1
                                                                      > v2.A1
The width of each field is dependent on the type of coordinate system > v2.A1
values you wish returned.  You may specify "WORLD" or "VIDEO" for     > v2.A1
your coordinate types.  In either event, the width of each field is   > v2.A1
based on the number of digits of the largest value for either         > v2.A1
coordinate system (ie, a 10000x8000 world coordinate system would     > v2.A1
yield a field width of 5 bytes for all parameters if you chose the    > v2.A1
WORLD type).  All numbers are left-padded with zeros if they are not  > v2.A1
as large as the maximum width.                                        > v2.A1
                                                                      > v2.A1
If you do not specify a viewport number, or you specify "CUR" then    > v2.A1
the current viewport's information is returned.  If the viewport is   > v2.A1
disabled then the all four fields will be set to zeros.               > v2.A1
                                                                      > v2.A1
     Example:  $VIEWQUERY(CUR,WORLD)$                                  > v2.A1
     Returns:  0000:0000:4095:3071                                    > v2.A1
                                                                     
=====================================================================
==                 DEFINING PERMANENT VARIABLES                    ==
=====================================================================

Under normal situations you reference text variables by simply
placing dollar signs ($) around the variable name.  Anywhere where
that text variable occurs in a Host Command, Query, or other related
place that can contain text variables will have its contents replaced
with the associated information.  A RIPscrip command exists in the
specification to define text variables for permanent storage.  Since
this is an actual RIPscrip command, it is not well suited for using
in a Host Command directly.  In fact, you couldn't use that in the
Host Command's return string definition.

If you reference a Text Variable in a Host Command that hasn't been
defined yet (eg, $FIRST_NAME$), then the user will be presented with
a pop-up dialog box asking them to:

                    Please enter FIRST_NAME:

When the user enters some information, this data is inserted where
the $FIRST_NAME$ variable was located, and the contents of that
variable are lost after that moment.  What is truly needed is an
ability to preserve that information (either on Disk, or in memory)
so that it can be used later on.  To accomplish this, we will form
some variations on the text variable syntax.

There are four basically different text variable references, each of  > v2.A0
them take a single command character added between the first dollar   > v2.A0
sign and the beginning of the variable name.  Those characters and    > v2.A0
their significance is:                                                > v2.A0
                                                                      > v2.A0
     * ... An answer is required                                      > v2.A0
     + ... Save variable to database permanently                      > v2.A0
     = ... Save to internal memory table (lost when RIPterm hangs up) > v2.A0
     # ... Do not echo keystrokes (show #'s instead).  This is        > v2.A0
           useful for things like entering passwords.                 > v2.A0

     - ... Used in conjunction with a default response (see below).   > v2.A1
           When this option is used, the value of the variable is     > v2.A1
           set to the default value and the user is not prompted      > v2.A1
           for any data entry (transparent data variable define).     > v2.A1
           Nothing is returned to the host in this mode.              > v2.A1
     & ... Transparent data variable retrieval.  This allows the      > v2.A1
           host to retrieve a text variable from the terminal and     > v2.A1
           the user is not prompted to modify the information.        > v2.A1
                                                                      > v2.A1
           DEVELOPER NOTE: For database variables that are retrieved  > v2.A1
           you might want to implement a "data security" option in    > v2.A1
           your software that overides this "transparent" mode of     > v2.A1
           operation for permanent variables.  For temporary          > v2.A1
           variables (in memory) though, the system should be allowed > v2.A1
           to retrieve them transparently since it created them       > v2.A1
           itself.                                                    > v2.A1


To ask for the FIRST_NAME text variable that must be filled in, and   > v2.A0
to instruct RIPterm to save the variable to the local database, you   > v2.A0
would use the following text variable command syntax:                 > v2.A0
                                                                      > v2.A0
                          $*+FIRST_NAME$                              > v2.A0
                                                                      > v2.A0
The four command characters (*, +, = and #) can be in any order, but  > v2.A0
can only appear once in the text variable statement - additional      > v2.A0
occurences of them are ignored.                                       > v2.A0

You may specify how wide the data entry field for the text variable   > v2.A1
is.  To do this, simply put the number of columns after the variable  > v2.A1
name with a comma (,) in between (eg, $NAME,10$).                     > v2.A1

As you may have noticed earlier, if a text variable is referenced     > v2.A0
without being previously defined, it will display a generic question  > v2.A0
to prompt the user.  You have the option to specify a custom          > v2.A0
question.  The syntax is similar in nature to the syntax of the host  > v2.A0
command/text labels of the pop-up pick lists described below.  In     > v2.A0
order to prompt with a particular question, after the variable name   > v2.A0
place an at-sign (@) followed by the question, then the final dollar  > v2.A0
sign as in the following example:                                     > v2.A0
                                                                      > v2.A0
               $FIRST_NAME,20@What's your first name?$                > v2.A0
                                                                      > v2.A0
In the question text, you are not allowed to use dollar signs at all. > v2.A0

You also have the ability to X/Y location of the pop-up window that   > v2.A1
asks for the text variable.  This gives you control over the location > v2.A1
of the window.  The way you do this is by adding some coordinate      > v2.A1
information before the variable name followed by a colon.  An example > v2.A1
of this would be as follows:                                          > v2.A1
                                                                      > v2.A1
               $10,10:FIRST_NAME,20@What's your first name?$          > v2.A1
                                                                      > v2.A1
These coordinates are specified in normal decimal format.  If one or  > v2.A1
either of the number are omitted then the dialog is centered either   > v2.A1
horizontally, vertically or both.  Some examples of this are as       > v2.A1
follows:                                                              > v2.A1
                                                                      > v2.A1
       $,50:NAME$ ... Centered horizontally                           > v2.A1
       $50,:NAME$ ... Centered vertically                             > v2.A1
         $,:NAME$ ... Centered both horizontally and vertically       > v2.A1
                                                                      > v2.A1
If you omit the X/Y specification codes entirely (eg, $NAME$), then   > v2.A1
the actual location of the popup dialog is up to the discretion of    > v2.A1
the RIPscrip software.                                                > v2.A1
                                                                      > v2.A1
You may also supply a default value for the text variable.  This      > v2.A1
default value is used if the variable doesn't already exist.  When    > v2.A1
the default value is used it is displayed in the data field's edit    > v2.A1
region and you have the option of changing it.                        > v2.A1
                                                                      > v2.A1
To supply a default response, you specify the default contents after  > v2.A1
an equal sign (=) which must be placed after the variable name (and   > v2.A1
width parameter and question parameter if applicable).  Some examples > v2.A1
are:                                                                  > v2.A1
                                                                      > v2.A1
     $STATE=Ca$                                                       > v2.A1
     $STATE@What state do you life in?=Ca$                            > v2.A1





===================================================================== > v2.A1
==            USER DEFINED DATA VARIABLE FORMAT OPTIONS            == > v2.A1
===================================================================== > v2.A1
                                                                      > v2.A1
Just like text variable parameters defined earlier for built-in text  > v2.A1
variables, user defined text variables have the same luxury.  These   > v2.A1
parameters define the format of the entered data.  The currently      > v2.A1
defined format options for user defined text variables are:           > v2.A1
                                                                      > v2.A1
        ANY ... Any character is allowed                              > v2.A1
      ALPHA ... User can enter alphabetic characters only (A-Z, a-z)  > v2.A1
     NUMBER ... User can enter numeric characters only (0-9)          > v2.A1
    DECIMAL ... Decimal numbers are allowed (0-9, +, - and .)         > v2.A1
   ALPHANUM ... User can enter alphanumeric only (A-Z, a-z, 0-9)      > v2.A1
       NAME ... Formatted name entery - first letter is capitalized   > v2.A1
                and all subsequent characters in a word are set to    > v2.A1
                lower case automatically.                             > v2.A1
       DATE ... Date field (format MM/DD/YY by default).              > v2.A1
                                                                      > v2.A1
                NOTE TO BETA SITES:  Any input on this for            > v2.A1
                international users and other date format types?      > v2.A1
                                                                      > v2.A1
By default, a format option of "ANY" is assumed when no parameter are > v2.A1
specified.                                                            > v2.A1





===================================================================== > v2.A1
==             EXAMPLES OF USER-DEFINED TEXT VARIABLES             == > v2.A1
===================================================================== > v2.A1
                                                                      > v2.A1
Below are some examples of user defined text variables as might be    > v2.A1
used in a real world situation:                                       > v2.A1
                                                                      > v2.A1
     $*+20,50:NAME(Name),30@What's your name?=John Doe$               > v2.A1
                                                                      > v2.A1
This is about as complex as they get.  Going from left to right, lets > v2.A1
look at what all the codes mean.  First, the "*" means that a         > v2.A1
response to this request is required (they cannot hit ESC or CANCEL   > v2.A1
to get out of it).  The "+" means to save the response to the         > v2.A1
internal database permanently.  The sequence "20,50:" means to place  > v2.A1
the dialog box's upper left corner  at location (20,50) on the        > v2.A1
screen.  The "NAME" is the name of the data variable.  The format     > v2.A1
option "(Name)" means that this should be a formatted name field      > v2.A1
where the first letter of any word should be capitolized and the      > v2.A1
remaining characters should be set to lower case.  The value ",30"    > v2.A1
after the variable name/format indicates that this field is up to 30  > v2.A1
characters in length.  "@What's your name?" indicates that the        > v2.A1
question "What's your name?" should be displayed when the user is     > v2.A1
prompted for the information.  Finally, the "=John Doe" indicates     > v2.A1
that if the field doesn't exist, it should be filled in with "John    > v2.A1
Doe" before any editing is allowed.  This gives the user the ability  > v2.A1
to choose a default name if they wish.                                > v2.A1
                                                                      > v2.A1
     $*#20,10:PASSWORD,10@Please enter your password$                 > v2.A1
                                                                      > v2.A1
This example is a required data variable that echos #'s in place of   > v2.A1
the keystrokes you entered.  The field is placed at (20,10) on the    > v2.A1
screen with a variable name of PASSWORD.  The field is 10 characters  > v2.A1
wide and the prompt is "Please enter your password".                  > v2.A1





=====================================================================
==                 LOCAL RIPscrip FILE PLAYBACK                    ==
=====================================================================


You can re-play a .RIP file that you have locally on your hard disk
from anyplace that allows text variables.  The format of the variable
is somewhat different than user variables, or pre-defined text
variables.  After the initial dollar sign ($), enter the greater-than
symbol (>) followed by the filename (with or without the .RIP
extension), then ending in another dollar sign ($).  Several examples
of this are as follows:

         $>MYFILE.RIP$
         $>FILE1$
         $>FILE1.RIP$$>FILE2.RIP$$>FILE3$

Note in the last example, a file extension other than .RIP was used.
You are not limited to playing back local .RIP files.  In fact, you
can play-back any file you want.  You could load any simple text
file, ANSI picture image, or other such thing.  When loaded, the data
is not sent to the host; it is strictly echoed on your local screen.
If the file is a .RIP file, it will replay any graphics that were in
the file and if any Mouse Regions are defined, it will create those
fields for you as well, thus allowing you to pop-up dialog screens or
other such things that are not built-in to RIPterm normally.

Each "local RIP playback" variable you enter will search for the .RIP
file in the current host's icon directory.  If it cannot find the
file in that directory, it will check the ICONS\ directory.






===================================================================== > v2.A1
==                   LOCAL AUDIO FILE PLAYBACK                     == > v2.A1
===================================================================== > v2.A1
                                                                      > v2.A1
In 2.0, we are introducing audio capability (both digitized and       > v2.A1
sequenced music).  To further enhance our host command language, we   > v2.A1
are now offering an extension of local RIP file playback for audio    > v2.A1
files.  This is "Local Audio File Playback".  This command is nearly  > v2.A1
identical in syntax to the local RIP file playback command with a     > v2.A1
simple alteration.  Instead of using the ">" character to signify     > v2.A1
RIPscrip file, you use the close paranthesis ")" as in the following  > v2.A1
example:                                                              > v2.A1
                                                                      > v2.A1
          $)AUDIOFILE.FIL$                                            > v2.A1
          $)TRAIN.WAV$                                                > v2.A1
                                                                      > v2.A1
The file extension is unimportant.  See the section of this document  > v2.A1
on audio commands for more detailed information on audio.             > v2.A1

===================================================================== > v2.A1
==                   LOCAL BITMAP PLAYBACK (DISPLAY)               == > v2.A1
===================================================================== > v2.A1
                                                                      > v2.A1
This command is much like the local RIPscrip playback or the local    > v2.A1
audio playback, but it intended to place a local bitmap (.BMP) file   > v2.A1
onto the screen.  The bitmap will be displayed inside the current     > v2.A1
image settings as defined by the RIP_IMAGE_STYLE command and will     > v2.A1
adhere to the settings of that command.  This mode of displaying a    > v2.A1
BMP file is the only method for showing a BMP via the image style     > v2.A1
settings.                                                             > v2.A1
                                                                      > v2.A1
For the purposes of universality, the bitmap is shown to the screen   > v2.A1
using the current screen's color palette and "auto-dithering" mode is > v2.A1
used for the viewing of the image.  If you need support for some of   > v2.A1
the other modes for viewing a bitmap image (ie, the RIP_LOAD_BITMAP's > v2.A1
flexibility), then you will have to use that command instead.  This   > v2.A1
command is provided as a simple method of showing a bitmapped image   > v2.A1
from within a host command.                                           > v2.A1
                                                                      > v2.A1
Note, if no image style definition has been recorded then the bitmap  > v2.A1
is shown in the maximum size of the current viewport.  In other       > v2.A1
words, it will be scaled to fill up the entire viewport.              > v2.A1
                                                                      > v2.A1
To instruct the terminal to playback a local bitmap file, you would   > v2.A1
execute a host command with the following in it:                      > v2.A1
                                                                      > v2.A1
     $<FILENAME.BMP$                                                  > v2.A1
                                                                      > v2.A1
Note that this uses the less-than sign unlike the greater than sign   > v2.A1
used for local RIPscrip file playback.  This is intentional.  In      > v2.A1
fact, we use the opposite angle-bracket to indicate that this is a    > v2.A1
low-level primitive type playback like local RIPscrip file playback.  > v2.A1
The audio playback uses the parenthesis because it is not a low-level > v2.A1
primitive playback, but a higher level concept.  We use the           > v2.A1
parenthesis as a distinction from the lower level playback commands.  > v2.A1


===================================================================== > v2.A1
==               LOCAL IMAGE FILE PLAYBACK (DISPLAY)               == > v2.A1
===================================================================== > v2.A1
                                                                      > v2.A1
This command is similar to the local bitmap playback except that      > v2.A1
dealing with raw bitmapped images, this command displays compressed   > v2.A1
photo-like images.  Currently, only JPEG compressed image files are   > v2.A1
supported.  This command takes a JPEG file and displays it based on   > v2.A1
the defined image style (set with a RIP_IMAGE_STYLE) command.  If no  > v2.A1
image style is recorded, then the JPEG file is displayed inside the   > v2.A1
current viewport and will occupy the entire viewport's dimensions.    > v2.A1
                                                                      > v2.A1
This command uses a syntax similar to the local bitmap playback       > v2.A1
operation but instead uses the "(" character instead of the "<" one.  > v2.A1
This uses the same idealogy as was noted between local RIPscrip file  > v2.A1
playback and local audio file playback.  The JPEG file is considered  > v2.A1
a higher level object then a raw bitmap, so it uses the parenthesis   > v2.A1
command character instead of the angle brackets.  To playback the     > v2.A1
local JPEG file MYFILE.JPG, issue the following command:              > v2.A1
                                                                      > v2.A1
     $(MYFILE.JPG$                                                    > v2.A1

=====================================================================
==                           POP-UP LISTS                          ==
=====================================================================

Any place that you can use a Text Variable (Queries, Button and Mouse
Field return strings, and Keystroke Macros), you can take advantage of
a unique feature of RIPscrip - Pop-Up Pick Lists.  A Pop-Up Pick List
is simply a list that pops up allowing you to choose from one of
several available values.  Whichever entry in the list you choose
will insert it's associated command in the Host Command returned back
to your host.

A list is created by putting the special list instructions inside two
sets of parenthesis like this: (( and )).  The list consists of an
optional question followed by two colons (::), followed by one or
more list entries.  For example, ((Send Email
to?::Sysop,Cosysop,Joe)) says to pop-up a list asking you "Send Email
to?", giving you the choices of "Sysop", "Cosysop", and "Joe".

By default, if you press ESC instead of picking an entry in the list,
then nothing will be inserted into the text of your Command. You can
indicate that the user must pick an entry by putting an asterisk (*)
at the beginning of the question.  For example, ((*Send Mail
to?::Sysop,Joe)).  This would make it so that the user must choose
either Sysop or Joe.

In the previous examples, Sysop and Joe are the text responses that
are inserted into your Host Command.  These commands are also the
same things that are displayed in the listing.  If you want to use
something else in the listing instead of the return text, you can.
When you make the list entry, add an @description to the end of it.
For example:

     ((Send Mail To?::Sysop@Head Honcho,Cosysop,Joe))

...would display a pop-up pick list of Head Honcho, Cosysop, and Joe.

One final feature of Pop-Up Pick Lists allows you to specify a hotkey
for each entry in the list.  For example, if you wanted the first
character of each entry to be highlighted (thus allowing you to
select that character to activate the entry), simply put a tilde (~)
or an underline (_) before and after the keystroke.  For example
"_S_ysop" would highlight the "S" in "Sysop" appearing like this:

                       Sysop

You can highlight more than one character, but only the first one will
be the active hotkey.  If you omit the second tilde or underline,
then the remainder of the description will be highlighted.

NOTE:  If you use a tilde or an underline in the Text Response (not
       the description), then those characters are inserted into
       your Host Command when it is transmitted to the host.  You
       probably don't want to do this.  Recommendation: only use
       hotkey features on list entries where you specify a
       description!

If you do not specify a question, then the list default to the
question:

               Choose one of the following:


You may specify up to 64 entries for any one list.  In RIPterm        > v2.A1
version 1.52 and earlier, the total length of a pick list was 256     > v1.53
bytes.  In version 1.53 and later, this limit has been increased to   > v1.53
1024 bytes.                                                           > v1.53

In earlier revisions of RIPscrip, a maximum number of 20 entries in a > v2.A1
picklist were allowed.  This has been expanded to 64 for version 2.0. > v2.A1
If the total number of entries makes the picklist too tall to fit on  > v2.A1
the screen then it should handle some form of scrolling mechanism.    > v2.A1

Some characters have special significance in the RIPscrip language.
These characters are ! (exclamation mark, or for you Unix-heads,
bang), \ (backslash), and | (vertical bar).  To use these characters
in a Text Response, they must be preceded by a backslash (! becomes
\!, \ becomes \\, and | becomes \|).  RIPaint automatically adds
these when creating Text Responses.  You need to be aware of this
only if you are editing RIPscrip files with a text editor.  The _
(underline) and ~ (tilde) characters used to indicate the hotkey in a
Text Response are not able to be preceded by a backslash to be used
by themselves.  They will be returned to the host if they exist in a
Text Response (not in the description), however everything after the
underline or tilde will be underlined, and the first character will
be considered the hotkey.

  Examples:

     ((Send E-Mail to?::Sysop,Joe,Mike))
     ((*Send E-Mail to?::Sysop@The Head Honcho,Joe,Mike@My Brother))
     ((::Sysop@_T_he Head Honcho,Joe,Mike@My _B_rother))






=====================================================================
==                     HOST COMMAND "TEMPLATES"                    ==
=====================================================================

Often you might want a button on your screen to do one thing in one
situation, but to do something completely different in another
situation.  In the past, this required having a separate menu file
for each different function that this Button needs.  This cumbersome
method is history with Command Templates.

Command Templates are probably best described with a brief example.
Lets say that you have a menu screen for reading and writing messages
in your public message forums.  On this menu, you can have buttons
for each forum on your host, and at the same time have buttons for
Read, Write, Erase, Modify, etc.  Now, how can you make the
Read/Write/etc.  buttons work differently for each forum button
clicked?

                  Templates!

To further refine our example, lets say that you click on the button
for Forum #1, it should send the command "S FORUM1" to the host to
select that forum.  After that, simply clicking on the Read or Write
buttons will read through the current section.  But, what if you want
to interactively move about on the menu? Make each of the forum
selection buttons define a template.  Each template instructs
RIPscrip how to process the other buttons.

In the example above, the Forum #1 button would define this template:

                S FORUM1 $?$^m

This template will return "S FORUM1" followed by the Host Command for
whichever button is clicked, followed by a carriage return. The
special text variable $?$ is only used in Command Templates, and is
used to indicate "insert the text into the template here".  It
references the text of some other button that was clicked that is
stuffing its data INTO this template.


CHARACTERISTICS OF TEMPLATES
----------------------------
Before you can go about defining templates, you need to know how they
work, interact and how other functions interact with templates.

You are allowed up to 36 different templates, each of which can be
different and active at the same time.  Each template corresponds to a
Button Group (see MOUSE FIELDS AND BUTTONS for more detail).  Templates
can be defined and/or activated in any order.  In other words, you can
have a template #1, 5, 13 and 32, but none of the others defined.
Templates remain defined until re-defined by another template.


DEFINING A TEMPLATE
-------------------
To create a template, when asked for a Host Command, simply type in
the Template similar to the following:

     [5:]S FORUM1 $?$^m


The [5:] at the beginning of the command indicates that you wish to
create template #5 with the following text as the template.  Remember,
a $?$ is considered a "macro" that will insert some text into this
template from another source.  Valid template numbers are 0-9, A-Z.
So, with this in mind, all of the following template definitions are
valid:

     [0:]S FORUM1 $?$^m
     [9:]S FORUM2 $?$^m
     [G:]S FORUM3 $?$^m


USING TEMPLATES
---------------
When you want to make a button "feed its command" into a template, you
do so in a format similar to defining a Template, but with a subtle
difference.  Don't include the colon (:) in the template reference.
An example of this would be the following:

     [0]HELLO

This says, take the text "HELLO" and feed it into template number 0,
and send the final result to the host.  Note how simple it is to
create and reference templates by either using a colon or omitting
it.

If you do not specify a Template reference in the format [#] at the
beginning of your Host Command, it will be considered to be a Normal
Host Command that does not get stuffed into any templates.  For
completeness, you may specify []HELLO to send the word "HELLO" to the
host without going through any templates (a "null" template).  So in
other words, using a [] or using nothing at all is the same thing,
don't use any templates for this host command.


CHAINING TEMPLATE RESPONSES
---------------------------
In the preceding examples we showed how you can feed the Host Command
of one button through a single Template definition.  This is the
simplest case of template processing.  As part of the big picture of
templates, you can chain the input of one template into another
template, into another, so on and so forth and then transmit the
result of all composite template stuffing to the Host as one big
command.  After all is said and done with template processing, the
text buffer sent to the host can be anywhere from 0-4095 characters
in length.

To chain one template into another, use a format similar to the
following:

     [0372]HELLO

This feeds the word "HELLO" into template #0, then that result into
template #3, then that result into template #7, then finally the
result will be stuffed into Template #2. The output from Template #2
will then be transmitted to the host.

You may specify from 0-36 different templates in any one chaining
operations.  You MAY use the same template more than once in the same
chain, like the following:

     [0370]HELLO


Note, that template #0 is used twice, both at the beginning and the
end of the processing.  This feature, potentially dangerous, is
provided for completeness and flexibility.


EMBEDDED TEMPLATES
------------------
You can embed the contents of one template into another template (or
into a Host Command) by using the special Text Variable $?x$ where
"x" is the Template number to insert.  This command functions much
like the insert-text variable $?$ does, but gives you a great deal
more power and flexibility.

If you specify to embed one template inside another, the embedded
template can contain text variables, pick-lists and other such
things.  It can even have another embedded template in it as well,
but that sub-embedded template cannot have ANY text variables, or any
special commands, not even control characters!

To sum it up, an embedded template can have anything you want in it,
including other embedded templates.  All text variables in an
embedded template are expanded, as are pick lists, control characters
and the like.  If you have an embedded template INSIDE an embedded
template, the deepest embedded template will have NO text variable
processing done on it (i.e., the text is sent to the host verbatim,
exactly as it appears in the template).

If a template that is referenced is not yet defined, the template
embed command will be skipped (i.e., blank) providing that the
embedded template doesn't refer to a Radio Group. Radio Groups are
"dependencies" in this manner.  Anything that tries to embed a
Template from a Radio Group will not be processed if a template in
that area hasn't been defined yet.  Embedded templates from Check Box
Groups can be skipped if none of the check-boxes are active.


LISTS, VARIABLES AND CONTROL CHARACTERS
---------------------------------------
You may use Text Variables, Pop-Up Pick Lists and Control Characters
anywhere in any template definition or reference.  You are limited
such that, a text variable is translated to its real value when the
template is being processed, not after all templates are processed.
The net result of this is, you cannot use one template to construct
another template's pick- list, text variables, or the such.

In other words, you cannot nest Text Variable definitions, Pop-Up
Pick Lists , or Control Characters.  You can have these commands in
any or all templates used in a template chain, but they are
independent.


TEMPLATE CHAIN EXAMPLES
-----------------------
Below are several examples of different template setups. These are
intended to give you ideas on how templates may be used:

  Example #1:

     [0:]D $?$ Z^m     ... Used to download a file with Zmodem
     [1:]D $?$ X^m     ... Used to download a file with Xmodem

     [0]FILENAME.ZIP   ... Use this with #0 to download Zmodem
     [1]FILENAME.ZIP   ... Use this with #1 to download Xmodem


In this example, template #0 is used for downloading with Zmodem.
Template #1 is for downloading with Xmodem.  Depending on which
FILENAME.ZIP button you click on, you might download it with one
protocol or with another.  It all lies on which template you
reference.  The text transmitted to the host if you clicked on the
buttons could be either:

     D FILENAME.ZIP Z^m

          - or -

     D FILENAME.ZIP X^m


  Example #2:

     D $?2$ $?1$^m    ... Make this the "Download Now" button

     [1:]X            ... Radio Button #1   (X-Modem)
     [1:]Y            ... Radio Button #2   (Y-Modem)
     [1:]B            ... Radio Button #3   (Y-Modem Batch)
     [1:]Z            ... Radio Button #4   (Z-Modem)

     [2:]FILENUM1.ZIP ... Radio Button to download file #1
     [2:]FILENUM2.ZIP ... Radio Button to download file #2
     [2:]FILENUM3.ZIP ... Radio Button to download file #3

This example is a bit more involved.  It brings the concept of Radio
Buttons into the picture, which is part of the Button command. A Radio
Button is like having a list of options on your screen, only one of which
can be selected at any
one time.  When using    ͻ
templates with Radio        Protocols            Download which file?  
Buttons, you can quickly                  
and elegantly define a      X X-Modem              File #1            
menu that can do one         Y-Modem             X File #2            
thing in one mode, or        Y-Modem Batch        File #3            
something totally            Z-Modem                                  
different in another      Ŀ 
mode.  An example of                 Begin Download Now!             
the above menu might be    
as follows:              ͼ

In the preceding example #2, a group of Radio Buttons were used on the
right side of the screen to determine which file should be downloaded.
In that example, there was no ability to specify an arbitrary filename to
download.  You were only allowed to download one of three given files.
What would be perfect, would be to have the ability to pop-up a question
to the user asking what filename they wanted.  The solution is easy,
insert a text-variable that hasn't been defined yet!  To illustrate, the
above example could be modified to accommodate this as follows:

     D $?2$ $?1$^m    ... Make this the "Download Now" button

     [1:]X            ... Radio Button #1   (X-Modem)
     [1:]Y            ... Radio Button #2   (Y-Modem)
     [1:]B            ... Radio Button #3   (Y-Modem Batch)
     [1:]Z            ... Radio Button #4   (Z-Modem)

     [2:]FILENUM1.ZIP ... Radio Button to download file #1
     [2:]FILENUM2.ZIP ... Radio Button to download file #2
     [2:]FILENUM3.ZIP ... Radio Button to download file #3
     [2:]$FILENAME$   ... Radio Button to download ANY file


The screen might appear something like this:

        ͻ
           Protocols            Download which file?  
                         
           X X-Modem              File #1            
            Y-Modem             X File #2            
            Y-Modem Batch        File #3            
            Z-Modem         Ŀ 
                                 Enter Filename     
                              
         Ŀ 
                    Begin Download Now!             
          
        ͼ

NOTE:  To get the radio button graphic show above, an Icon Button
       must be used.  The empty circle is an icon, and the filled
       in circle is a hot icon.  Refer to Section 5.3.7.

Note the addition of the Enter Filename button.  If the user clicked
on that button, it would first try to replace $FILENAME$ with a text
variable.  It will find that such a variable does not exist, and will
then pop-up the following question on the screen:

       ͻ
                        Enter "FILENAME"                 
        Ŀ 
                                                      
         
       ͼ

If the user typed in DEMOFILE.TXT, then that filename is inserted
where $FILENAME$ was, resulting in (for example):

     D DEMOFILE.TXT Z^m

This is only an example, your mileage may vary.


MORE ABOUT TEMPLATES
--------------------
When you use the $?$ text variable inside a template definition, you
are not limited to using it only once.  In fact, you can use it as
many times in your template definition as you wish.  This can be
useful under many circumstances where the user might have to enter
the same thing twice.






=====================================================================
==                TEXT VARIABLE CREATION, AND QUERY                ==
=====================================================================

As mentioned in preceding sections, Text Variables were described as
either pre-defined variables, or as User Variables.  Pre-defined
variables are variables that RIPscrip products know things about "out
of the box".  They will always know what the variables mean, from the
day you install the software.  User Variables are variables that the
user of RIPscrip products defines, and teach it new things it doesn't
already know.


WHAT ARE USER VARIABLES?
------------------------
A User Variable is a Text Variable that RIPscrip doesn't know exists.
They are custom-defined text variables that contain information that
the terminal user will fill in.  If a variable already contains
information, a host will be automatically told (if told to do so)
what that variable contains without the user having to intervene
(i.e., transparent information exchange).

Examples of Text Variables might be:

     $FULL_NAME$    ... What is your full name?
     $COMPANY_NAME$ ... What company do you work for?
     $AGE$          ... How old are you?
     $DATEOFBIRTH$  ... What is your Date of Birth?
     $PHONENUMBER$  ... What is your Day-time phone number?

User Variables will "keep track" of these responses for you, in the
terminal program database.  You can tell the terminal to store these
values permanently, or they may be active only during the current
session, or they may be defined as temporary where they are not
stored for more than a brief moment.

NOTE:  This ability is configurable so that information exchange
       can be either interactive, or automatic.  Automatic
       transfer of information does NOT prompt the user with the
       information unless the variable has not yet been defined.
       If it has not been defined, a pop-up question will appear
       asking the user a particular question, thus defining the
       text variable.

If the exchange is interactive, the data is displayed in a pop-up
editor box, asking you if the information is correct.  If it is,
press ENTER and the retrieved information is sent to the host for
you.  If it is not correct, or it has not been created yet, just type
it in and press ENTER and it will be saved automatically, and sent to
the host all at once.


HOW CAN USER VARIABLES BE IMPORTANT?
------------------------------------
Lets take an example.  You are the system operator of a large
RIPscrip host.  As you have read, RIPscrip can take advantage of
database-like ability on the terminal end.  If you can alter your
host to ask questions with RIPscrip Text Variables built in, you can
have the terminal calling your host automatically fill in
questionnaires.  Imagine if a user could sign-up on your host without
having to type more than a single keystroke (i.e., "YES, this
information is correct").  With User Text Variables, you can do this
very thing.


CREATING USER VARIABLES
-----------------------
There are two ways of defining User Text Variables in RIPaint.  You
can use either the Define Text Variable command, or you can use Text
Variable Queries, as described in the next section.


DEFINING TEXT VARIABLES
-----------------------
The RIPscrip command Define Text Variable is by definition, an
interactive command with the user.  The RIPscrip command will attempt
to define a User Variable.  This variable is some piece of
information that the system operator deems important.  You may
specify a question, a default response, and how many characters long
the response may be.

Once the terminal has received a define command, the terminal pops up
an appropriate question box on the user's screen, asking him the
desired question that should be saved to a particular Text Variable.
If you did not specify a question, a default question is used (i.e.,
"Enter <name of text variable>").

Once the user has entered his response, it is recorded and saved.
How long it is stored depends on what the host told the terminal. The
host can tell the terminal "save this on your hard disk forever". The
host may also tell the terminal "don't save this to disk, but
remember this value until you exit RIPterm".  You also have the
option of saying "don't remember this value at all, just pop up a
question, and send the value to me NOW" - i.e., don't save it at all,
just enter it and send it to the host).


QUERYING TEXT VARIABLES
-----------------------
Now that you know how to define information on the terminal, you need
to know the last method of asking the terminal about text variables.
This feature is called "Data Query".
Data Query is a generic query command that can ask the terminal one
or more questions, and tell it how to transmit the information back
to the host.  This command is for use in non-button situations where
you do not want to wait until the user clicks on a button to get your
data back.

Data Query is a special RIPscrip command that can be used to ask the
contents of one or more Text Variables.


EXAMPLES OF TEXT VARIABLE QUERY
-------------------------------
Lets take a simple example.  You wanted to ask the terminal program
some address information.  You could do this with the following query
(remember, the query also tells the terminal HOW to send the data back
to the host):

     $FULL_NAME$^m$COMPANY$^m$ST_ADDR$^m$CITY$, $STATE$ $ZIP^m

This would query the terminal the contents of 6 text variables, and
format them in a manner similar to any normal address on an envelope.
The results of this query might send the following back to the host :

     Joe Sixpack
     ACME Corporation
     13631 Palindrome Parkway
     Surf City, CA 92649

If a text variable is queried, and it has not been defined yet, a
pop-up question will appear asking the user to fill in the
information.

===================================================================== > v2.A1
==                TEXT VARIABLE FORM GENERATION                    == > v2.A1
===================================================================== > v2.A1
                                                                      > v2.A1
In RIPscrip 2.0 we are introducing another text variable mechanism -  > v2.A1
form generation.  This is accomplished with some special usage of the > v2.A1
text variable constructs described earlier combined with two or more  > v2.A1
special active text variables $BEGINFORM$ and $ENDFORM$.              > v2.A1
                                                                      > v2.A1
A simple one variable query is truly just a special case of form      > v2.A1
generation - it is a form of one field.  Now we extend this concept   > v2.A1
considerably in both flexibility and power by adding a more complete  > v2.A1
form generation system.                                               > v2.A1
                                                                      > v2.A1
A form can be used in query commands and in mouse/button host         > v2.A1
commands.  To create a form you must enclose the form text variables  > v2.A1
between a $BEGINFORM$ and $ENDFORM$ commands as in the following      > v2.A1
example (we put things on separate lines for clarity):                > v2.A1
                                                                      > v2.A1
     $BEGINFORM$                                                      > v2.A1
       $10,10:FIRST_NAME@First name$                                  > v2.A1
       $10,20:LAST_NAME@Last name$                                    > v2.A1
     $ENDFORM$                                                        > v2.A1
                                                                      > v2.A1
Notice how we are taking advantage of the X/Y coordinates for placing > v2.A1
text variable queries on the screen - these coordinates are relative  > v2.A1
to the upper-left corner of the form's dialog box (not the screen).   > v2.A1
These X/Y sizes are used by the form generator to determine the       > v2.A1
actual size of the dialog that pops up.  We also us the description   > v2.A1
for each text variable as a label for the field.  On a form, an OK    > v2.A1
and CANCEL button will be added at the bottom to indicate whether the > v2.A1
form is complete or not.                                              > v2.A1
                                                                      > v2.A1
In our earlier example, if you typed in "John" in the first field and > v2.A1
"Doe" in the second, and the user clicked on OK, then "JohnDoe" will  > v2.A1
be transmitted to the host.  This obviously isn't of much use as-is.  > v2.A1
This was an overly simplified example.  One that's more realistic     > v2.A1
would be:                                                             > v2.A1
                                                                      > v2.A1
     $BEGINFORM$                                                      > v2.A1
       $10,10:FIRST_NAME@First name$^M                                > v2.A1
       $10,20:LAST_NAME@Last name$^M                                  > v2.A1
     $ENDFORM$                                                        > v2.A1
                                                                      > v2.A1
Notice the "^M" carriage return text variables after both text        > v2.A1
variable field definitions.  Anything outside the text variables is   > v2.A1
information that gets added when the form is complete.  So in this    > v2.A1
example (with "John Doe" as the name entered) you would have this as  > v2.A1
the final result "John^MDoe^M" which would be translated to John      > v2.A1
followed by a carriage return then Doe followed by another carriage   > v2.A1
return.  In fact, you can use anything in between text variable field > v2.A1
definitions that you want (picklists, raw text and control            > v2.A1
characters or template embedding).  You cannot have other forms       > v2.A1
embedded inside of a form.                                            > v2.A1

If the text variable fields already are defined when the form is      > v2.A1
popped up on screen, then those fields are automatically filled in    > v2.A1
with the associated information.  You can combine the text variable   > v2.A1
directives as well, so one field could be a permanent text variable   > v2.A1
definition while another could be a temporary one.  In the absence of > v2.A1
any directives, fields are volatile in nature in that they are        > v2.A1
destroyed immediately after the form is complete.                     > v2.A1

A special text variable exists, $FRAMELESS$ which is useful only
inside a form definition - if it is used prior to any normal text
variable, then it specifies that no dialog box should be created to
place the fields upon; the fields are placed inside the current
viewport directly on top of whatever graphics you already have.  When
the form is complete, the fields are not erased.  It's up to the host
to clear the fields in this case.  If you do not specify this text
variable then when the form is complete, the dialog box is removed.

===================================================================== > v2.A1
==            RIPscrip ICON FILE FORMAT SPECIFICATION             === > v2.A1
===================================================================== > v2.A1
                                                                      > v2.A1
The following section describes the exact file format specification   > v2.A1
of the RIPscrip Icon File.  This format differs from the older RIP    > v2.A1
v1.54 icon file format which used the Borland getimage() and          > v2.A1
putimage() formats.  That format was completely inadequate to         > v2.A1
resolution independent and color independent environments.  With that > v2.A1
in mind, we have changed to a Device Independent Bitmap (DIB).  A DIB > v2.A1
is a file that can be shown at any resolution, in any color           > v2.A1
configuration.  There are no actual DIB files out there in the world  > v2.A1
that conform to the raw DIB format.  The Microsoft Windows BMP format > v2.A1
is a DIB though, with a little more header information thrown in to   > v2.A1
give some added flexibility for future expandability.  In the         > v2.A1
interests of not inventing a completely new file format, we will be   > v2.A1
using BMP files for our Icon format for future RIPscrip revisions.    > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
DEVICE INDEPENDENT BITMAP (DIB) FILE FORMAT)                          > v2.A1
--------------------------------------------                          > v2.A1
The DIB file format, originally pioneered by Microsoft for their      > v2.A1
Windows product provides a device-independent method of storing       > v2.A1
bitmap data in a universally accessible way.                          > v2.A1
                                                                      > v2.A1
The file format has a more elaborate header structure than does the   > v2.A1
RIPscrip Icon file format.  In addition, color palette information is > v2.A1
stored in the file so that color approximation or dithering methods   > v2.A1
may be used to make image appear correct no matter what color palette > v2.A1
is in use.                                                            > v2.A1
                                                                      > v2.A1
The file format accomodates 1 bit per pixel (monochrome images), 4    > v2.A1
bits per pixel (16 color images), 8 bits per pixel (256 color images) > v2.A1
and 24 bit images.                                                    > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
DIB FILE HEADER                                                       > v2.A1
---------------                                                       > v2.A1
At the beginning of the file (at offset 0) is the bitmap information  > v2.A1
header.  Immediately following this is a color table (for all formats > v2.A1
except for 24 bit images).  The size of the color table is dependent  > v2.A1
on the number of bits per pixel and also on some other fields in the  > v2.A1
header.  After the color table is the actual raw bitmap data.  The    > v2.A1
format of the bitmap data varies depending on the number of bits per  > v2.A1
pixel.                                                                > v2.A1
                                                                      > v2.A1
The structure of the bitmap header is as follows:                     > v2.A1

struct BitmapInfoHeader {
     long biSize;                  /* Size of this header (40 bytes)       */
     long biWidth;                 /* Image width  in pixels               */
     long biHeight;                /* Image height in pixels               */
     int  biPlanes;                /* Number of image planes (must be 1)   */
     int  biBitCount;              /* Bits per pixel (1, 4, 8 or 24)       */
     long biCompression;           /* Compression type (1=no compression)  */
     long biSizeImage;             /* Size in bytes of compressed image    */
     long biXPelsPerMeter;         /* Horizontal resolution in pixels/meter*/
     long biYPelsPerMeter;         /* Vertical resolution in pixels/meter  */
     long biClrUsed;               /* Number of colors used                */
     long biClrImportant;          /* Number of "Important" Colors         */
};


The biSize parameter is the size of the actual header in the file.    > v2.A1
This should be set to 40 for this structure.  In the future, this     > v2.A1
value may change to accomodate larger headers.  To properly read in   > v2.A1
the header, you should examine the first four bytes of the header to  > v2.A1
find out the actual header's size then read in the remaining bytes of > v2.A1
the header into your program.                                         > v2.A1
                                                                      > v2.A1
The biWidth and biHeight parameter define the pixel dimensions of the > v2.A1
actual image in the raw bitmap data block.                            > v2.A1
                                                                      > v2.A1
The biPlanes field defines how many "bit planes" are used in the      > v2.A1
bitmap data.  This value should be set to 1 - meaning one bit plane.  > v2.A1
                                                                      > v2.A1
The biBitCount field determines the number of bits per pixel used in  > v2.A1
this image.  Valid values for this field are 1, 4, 8 and 24.          > v2.A1
                                                                      > v2.A1
The biCompression field determines the type of image compression used > v2.A1
on this image.  A value of 0 means no compression.  Microsoft defines > v2.A1
several nonzero values for the BMP files (basically a DIB with a bit  > v2.A1
more header information) that use a byte-oriented RLE encoding        > v2.A1
scheme.  After some research, it was found that no applications       > v2.A1
actually use this mode and the one vendor that we discovered that     > v2.A1
supported this form of compression did not do it correctly. As a      > v2.A1
result of this, we will formally declare that this field should be    > v2.A1
set to zero to indicate no compression.  In the future, we may alter  > v2.A1
this for something like internal JPEG data compression, TIFF, GIF,    > v2.A1
etc.                                                                  > v2.A1
                                                                      > v2.A1
The biSizeImage indicates the size of the compressed image in bytes.  > v2.A1
This is actually the size of the file (including all header           > v2.A1
information).                                                         > v2.A1
                                                                      > v2.A1
The biXPelsPerMeter and biYPelsPerMeter values are used for dots per  > v2.A1
inch calculations.  The formal definition of these fields are the     > v2.A1
horizontal and vertical resolution in pixels per meter.  It does not  > v2.A1
appear that any applications that use DIB formats actually take       > v2.A1
advantage of these fields, so they could easily be set to zero, or    > v2.A1
the width and height of the image.                                    > v2.A1
                                                                      > v2.A1
The biClrUsed field defines how many colors out of the maximum        > v2.A1
available are actually used by this image.  For example, if you have  > v2.A1
an 8 bit per pixel image (256 colors), but the image only uses 200    > v2.A1
colors, you could set this value to 200 to indicate that the color    > v2.A1
table only has 200 entries in it. Set this field to 0 to indicate     > v2.A1
that the maximum number of colors are in the color table.  We will    > v2.A1
set this value to 0 for all RIP bitmaps.                              > v2.A1
                                                                      > v2.A1
The biClrImportant field is used to specify how many of the colors in > v2.A1
the color table are actually important to the image.  For example, if > v2.A1
you had a 256 color bitmap, but only 16 colors of the image were      > v2.A1
critically important to the reproduction of the image, you would set  > v2.A1
this field to 16 and make sure that the first 16 colors in the color  > v2.A1
table were those important colors. This makes conversion to a 16      > v2.A1
color environment easier.  We formally will set this value to 0 to    > v2.A1
indicate that all colors are equally important.                       > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1

COLOR TABLE FORMAT                                                    > v2.A1
------------------                                                    > v2.A1
For 1, 4 and 8 bits per pixel images, a color table immediately       > v2.A1
follows the bitmap file header.  If the biClrUsed field is set to     > v2.A1
zero in the header, then the number of entries is 2^bits where "bits" > v2.A1
is the number of bits per pixel (1, 4, or 8).  This yields color      > v2.A1
table sizes of 2, 16 or 256 entries.  If the biClrUsed field is       > v2.A1
non-zero, then it defines the actual number of color table entries    > v2.A1
actually present.                                                     > v2.A1
                                                                      > v2.A1
Each entry in the color table consists of an RgbQuad structure.  This > v2.A1
structure stores information for the Red, Green and Blue components   > v2.A1
of the corresponding color table entry.  All values are full 8-bit    > v2.A1
unsigned characters, representing values from 0-255.  If displaying   > v2.A1
colors in video sub-systems that are not 8 bits for these components, > v2.A1
some bit shifting may be necessary to convert to the proper target    > v2.A1
color system.                                                         > v2.A1
                                                                      > v2.A1
Here is the structure definition for the RgbQuad structure:           > v2.A1

struct RgbQuad {
     unsigned char rgbBlue;        /* Blue  value for color map entry      */
     unsigned char rgbGreen;       /* Green value for color map entry      */
     unsigned char rgbRed;         /* Red   value for color map entry      */
     unsigned char rgbReserved;    /* Reserved - set to zero               */
};

Notice that the values are in reverse order (Blue, Green then Red).   > v2.A1
For some obscure reason, this was the way that it was originally      > v2.A1
designed.  Also note that there is a reserved parameter.  This should > v2.A1
be set to zero for future compatibility.                              > v2.A1
                                                                      > v2.A1
For 24 bit images, there is no color table.  Color table values are   > v2.A1
actually stored in the raw bitmap data block itself (see below).      > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
BITMAP DATA BLOCK FORMAT                                              > v2.A1
------------------------                                              > v2.A1
The format for the bitmap data block varies depending on the number   > v2.A1
of bits per pixel actually defined in the header.  The reason for     > v2.A1
this is optimal data storage without compression.                     > v2.A1
                                                                      > v2.A1
All bitmap image data blocks are stored in horizontal rows of data.   > v2.A1
Each row is padded to an even four byte boundary with zeros.  The     > v2.A1
first row of raw data is actually the bottom-most scan line of the    > v2.A1
bitmap.  Every subsequent row is progressively closer to the top of   > v2.A1
the bitmap in one line increments.                                    > v2.A1
                                                                      > v2.A1
The four storage methods are described in the next sub-sections.      > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
     1 BITS PER PIXEL                                                 > v2.A1
     ----------------                                                 > v2.A1
     Information is stored as one pixel per bit.  The high-order      > v2.A1
     bit in a byte is the left-most pixel in a group of eight         > v2.A1
     pixels.  For bits that represent pixels beyond the right         > v2.A1
     side of the image, zero bits are used as padding.                > v2.A1
                                                                      > v2.A1

     For example, if you had the following pixel values:              > v2.A1
                                                                      > v2.A1
          1 0 0 1 1 1 0 1 1 0 1 0 1 1 1 1 0 1 1 1                     > v2.A1
                                                                      > v2.A1
     They would be encoded as the following:                          > v2.A1
                                                                      > v2.A1
            In Binary: 10011101 10101111 01110000                     > v2.A1
          Hexadecimal: 9D AF 70 00                                    > v2.A1
                                                                      > v2.A1
     Note how four zero bits are added to the last byte, and          > v2.A1
     another zero byte is added to pad the row out to an even         > v2.A1
     four-byte boundary.  If image data stops exactly on a four       > v2.A1
     byte boundary, no padding is necessary.                          > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
     4 BITS PER PIXEL                                                 > v2.A1
     ----------------                                                 > v2.A1
     Information is stored as two pixels per byte.  Each pixel's      > v2.A1
     color value is stored in its own nibble inside the byte.         > v2.A1
     The left-most pixel is stored in the high-order nibble, and      > v2.A1
     the right-most pixel is stored in the low-order nibble.          > v2.A1
                                                                      > v2.A1
     For example, if you had the following pixel values:              > v2.A1
                                                                      > v2.A1
           In decimal:  12 0 7 8 4 15 11 10 9                         > v2.A1
          Hexadecimal:  C  0 7 8 4 F  B  A  9                         > v2.A1
                                                                      > v2.A1
     This would result in the following 4 bit encoding values:        > v2.A1
                                                                      > v2.A1
          Hexadecimal:  C0 78 4F BA 90 00 00 00                       > v2.A1
                                                                      > v2.A1
     Note that an extra 0 nibble was added to the last valid dat      > v2.A1
     byte and three zero bytes were added to round the row out        > v2.A1
     to an even four byte boundary.                                   > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
     8 BITS PER PIXEL                                                 > v2.A1
     ----------------                                                 > v2.A1
                                                                      > v2.A1
     This is the most straightforward encoding scheme.  Each          > v2.A1
     pixel is stored as exactly one pixel per byte.  All eight        > v2.A1
     bits of the byte are used to store the pixel color values.       > v2.A1
     No bit shifting or color encoding is necessary.                  > v2.A1
                                                                      > v2.A1
     The above example (4 bits per pixel) would be encoded as         > v2.A1
     follows:                                                         > v2.A1
                                                                      > v2.A1
          Hexadecimal: 0C 00 07 08 04 0F 0B 0A 09 00 00 00            > v2.A1
                                                                      > v2.A1
     Notice that three extra zero bytes were added to round the       > v2.A1
     row out to an even four byte boundary.                           > v2.A1
                                                                      > v2.A1
                                                                      > v2.A1
     24 BITS PER PIXEL                                                > v2.A1
     -----------------                                                > v2.A1
     This format does not use a color table.  The actual RGB          > v2.A1
     values used for colors is actually stored in the raw bitmap      > v2.A1
     data blocks.  Each pixel's worth of data in the data block       > v2.A1
     consists of three bytes.  The first byte represents the          > v2.A1
     BLUE component, then the GREEN component, then the RED           > v2.A1
     component in the third byte.  Each one of these values can       > v2.A1
     range from 0 to 255.  Some bit shifting may be necessary         > v2.A1
     depending on your target video sub-system.  Again, every         > v2.A1
     row of information is padded to an even four byte boundary       > v2.A1
     like all the above methods do.                                   > v2.A1

                                                                      > v2.A1
                                                                      > v2.A1
MISCELLANEOUS NOTES                                                   > v2.A1
-------------------                                                   > v2.A1
Any of the fields in the header that are LONGs or INTs use Intel byte > v2.A1
ordering of its values.  For IBM-PC based software, this should pose  > v2.A1
no problems at all.  On Motorola based processors though, the data in > v2.A1
these fields will have to have some bit shifting done on them to      > v2.A1
ensure that they are represented correctly.  In no cases will these   > v2.A1
fields in the header represent negative values.                       > v2.A1



===================================================================== > v2.A0
==                 RIF FILE FORMAT SPECIFICATION                  === > v2.A0
===================================================================== > v2.A0

The RIF file format specification goes here!

