💾 Archived View for spam.works › mirrors › textfiles › computers › ripscrip.txt captured on 2023-06-14 at 16:05:07.
-=-=-=-=-=-=-
------------------------------------------
RIPscrip Graphics Protocol Specification
"Remote Imaging Protocol"
Copyright (c) 1992-1993
TeleGrafix Communications, Inc.
All Rights Reserved
Revision 1.53.00
May 12th, 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, RIPterm or RIPscrip development
tools, 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)
=====================================================================
== USE OF 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.53.00 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.
ANSI SEQUENCES
--------------
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
RIPSCRIPxxyyzz where xx is equal to the major version
number (zero padded), yy is equal to the minor version
number (zero padded), and zz equals the revision code (also
zero padded). For v1.53.00, the returned sequence would be
RIPSCRIP015300. Another example, v1.23.45 would return
RIPSCRIP012345.
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.
=====================================================================
== 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.
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
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 and 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
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 is "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 and 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
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, all Mouse
Regions are deleted and the Clipboard is erased. A system might use this
function before entering a text 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 the Text Window to the 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
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
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
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
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 text line from the 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
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 the current Drawing Color for graphics primitives
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
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 RIP 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
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 RIP 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
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
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
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 location
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
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 location
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
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 the 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
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
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
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
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 solid, 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
This command fills a rectangular region with the current fill color and
pattern. No border is drawn.
RIP_CIRCLE
----------
Function: Draw a circle in the 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
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 the 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
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/fill 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
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
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:
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
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:
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
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
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
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.
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.
RIP_POLYGON
-----------
Function: Draw a polygon in the current color, line style, thickness
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
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 a filled polygon using drawing color & fill settings
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
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.
RIP_FILL
--------
Function: Flood fill screen area with the 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
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.
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
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
--------------------------------------------------------
00 Normal, Solid Line
01 Dotted Line
02 Centered Line
03 Dashed Line
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) and 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
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.)
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 color:2
Format: !|s <c1> <c2> <c3> <c4> <c5> <c6> <c7> <c8> <color>
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
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 <color> 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
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 <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.).
NOTE: You are limited to a maximum of 128 Mouse Regions. 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
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
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 the 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
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
except for the last line of a paragraph and sets of indented
lines.
If a text line falls off the bottom of the region, it is discarded -- the
rectangular Text Region does not scroll.
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
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 screen 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
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 (icon) 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
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
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 the 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
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
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
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 is 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. See the Section in
this manual for a "Table of MegaNums".
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 Adjust 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
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 top of char
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:
Value 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/center/bottom) Y Y Y Y Y
16 Right Justify Label (top/center/bottom) Y Y Y Y Y
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
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 is enabled 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.
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 bloc 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
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
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
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!
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
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
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
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
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.
=====================================================================
== 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
===========================================================
^G ... Beep ^[[A ... Up Arrow
^L ... Clear Screen (Top of Form) ^[[B ... Down Arrow
^M ... Carriage Return ^[[C ... Right Arrow
^C ... Break (sometimes) ^[[D ... Left Arrow
^H ... Backspace ^[[H ... Home Key
^[ ... Escape character ^[[K ... End Key
^S ... Pause data transmission ^[[L ... Control Home
^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.
-- 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. When this Text Variable is used, it will respond back with
"RIPSCRIP" followed by the full Version Number (e.g., 01.53.00), without
the periods.
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); // the 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 blast away with the bset of them. Trivia
question: What is 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.
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.
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.
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).
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:
{body}gt;MYFILE.RIP$
{body}gt;FILE1$
{body}gt;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
version 1.52 and earlier, the total length of a pick list was 256 bytes.
In version 1.53 and later, this limit has been increased to 1024 bytes.
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.