



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

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

                            Revision 1.54

                           July 19th, 1993
             ------------------------------------------





=====================================================================
==                           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
     DATA : (714) 379-2133 (ArenaBBS: The Major BBS...32 lines)




=====================================================================
==                    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 "> 1.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




=====================================================================
==                   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 for example).  The language is
open ended enough so that literally trillions of different graphics
commands can be implemented as needed.  RIPscrip is not a proprietary
protocol standard and 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 precludes 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, line, circles,
fills, 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.




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

This document describes RIPscrip commands up through version 1.54
of the RIPscrip Protocol Specification.

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.

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 a Graphical Window and a Text
    Window.  The Graphical Window is where all RIPscrip graphics
    appear.  The 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 printable non-decimal-digit
    character.

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 represented in base-36.  This
    compacts numbers down to roughly 3/5 of their decimal form.
    This numbering system, technically called "Hexa-Tri-Decimal",
    has affectionately been dubbed "MegaNums".  Unlike Hexadecimal
    which uses 0-9, A-F, MegaNums take advantage of the entire
    alphabet, using characters 0-9 and A-Z.

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




=====================================================================
==                   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
                                                                      > 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

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




=====================================================================
==                    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.

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





---------------------------------------------------------------------
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 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.

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 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 are specified based on a 640x350 pixel resolution, meaning
X can be anywhere from 0 - 639, and Y can be anywhere from 0 - 349.
x0 must be less than x1 and y0 must be less than y1 unless all
parameters are set to zero, indicating that the graphics window is
disabled.



---------------------------------------------------------------------
RIP_RESET_WINDOWS
---------------------------------------------------------------------
         Function:  Clear Graphics/Text Windows & reset to full screen
            Level:  0
          Command:  *
        Arguments:  <none>
           Format:  !|*
          Example:  !|*
  Uses Draw Color:  NO
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).



---------------------------------------------------------------------
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 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 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 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 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 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:2
           Format:  !|c <color>
          Example:  !|cA
  Uses Draw Color:  YES
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.)

This command chooses one of the colors of the 16-color RIP palette
defined by the RIP_SET_PALETTE.  Here is the default 16-color RIP
palette:

     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



---------------------------------------------------------------------
RIP_SET_PALETTE
---------------------------------------------------------------------
         Function:  Set 16-color Palette from master 64-color palette
            Level:  0
          Command:  Q
        Arguments:  c1:2, c2:2, ... c16:2
           Format:  !|Q <c1> <c2> ... <c16>
          Example:  !|Q000102030405060708090A0B0C0D0E0F
  Uses Draw Color:  YES
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 RIP 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:

    16-Color RIP Palette     Master 64-Color EGA
        Color Code           Palette Color Code       Color
    ---------------------------------------------------------------
           00                     0  (00)             Black
           01                     1  (01)             Blue
           02                     2  (02)             Green
           03                     3  (03)             Cyan
           04                     4  (04)             Red
           05                     5  (05)             Magenta
           06                     7  (06)             Brown
           07                     20 (0K)             Light Gray
           08                     56 (1K)             Dark Gray
           09                     57 (1L)             Light Blue
           0A                     58 (1M)             Light Green
           0B                     59 (1N)             Light Cyan
           0C                     60 (1O)             Light Red
           0D                     61 (1P)             Light Magenta
           0E                     62 (1Q)             Yellow
           0F                     63 (1R)             White

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 Palette from Master Palette
            Level:  0
          Command:  a
        Arguments:  color:2 value:2
           Format:  !|a <color> <value>
          Example:  !|a051B
  Uses Draw Color:  YES
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 changes one color in the 16-color 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
RIP_RESET_WINDOWS.

    16-Color RIP Palette     Master 64-Color EGA
        Color Code           Palette Color Code       Color
    ---------------------------------------------------------------
           00                     0  (00)             Black
           01                     1  (01)             Blue
           02                     2  (02)             Green
           03                     3  (03)             Cyan
           04                     4  (04)             Red
           05                     5  (05)             Magenta
           06                     7  (06)             Brown
           07                     20 (0K)             Light Gray
           08                     56 (1K)             Dark Gray
           09                     57 (1L)             Light Blue
           0A                     58 (1M)             Light Green
           0B                     59 (1N)             Light Cyan
           0C                     60 (1O)             Light Red
           0D                     61 (1P)             Light Magenta
           0E                     62 (1Q)             Yellow
           0F                     63 (1R)             White

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_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 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
     ------------------------------------------
     00     Normal drawing mode (overwrite)
     01     XOR (complimentary) mode

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 inverted (black changes to white, red to
green, etc.).  Drawing the same item a second time erases it
completely.  This mode is useful for drawing something temporarily,
or for animation.  The Rubber Band mode of most paint programs uses a
mode like this.



---------------------------------------------------------------------
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 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 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 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, res:2
           Format:  !|Y <font> <direction> <size> <res>
          Example:  !|Y01000400
  Uses Draw Color:  NO
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.

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 - 4 are smooth scalable vector fonts.



---------------------------------------------------------------------
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 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 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 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 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 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 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 Line Pattern:  NO
  Uses Line Thick:  YES
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  NO
  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 Line Pattern:  NO
  Uses Line Thick:  YES
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  NO
  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 Line Pattern:  NO
  Uses Line Thick:  YES
  Uses Fill Color:  YES
Uses Fill Pattern:  YES
  Uses Write Mode:  NO
  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 Line Pattern:  NO
  Uses Line Thick:  YES
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  NO
  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 Line Pattern:  NO
  Uses Line Thick:  YES
  Uses Fill Color:  NO
Uses Fill Pattern:  NO
  Uses Write Mode:  NO
  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 Line Pattern:  NO
  Uses Line Thick:  YES
  Uses Fill Color:  YES
Uses Fill Pattern:  YES
  Uses Write Mode:  NO
  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 Line Pattern:  NO
  Uses Line Thick:  YES
  Uses Fill Color:  YES
Uses Fill Pattern:  YES
  Uses Write Mode:  NO
  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 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



---------------------------------------------------------------------
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 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 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 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:2
           Format:  !|F <x> <y> <border>
          Example:  !|F25090F
  Uses Draw Color:  NO
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



---------------------------------------------------------------------
RIP_LINE_STYLE
---------------------------------------------------------------------
         Function:  Defines a line style and thickness
            Level:  0
          Command:  =
        Arguments:  style:2, user_pat:4, thick:2
           Format:  !|= <style> <user_pat> <thick>
          Example:  !|=01000001
  Uses Draw Color:  NO
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
     00      Normal, Solid Line    1111111111111111  FFFF             > v1.54
     01      Dotted Line           0011001100110011  3333             > v1.54
     02      Centered Line         0001111000111111  1E3F             > v1.54
     03      Dashed Line           0001111100011111  1F1F             > v1.54
     04      Custom Defined line (see about <user_pat> below)

     Thick   Description
     -------------------------------
     01      Lines are 1 pixel wide
     03      Lines are 3 pixels wide

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.



---------------------------------------------------------------------
RIP_FILL_STYLE
---------------------------------------------------------------------
         Function:  Set current fill style (predefined) & fill color
            Level:  0
          Command:  S
        Arguments:  pattern:2, color:2
           Format:  !|S <pattern> <color>
          Example:  !|S050F
  Uses Draw Color:  NO
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 special case, the fill color doesn't
matter.)

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:2
           Format:  !|s <c1> <c2> <c3> <c4> <c5> <c6> <c7> <c8> <col>
          Example:  !|s11223344556677880F
  Uses Draw Color:  NO
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.

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



---------------------------------------------------------------------
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 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 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.



---------------------------------------------------------------------
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 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 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 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, res:1
           Format:  !|1C <x0> <y0> <x1> <y1> <res>
          Example:  !|1C001122330
  Uses Draw Color:  NO
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).

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



---------------------------------------------------------------------
RIP_PUT_IMAGE
---------------------------------------------------------------------
         Function:  Pastes the clipboard contents onto the screen
            Level:  1
          Command:  P
        Arguments:  x:2, y:2, mode:2, res:1
           Format:  !|1P <x> <y> <mode> <res>
          Example:  !|1P0011010
  Uses Draw Color:  NO
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 <mode> parameter defines "how" the image will be pasted on the
screen:

  Mode   Description                                          Logical
  -------------------------------------------------------------------
   00    Paste the image on-screen normally                   (COPY)
   01    Exclusive-OR  image with the one already on screen   (XOR)
   02    Logically OR  image with the one already on screen   (OR)
   03    Logically AND image with the one already on screen   (AND)
   04    Paste the inverse of the image on the screen         (NOT)

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



---------------------------------------------------------------------
RIP_WRITE_ICON
---------------------------------------------------------------------
         Function:  Write contents of the clipboard (icon) to disk
            Level:  1
          Command:  W
        Arguments:  res:1, filename
           Format:  !|1W <res> <filename>
          Example:  !|1W0filename.icn
  Uses Draw Color:  NO
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.

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



---------------------------------------------------------------------
RIP_LOAD_ICON
---------------------------------------------------------------------
         Function:  Loads and displays a disk-based icon to screen
            Level:  1
          Command:  I
        Arguments:  x:2, y:2, mode:2, clipboard:1, res:2, filename
           Format:  !|1I <x> <y> <mode> <clipboard> <res> <filename>
          Example:  !|1I001101010button.icn
  Uses Draw Color:  NO
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 .ICN file extension does not need to be included as part of the
filename.  If omitted, it will automatically be appended to the
filename.  If an extension is provided, it will be used verbatim.

  Mode   Description                                         Logical
  ------------------------------------------------------------------
   00    Paste the image on-screen normally                   (COPY)
   01    Exclusive-OR  image with the one already on screen   (XOR)
   02    Logically OR  image with the one already on screen   (OR)
   03    Logically AND image with the one already on screen   (AND)
   04    Paste the inverse of the image on the screen         (NOT)

If the <clipboard> parameter is 1, then the image pasted on screen
AND also copied onto the Clipboard.  If 0, it is simply pasted on the
screen.

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".



---------------------------------------------------------------------
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
                    res:6
           Format:  !|1B <wid> <hgt> <orient> <flags>
                    <bevsize> <dfore> <dback> <bright> <dark>
                    <surface> <grp_no> <flags2> <uline_col>
                    <corner_col> <res>
          Example:  !|1B0A0A010274030F080F080700010E07000000
  Uses Draw Color:  NO
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.

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).

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.                                                 > v1.54
                                                                      > 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.ICN).  When the Hot Icon flag is        > v1.54
     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 .ICN.  When Hot         > v1.54
     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
                                                                      > 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

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
                                                                      > 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
                                                                      > 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



---------------------------------------------------------------------
RIP_BUTTON
---------------------------------------------------------------------
         Function:  Define a Mouse Button
            Level:  1
          Command:  U
        Arguments:  x0:2 y0:2 x1:2 y1:2 hotkey:2 flags:1 res:1
                    ...text
           Format:  !|1U <x0> <y0> <x1> <y1> <hotkey> <flags>
                    <res> <text>
          Example:  !|1U010100003200iconfile<>Label<>HostCmd^m
  Uses Draw Color:  NO
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 the previously
described RIP_BUTTON_STYLE command.  You may have at most 128
different Mouse Buttons (you may have any number of non-Mouse
Buttons).

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.ICN<>TEXT LABEL<>HOST COMMAND

The actual syntax of this text parameter is as follows:

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

The block described as ICONFILE.ICN is actually the Icon Filename
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).

The .ICN file extension does not need to be included as part of the
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 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.



---------------------------------------------------------------------
RIP_QUERY
---------------------------------------------------------------------
         Function:  Query the contents of a text variable
            Level:  1
          Command:  <escape>
        Arguments:  mode:1 res:3 ...text
           Format:  !|1<escape> <mode> <res> <text>
          Example:  !|1<escape>0000this is a query $COMMAND$^m
  Uses Draw Color:  NO
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, Text Variables,
       and Host Command template definitions.  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 Graphics Window
     2    Process when mouse clicked in Text Window (any text
          variables that return X or Y mouse coordinates return TEXT
          coordinates, not graphics coordinates in this mode.  These
          coordinates are two-digit values instead of the graphical
          values that are four digits).

Note that modes 1-2 do not return the results of the Query instantly.
They query commands are processed when the user clicks the mouse
either in the text window, or in the graphics window respectively.
These "queries after mouse clicks" are only 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).

Basically put, a Query command will be immediately acted upon by the
Terminal program when received.  The Query 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.



---------------------------------------------------------------------
RIP_COPY_REGION
---------------------------------------------------------------------
         Function:  Copy screen region up/down
            Level:  1
          Command:  G
        Arguments:  x0:2 y0:2 x1:2 y1:2 res:2 dest_line:2
           Format:  !|1G <x0> <y0> <x1> <y1> <res> <dest_line>
          Example:  !|1G080G140M0005
  Uses Draw Color:  NO
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

NOTE:  The <res> parameter is reserved for future development by
       TeleGrafix.



---------------------------------------------------------------------
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 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 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.



---------------------------------------------------------------------
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.ICN<>
  Uses Draw Color:  NO
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 <filetype> 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

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     RIP file sequence (store them)
      2     ICN file sequence (store them in proper directories)
      3     HLP file sequence (store it, and auto-load if needed)
      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<>

The special <file_type> of 4 & 5 (COMPOSITE DYNAMIC file sequences)
is somewhat different than the non-batch transfer methods.  This
allows each file uploaded to be individually processed based on their
file extensions.  If you use extensions other than .RIP or .ICN, then
this mode is not available to you as the necessary files will not be
able to be processed.  Any files that are "downloaded" from the Host
in DYNAMIC mode are placed into the appropriate sub-directories and
no further processing is performed.  .RIP files that are received are
"stored" and are not played back in COMPOSITE DYNAMIC mode.  In
ACTIVE DYNAMIC mode, they are stored and played back simultaneously.

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.



---------------------------------------------------------------------
RIP_NO_MORE
---------------------------------------------------------------------
         Function:  End of RIPscrip Scene
            Level:  0
          Command:  #
        Arguments:  <none>
           Format:  !|#
          Example:  !|#
  Uses Draw Color:  NO
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




=====================================================================
==          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)




=====================================================================
==                        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 Variable 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.

-- 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.

The following is a reference of all Built-In and Active Text
Variables.





The following is a Listing of the 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 two-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$ ... Beep Sound (ala Ctrl-G)
----------------------------------
This Active Text Variable beeps the terminal, producing a Ctrl-G
sound.

The C source code to play this sound is:

          sound(1000);   // the Hertz frequency to play
          delay(75);     // millisecond delay
          nosound();     // turn the sound off
          delay(75);     // millisecond delay

     Example:  $BEEP$
     Returns:  nothing



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

The C source code to play this sound is:

          sound(50);     // the Hertz frequency to play
          delay(25);     // millisecond delay
          nosound();     // turn the sound off
          delay(10);

     Example:  $BLIP$
     Returns:  nothing



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

The C source code to play this sound is:

     for (i=0 ; i<4 ; i+=1)
     {
          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$
     Returns:  nothing



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

The C source code to play this sound is:

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


     Example:  $ALARM$
     Returns:  nothing



$PHASER$ ... Fire phasers!
--------------------------
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.

The C source code to play this sound is:

     for (i=2500 ; i>=50 ; i-=20)
     {
          sound(i);               // the Hertz frequency to play
          delay(2);               // millisecond delay
     }
     nosound();                   // turn the sound off


     Example:  $PHASER$
     Returns:  nothing



$REVPHASER$ ... Fire phasers!
-----------------------------
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.

The C source code to play this sound is:

          for (i=50 ; i<=2500 ; i+=20)
          {
               sound(i);               // the Hertz frequency to play
               delay(2);               // millisecond delay
          }
          nosound();                   // turn the sound off

     Example:  $REVPHASER$
     Returns:  nothing



$X$ ... X Mouse location
------------------------
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.

     Example:  $X$
     Returns:  0523



$Y$ ... Y Mouse location
------------------------
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.

     Example:  $Y$
     Returns:  0244



$XY$ ... X/Y Mouse Location
---------------------------
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

     Example:  $XY$
     Returns:  0297:0321



$XYM$ ... X, Y & button status
------------------------------
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.

     Example:  $XYM$
     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$ ... Save all screen attributes
----------------------------------------
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$
$SCB$ $SMF$ $SAVE$".

     Example:  $SAVEALL$
     Returns:  nothing



$RESTOREALL$ ... Restore all screen attributes
----------------------------------------------
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$ $RCB$
$RMF$ $RESTORE$".

     Example:  $RESTOREALL$
     Returns:  nothing



$EGW$ ... Erase Graphics Window
-------------------------------
This Active Text Variable erases the graphics window (much like a
Reset Windows command does). This command is useful in Host
Commands.  When you click on a Mouse Field, it could erase the
graphics 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).

     Example:  $EGW$
     Returns:  nothing



$SAVE$ and $SAVEx$ ... Save graphics screen
-------------------------------------------
The Active Text Variable $SAVE$ saves the contents of the entire
graphics screen to a disk file called RIPTERM.SAV.  No Mouse Fields,
Text Window locations or Clipboard data are saved - just the graphics
screen.  The entire 640x350 region is saved to disk.

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$.

     Example:  $SAVE7$
     Returns:  nothing



$RESTORE$ and $RESTOREx$ ... Restore graphics screen
----------------------------------------------------
The Active Text Variable $RESTORE$ reads the saved file RIPTERM.SAV
in from disk and restores the graphics as they were originally saved
with the $SAVE$ command.  Only the graphics screen is restored, not
the Clipboard, Mouse Fields or Text Window settings.

If you choose the RESTORE0 through RESTORE9 variations, the filename
that is restored are RIPTERM0.SAV through RIPTERM9.SAV, allowing you
to restore from up to ten different saved files.  A slight difference
from $RESTORE$ is that $RESTORE0$ - $RESTORE9$ delete the file after
the graphics screen is restored.

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:  $RESTORE3$
     Returns:  nothing



$SMF$ ... Save Mouse Fields
---------------------------
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$.

     Example:  $SMF$
     Returns:  nothing



$RMF$ ... Restore Mouse Fields
------------------------------
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.

NOTE:  You may restore Mouse Fields more than once is you wish. In
       other words, if you do a $SMF$ command, you may execute
       $RMF$ one or more times.

     Example:  $RMF$
     Returns:  nothing



$MKILL$ ... Kill Mouse Fields
-----------------------------
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$
     Returns:  nothing



$ETW$ ... Erase Text Window
---------------------------
This Active Text Variable erases the Text Window (like a clear screen
code does).  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$
     Returns:  nothing



$DTW$ ... Disable Text Window
-----------------------------
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



$STW$ ... Save Text Window information
--------------------------------------
This Active Text Variable stores all of the text window settings.
The window's X/Y dimensions are preserved, as is the current cursor
location, ANSI attributes, cursor ON/OFF status and the vertical
scrolling margins.  Even the current System Font is saved (if
necessary).

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

     Example:  $STW$
     Returns:  nothing



$RTW$ ... Restore Text Window information
-----------------------------------------
This Active Text Variable restores the Text Window to the settings
active when $STW$ (Save Text Window) was executed. The current cursor
location, ANSI attributes, cursor ON/OFF status, vertical scrolling
margins, and the System Font are restored.

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

     Example:  $RTW$
     Returns:  nothing



$TWIN$ ... Text  Window Status
------------------------------
This Text Variable checks to see if a 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$).

     Example:  $TWIN$
     Returns:  YES



$TWFONT$ ... Active Text Font
-----------------------------
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

     Example:  $TWFONT$
     Returns:  1



$TWH$ ... Text Window Height
----------------------------
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.

     Example:  $TWH$
     Returns:  25



$TWW$ ... Text Window Width
---------------------------
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.

     Example:  $TWW$
     Returns:  80



$TWX0$ ... Text Window Upper Left X Coordinate
----------------------------------------------
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.

     Example:  $TWX0$
     Returns:  0



$TWY0$ ... Text Window Upper Left Y Coordinate
----------------------------------------------
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.

     Example:  $TWY0$
     Returns:  40



$TWX1$ ... Text Window Lower Right X Coordinate
-----------------------------------------------
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.

     Example:  $TWX1$
     Returns:  80



$TWY1$ ... Text Window Lower Right Y Coordinate
-----------------------------------------------
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.

     Example:  $TWY1$
     Returns:  43



$CURX$ ... Text Cursor X Coordinate
-----------------------------------
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.

     Example:  $CURX$
     Returns:  2



$CURY$ ... Text Cursor Y Coordinate
-----------------------------------
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.

     Example:  $CURY$
     Returns:  5



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

     Example:  $CON$
     Returns:  nothing



$COFF$ ... Disable the Text Cursor
----------------------------------
This Active Text Variable turns off the text cursor.  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, and NO
if the Text Cursor is disabled.  If there no Text Window, it returns
NO.

     Example:  $CURSOR$
     Returns:  YES



$SCB$ ... Save Clipboard
------------------------
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.

     Example:  $SCB$
     Returns:  nothing



$RCB$ ... Restore Clipboard
---------------------------
This Active Text Variable restores the Clipboard from the temporary
disk file called RIPCLIB.BRD.  This file is created by $SCB$ (Save
Clipboard).  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.

     Example:  $RCB$
     Returns:  nothing



$PCB$ ... Paste Clipboard at last location
------------------------------------------
This Active Text Variable pastes the clipboard at the last location
it was clipped from. This also works with icons.  The last location
taken used is the 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

     Example:  $PCB$
     Returns:  nothing



$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.

     Example:  $APP1$
     Returns:  nothing




=====================================================================
==                 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.





=====================================================================
==                           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 twenty entries for any one list.  In RIPterm    > v1.53
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

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.



===================================================================== > v1.54
==            RIPscrip ICON FILE FORMAT SPECIFICATION             === > v1.54
===================================================================== > v1.54
                                                                      > v1.54
The following section describes the exact file format specification   > v1.54
of the RIPscrip Icon File.  It is identical in design to the Borland  > v1.54
BGI graphics putimage() and getimage() buffer format.                 > v1.54
                                                                      > v1.54
The beginning of the file contains a header structure at file offset  > v1.54
zero.  It is exactly four bytes in length.  Here is the "C" structure > v1.54
definition for this header:                                           > v1.54
                                                                      > v1.54
   struct iconfile_header {                                           > v1.54
          int width;        /* Width  of image in pixels (minus 1) */ > v1.54
          int height;       /* Height of image in lines  (minus 1) */ > v1.54
   };                                                                 > v1.54
                                                                      > v1.54
After the header follows each scan-line of the bitmap.  Each          > v1.54
scan-line is segmented into four chunks in 16-color mode.  In 256     > v1.54
color mode it is segmented into 8 chunks.  All chunks of the          > v1.54
scan-line are monochrome bitmaps of a horizontal line.  Each chunk    > v1.54
is padded to an even 8-pixels (bytes).  Each of the scan-line         > v1.54
chunks are merged together to create one full-scan-line bitmap.       > v1.54
                                                                      > v1.54
After the first scan-line's segments follows the next scan-line's     > v1.54
four segments (or 8), and so on.  After all the scan-lines is 1-byte  > v1.54
of "trash" data which is never used and its value is undefined (who   > v1.54
knows why?)...                                                        > v1.54
                                                                      > v1.54
The general format of an iconfile buffer is:                          > v1.54
     _______________________________                                  > v1.54
    |                               |                                 > v1.54
    |            HEADER             |  4 bytes                        > v1.54
    |_______________________________|                                 > v1.54
    |                               |                                 > v1.54
    |  Scan line #1 (bit plane 3)   |                                 > v1.54
    |  Scan line #1 (bit plane 2)   |                                 > v1.54
    |  Scan line #1 (bit plane 1)   |                                 > v1.54
    |  Scan line #1 (bit plane 0)   |                                 > v1.54
    |_______________________________|                                 > v1.54
    |                               |                                 > v1.54
    |  Scan line #2 (bit plane 3)   |                                 > v1.54
    |  Scan line #2 (bit plane 2)   |                                 > v1.54
    |  Scan line #2 (bit plane 1)   |                                 > v1.54
    |  Scan line #2 (bit plane 0)   |                                 > v1.54
    |_______________________________|                                 > v1.54
    |                               |                                 > v1.54
    |  Scan line #n (bit plane 3)   |                                 > v1.54
    |  Scan line #n (bit plane 2)   |                                 > v1.54
    |  Scan line #n (bit plane 1)   |                                 > v1.54
    |  Scan line #n (bit plane 0)   |                                 > v1.54
    |_______________________________|                                 > v1.54
    |                               |                                 > v1.54
    |           TRASH BYTE          |   1 byte                        > v1.54
    |_______________________________|                                 > v1.54
                                                                      > v1.54
                                                                      > v1.54
Example:                                                              > v1.54
                                                                      > v1.54
If you had a bitmap image (2 scan lines high) containing the          > v1.54
following pixel colors:                                               > v1.54
                                                                      > v1.54
                    < X pos >                                         > v1.54
                0  1  2  3  4  5                                      > v1.54
              -------------------                                     > v1.54
     <Y>   0 | 00 01 02 04 08 0F                                      > v1.54
           1 | 03 05 08 03 02 01                                      > v1.54
                                                                      > v1.54
IN BINARY:                                                            > v1.54
                                                                      > v1.54
     0000 0001 0010 0100 1000 1111                                    > v1.54
     0011 0101 1000 0011 0010 0001                                    > v1.54
     ||| \                                                            > v1.54
     || \ \                                                           > v1.54
     | \ \ \                                                          > v1.54
      \ \ \ \ Bit plane #0                                            > v1.54
       \ \ \                                                          > v1.54
        \ \ \ Bit plane #1                                            > v1.54
         \ \                                                          > v1.54
          \ \ Bit plane #2                                            > v1.54
           \                                                          > v1.54
            \ Bit plane #3                                            > v1.54
                                                                      > v1.54
Breaking this up into bit-planes, you have the following four         > v1.54
monochrome patterns (in reverse order):                               > v1.54
                                                                      > v1.54
     000011    Bit plane #3   (bit #3 in each pixel)                  > v1.54
     001000                                                           > v1.54
                                                                      > v1.54
     000101    Bit plane #2   (bit #2 in each pixel)                  > v1.54
     010000                                                           > v1.54
                                                                      > v1.54
     001001    Bit plane #1   (bit #1 in each pixel)                  > v1.54
     100110                                                           > v1.54
                                                                      > v1.54
     010001    Bit plane #0   (bit #0 in each pixel)                  > v1.54
     110101                                                           > v1.54
                                                                      > v1.54
Since these bit patterns are not an even byte in size, pad remaining  > v1.54
bits on the right with 0 bits (these are "don't care bits"):          > v1.54
                                                                      > v1.54
            vv--- don't care bits                                     > v1.54
   A: 00001100 = 0Ch - Bit plane #3               WIDTH  = 6 pixels   > v1.54
   B: 00100000 = 20h                              HEIGHT = 2 lines    > v1.54
                                                                      > v1.54
   C: 00010100 = 14h - Bit plane #2                                   > v1.54
   D: 01000000 = 40h                                                  > v1.54
                                                                      > v1.54
   E: 00100100 = 24h - Bit plane #1                                   > v1.54
   F: 10011000 = 98h                                                  > v1.54
                                                                      > v1.54
   G: 01000100 = 44h - Bit plane #0                                   > v1.54
   H: 11010100 = C4h                                                  > v1.54
                                                                      > v1.54
                                                                      > v1.54
The final structure of the entire iconfile buffer would be as follows > v1.54
in this example:                                                      > v1.54
                                                                      > v1.54
   Offset  VALUE             Ref    Description                       > v1.54
   ==============================================================     > v1.54
     00:   05 00          /* ---    Width  6-1=5               */     > v1.54
     02:   01 00          /* ---    Height 2-1=1               */     > v1.54
     04:   0C             /* (A)    Scan line #0, bit plane #3 */     > v1.54
     05:   14             /* (C)    Scan line #0, bit plane #2 */     > v1.54
     06:   24             /* (E)    Scan line #0, bit plane #1 */     > v1.54
     07:   44             /* (G)    Scan line #0, bit plane #0 */     > v1.54
                                                                      > v1.54
     08:   20             /* (B)    Scan line #1, bit plane #3 */     > v1.54
     09:   40             /* (D)    Scan line #1, bit plane #2 */     > v1.54
     0A:   98             /* (F)    Scan line #1, bit plane #1 */     > v1.54
     0B:   C4             /* (H)    Scan line #1, bit plane #0 */     > v1.54
                                                                      > v1.54
     0C:   00             /* ---    TRASH BYTE - UNKNOWN VALUE */     > v1.54

