                               TABLE OF CONTENTS
═══════════════════════════════════════════════════════════════════════════════

1        ■ Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
1.1      ■ Use of the RIPscrip Language  . . . . . . . . . . . . . . . .   3
1.2      ■ Definition  . . . . . . . . . . . . . . . . . . . . . . . . .   4
1.3      ■ How Does RIPscrip Work? . . . . . . . . . . . . . . . . . . .   5
1.4      ■ Revision History Notation . . . . . . . . . . . . . . . . . .   6
1.4.1    ■ Revision 2.A4 . . . . . . . . . . . . . . . . . . . . . . . .   7
1.4.2    ■ Revision 2.A3 . . . . . . . . . . . . . . . . . . . . . . . .  10
1.4.3    ■ Revision 2.A2 . . . . . . . . . . . . . . . . . . . . . . . .  11
1.4.4    ■ Revision 2.A1 . . . . . . . . . . . . . . . . . . . . . . . .  13
1.4.5    ■ Revision 2.A0 . . . . . . . . . . . . . . . . . . . . . . . .  17
1.5      ■ Differences from 1.54 and 2.00 formats  . . . . . . . . . . .  18
1.6      ■ Backward Compatibility Topics . . . . . . . . . . . . . . . .  19
2        ■ How RIPscrip is Designed - Fundamental Topics . . . . . . . .  20
2.1      ■ Drawing Ports - What Are They?  . . . . . . . . . . . . . . .  21
2.1.1    ■ Screen Drawing Ports  . . . . . . . . . . . . . . . . . . . .  22
2.1.2    ■ Offscreen Drawing Ports (Clipboard Ports) . . . . . . . . . .  23
2.1.3    ■ Ports and Coordinates . . . . . . . . . . . . . . . . . . . .  24
2.1.4    ■ Ports and Viewports . . . . . . . . . . . . . . . . . . . . .  26
2.1.5    ■ Ports, Viewports and Graphical Operations . . . . . . . . . .  28
2.1.6    ■ Copying data from one port to another . . . . . . . . . . . .  29
2.2      ■ Data Tables - A Fundamental 2.0 Concept . . . . . . . . . . .  31
2.2.1    ■ Types of Data Tables  . . . . . . . . . . . . . . . . . . . .  32
2.2.1.1  ■ Drawing Port Table  . . . . . . . . . . . . . . . . . . . . .  33
2.2.1.2  ■ Color Palette Table . . . . . . . . . . . . . . . . . . . . .  34
2.2.1.3  ■ Graphical Style Table . . . . . . . . . . . . . . . . . . . .  35
2.2.1.4  ■ Button Style Table  . . . . . . . . . . . . . . . . . . . . .  36
2.2.1.5  ■ Text Window Table . . . . . . . . . . . . . . . . . . . . . .  37
2.2.1.6  ■ Environment Table . . . . . . . . . . . . . . . . . . . . . .  38
2.2.1.7  ■ Mouse Field Table . . . . . . . . . . . . . . . . . . . . . .  39
2.2.2    ■ Protected Data Table Entries  . . . . . . . . . . . . . . . .  40
2.3      ■ Data Backup Areas . . . . . . . . . . . . . . . . . . . . . .  42
2.3.1    ■ Data Backup Areas - Protection and Restoration  . . . . . . .  47
2.3.2    ■ Invidual Data Backup Areas  . . . . . . . . . . . . . . . . .  48
2.3.2.1  ■ Button Style Table Save Area  . . . . . . . . . . . . . . . .  49
2.3.2.2  ■ Graphical Style Table Save Area . . . . . . . . . . . . . . .  50
2.3.2.3  ■ Drawing Port Table Save Area  . . . . . . . . . . . . . . . .  51
2.3.2.4  ■ Text Window Table Save Area . . . . . . . . . . . . . . . . .  52
2.3.2.5  ■ Color Palette Table Save Area . . . . . . . . . . . . . . . .  53
2.3.2.6  ■ Mouse Field Table Save Area . . . . . . . . . . . . . . . . .  54
2.3.2.7  ■ Screen Save Area  . . . . . . . . . . . . . . . . . . . . . .  55
2.3.2.8  ■ Environment Table Save Area . . . . . . . . . . . . . . . . .  56
2.4      ■ Numerical Parameters - Formats and Base-Math Variations . . .  58
2.5      ■ World Coordinate Systems  . . . . . . . . . . . . . . . . . .  61
2.6      ■ The Mathematics of Graphics and Coordinates . . . . . . . . .  62
2.7      ■ Color Palettes and Hardware - Color Translation . . . . . . .  70
2.7.1    ■ Color Palettes and Hardware - The Drawing Palette . . . . . .  74
2.7.2    ■ Color Palettes - Palette Mapping and Direct RGB Mode  . . . .  76
2.7.3    ■ Default RGB Values of Color Lookup Table  . . . . . . . . . .  78
2.8      ■ Audio (Sound and Music) Formats . . . . . . . . . . . . . . .  81
2.9      ■ Text Windows and Terminal Emulation Protocols . . . . . . . .  82
2.10     ■ Viewports and Text Windows - Overlapping Issues . . . . . . .  83
2.11     ■ Miscellaneous Notes/Information . . . . . . . . . . . . . . .  84
3        ■ RIPscrip Protocol Definition  . . . . . . . . . . . . . . . .  85
3.1      ■ ANSI Sequences (Auto-Sensing) . . . . . . . . . . . . . . . .  86

═══════════════════════════════════════════════════════════════════════════════
                                       i
                         TABLE OF CONTENTS (continued)
═══════════════════════════════════════════════════════════════════════════════

3.2      ■ RIPscrip Protocol - Syntax and General Structure  . . . . . .  88
3.3      ■ Description of RIPscrip Command Levels  . . . . . . . . . . .  92
3.4      ■ RIPscrip Command Reference  . . . . . . . . . . . . . . . . .  93
3.4.1    ■ Level-0 RIPscrip Commands . . . . . . . . . . . . . . . . . .  95
3.4.1.1  ■ RIP_ARC . . . . . . . . . . . . . . . . . . . . . . . . . . .  96
3.4.1.2  ■ RIP_BACK_COLOR  . . . . . . . . . . . . . . . . . . . . . . .  97
3.4.1.3  ■ RIP_BAR . . . . . . . . . . . . . . . . . . . . . . . . . . .  98
3.4.1.4  ■ RIP_BEZIER  . . . . . . . . . . . . . . . . . . . . . . . . .  99
3.4.1.5  ■ RIP_CIRCLE  . . . . . . . . . . . . . . . . . . . . . . . . . 100
3.4.1.6  ■ RIP_COLOR . . . . . . . . . . . . . . . . . . . . . . . . . . 101
3.4.1.7  ■ RIP_COMMENT . . . . . . . . . . . . . . . . . . . . . . . . . 104
3.4.1.8  ■ RIP_ERASE_EOL . . . . . . . . . . . . . . . . . . . . . . . . 105
3.4.1.9  ■ RIP_ERASE_VIEW  . . . . . . . . . . . . . . . . . . . . . . . 106
3.4.1.10 ■ RIP_ERASE_WINDOW  . . . . . . . . . . . . . . . . . . . . . . 107
3.4.1.11 ■ RIP_EXTENDED_FONT_STYLE . . . . . . . . . . . . . . . . . . . 108
3.4.1.12 ■ RIP_EXTENDED_TEXT_WINDOW  . . . . . . . . . . . . . . . . . . 111
3.4.1.13 ■ RIP_FILL  . . . . . . . . . . . . . . . . . . . . . . . . . . 115
3.4.1.14 ■ RIP_FILL_PATTERN  . . . . . . . . . . . . . . . . . . . . . . 116
3.4.1.15 ■ RIP_FILL_STYLE  . . . . . . . . . . . . . . . . . . . . . . . 118
3.4.1.16 ■ RIP_FILLED_CIRCLE . . . . . . . . . . . . . . . . . . . . . . 121
3.4.1.17 ■ RIP_FILLED_OVAL . . . . . . . . . . . . . . . . . . . . . . . 122
3.4.1.18 ■ RIP_FILLED_POLYGON  . . . . . . . . . . . . . . . . . . . . . 123
3.4.1.19 ■ RIP_FILLED_POLY_BEZIER  . . . . . . . . . . . . . . . . . . . 124
3.4.1.20 ■ RIP_FILLED_RECTANGLE  . . . . . . . . . . . . . . . . . . . . 125
3.4.1.21 ■ RIP_FILLED_ROUNDED_RECT . . . . . . . . . . . . . . . . . . . 126
3.4.1.22 ■ RIP_FONT_STYLE  . . . . . . . . . . . . . . . . . . . . . . . 127
3.4.1.23 ■ RIP_GOTOXY  . . . . . . . . . . . . . . . . . . . . . . . . . 134
3.4.1.24 ■ RIP_GROUP_BEGIN . . . . . . . . . . . . . . . . . . . . . . . 135
3.4.1.25 ■ RIP_GROUP_END . . . . . . . . . . . . . . . . . . . . . . . . 136
3.4.1.26 ■ RIP_HEADER  . . . . . . . . . . . . . . . . . . . . . . . . . 137
3.4.1.27 ■ RIP_HOME  . . . . . . . . . . . . . . . . . . . . . . . . . . 140
3.4.1.28 ■ RIP_LINE  . . . . . . . . . . . . . . . . . . . . . . . . . . 141
3.4.1.29 ■ RIP_LINE_STYLE  . . . . . . . . . . . . . . . . . . . . . . . 142
3.4.1.30 ■ RIP_MOVE  . . . . . . . . . . . . . . . . . . . . . . . . . . 144
3.4.1.31 ■ RIP_NO_MORE . . . . . . . . . . . . . . . . . . . . . . . . . 145
3.4.1.32 ■ RIP_ONE_DRAWING_PALETTE . . . . . . . . . . . . . . . . . . . 146
3.4.1.33 ■ RIP_ONE_PALETTE . . . . . . . . . . . . . . . . . . . . . . . 147
3.4.1.34 ■ RIP_OVAL  . . . . . . . . . . . . . . . . . . . . . . . . . . 148
3.4.1.35 ■ RIP_OVAL_ARC  . . . . . . . . . . . . . . . . . . . . . . . . 149
3.4.1.36 ■ RIP_OVAL_PIE_SLICE  . . . . . . . . . . . . . . . . . . . . . 150
3.4.1.37 ■ RIP_PIE_SLICE . . . . . . . . . . . . . . . . . . . . . . . . 151
3.4.1.38 ■ RIP_PIXEL . . . . . . . . . . . . . . . . . . . . . . . . . . 152
3.4.1.39 ■ RIP_POLYGON . . . . . . . . . . . . . . . . . . . . . . . . . 153
3.4.1.40 ■ RIP_POLYLINE  . . . . . . . . . . . . . . . . . . . . . . . . 154
3.4.1.41 ■ RIP_POLY_BEZIER . . . . . . . . . . . . . . . . . . . . . . . 155
3.4.1.42 ■ RIP_POLY_BEZIER_LINE  . . . . . . . . . . . . . . . . . . . . 159
3.4.1.43 ■ RIP_RECTANGLE . . . . . . . . . . . . . . . . . . . . . . . . 160
3.4.1.44 ■ RIP_RESET_WINDOWS . . . . . . . . . . . . . . . . . . . . . . 161
3.4.1.45 ■ RIP_ROUNDED_RECT  . . . . . . . . . . . . . . . . . . . . . . 162
3.4.1.46 ■ RIP_SET_BASE_MATH . . . . . . . . . . . . . . . . . . . . . . 163
3.4.1.47 ■ RIP_SET_BORDER  . . . . . . . . . . . . . . . . . . . . . . . 164
3.4.1.48 ■ RIP_SET_COLOR_MODE  . . . . . . . . . . . . . . . . . . . . . 165
3.4.1.49 ■ RIP_SET_COORDINATE_SIZE . . . . . . . . . . . . . . . . . . . 166
3.4.1.50 ■ RIP_SET_DRAWING_PALETTE . . . . . . . . . . . . . . . . . . . 167
3.4.1.51 ■ RIP_SET_PALETTE . . . . . . . . . . . . . . . . . . . . . . . 168

═══════════════════════════════════════════════════════════════════════════════
                                       ii
                         TABLE OF CONTENTS (continued)
═══════════════════════════════════════════════════════════════════════════════

3.4.1.52 ■ RIP_SET_WORLD_FRAME . . . . . . . . . . . . . . . . . . . . . 169
3.4.1.53 ■ RIP_TEXT  . . . . . . . . . . . . . . . . . . . . . . . . . . 172
3.4.1.54 ■ RIP_TEXT_WINDOW . . . . . . . . . . . . . . . . . . . . . . . 173
3.4.1.55 ■ RIP_TEXT_XY . . . . . . . . . . . . . . . . . . . . . . . . . 175
3.4.1.56 ■ RIP_VIEWPORT  . . . . . . . . . . . . . . . . . . . . . . . . 176
3.4.1.57 ■ RIP_WRITE_MODE  . . . . . . . . . . . . . . . . . . . . . . . 178
3.4.2    ■ Level-1 RIPscrip Commands . . . . . . . . . . . . . . . . . . 180
3.4.2.1  ■ RIP_BEGIN_TEXT  . . . . . . . . . . . . . . . . . . . . . . . 181
3.4.2.2  ■ RIP_BUTTON  . . . . . . . . . . . . . . . . . . . . . . . . . 182
3.4.2.3  ■ RIP_BUTTON_STYLE  . . . . . . . . . . . . . . . . . . . . . . 185
3.4.2.4  ■ RIP_COPY_BLIT . . . . . . . . . . . . . . . . . . . . . . . . 196
3.4.2.5  ■ RIP_DEFINE  . . . . . . . . . . . . . . . . . . . . . . . . . 197
3.4.2.6  ■ RIP_END_TEXT  . . . . . . . . . . . . . . . . . . . . . . . . 199
3.4.2.7  ■ RIP_FILE_QUERY  . . . . . . . . . . . . . . . . . . . . . . . 200
3.4.2.8  ■ RIP_GET_IMAGE . . . . . . . . . . . . . . . . . . . . . . . . 201
3.4.2.9  ■ RIP_IMAGE . . . . . . . . . . . . . . . . . . . . . . . . . . 202
3.4.2.10 ■ RIP_IMAGE_STYLE . . . . . . . . . . . . . . . . . . . . . . . 203
3.4.2.11 ■ RIP_KILL_ENCLOSED_MOUSE_FIELDS  . . . . . . . . . . . . . . . 205
3.4.2.12 ■ RIP_KILL_MOUSE_FIELDS . . . . . . . . . . . . . . . . . . . . 207
3.4.2.13 ■ RIP_LOAD_BITMAP . . . . . . . . . . . . . . . . . . . . . . . 208
3.4.2.14 ■ RIP_LOAD_ICON . . . . . . . . . . . . . . . . . . . . . . . . 212
3.4.2.15 ■ RIP_MOUSE . . . . . . . . . . . . . . . . . . . . . . . . . . 214
3.4.2.16 ■ RIP_PLAY_AUDIO  . . . . . . . . . . . . . . . . . . . . . . . 216
3.4.2.17 ■ RIP_PUT_IMAGE . . . . . . . . . . . . . . . . . . . . . . . . 217
3.4.2.18 ■ RIP_QUERY . . . . . . . . . . . . . . . . . . . . . . . . . . 218
3.4.2.19 ■ RIP_READ_SCENE  . . . . . . . . . . . . . . . . . . . . . . . 221
3.4.2.20 ■ RIP_REGION_TEXT . . . . . . . . . . . . . . . . . . . . . . . 222
3.4.2.21 ■ RIP_SCROLL  . . . . . . . . . . . . . . . . . . . . . . . . . 223
3.4.2.22 ■ RIP_SET_MOUSE_CURSOR  . . . . . . . . . . . . . . . . . . . . 224
3.4.2.23 ■ RIP_WRITE_ICON  . . . . . . . . . . . . . . . . . . . . . . . 225
3.4.3    ■ Level-2 RIPscrip Commands . . . . . . . . . . . . . . . . . . 226
3.4.3.1  ■ RIP_DEFINE_PORT . . . . . . . . . . . . . . . . . . . . . . . 227
3.4.3.2  ■ RIP_DELETE_PORT . . . . . . . . . . . . . . . . . . . . . . . 229
3.4.3.3  ■ RIP_PORT_COPY . . . . . . . . . . . . . . . . . . . . . . . . 230
3.4.3.4  ■ RIP_PORT_WRITE  . . . . . . . . . . . . . . . . . . . . . . . 232
3.4.3.5  ■ RIP_SET_REFRESH . . . . . . . . . . . . . . . . . . . . . . . 233
3.4.3.6  ■ RIP_SWITCH_BUTTON_STYLE . . . . . . . . . . . . . . . . . . . 234
3.4.3.7  ■ RIP_SWITCH_ENVIRONMENT  . . . . . . . . . . . . . . . . . . . 235
3.4.3.8  ■ RIP_SWITCH_PALETTE  . . . . . . . . . . . . . . . . . . . . . 236
3.4.3.9  ■ RIP_SWITCH_PORT . . . . . . . . . . . . . . . . . . . . . . . 237
3.4.3.10 ■ RIP_SWITCH_TEXT_WINDOW  . . . . . . . . . . . . . . . . . . . 238
3.4.3.11 ■ RIP_SWITCH_STYLE  . . . . . . . . . . . . . . . . . . . . . . 239
3.4.4    ■ Level-3 RIPscrip Commands . . . . . . . . . . . . . . . . . . 240
3.4.4.1  ■ RIP_BAUD_EMULATION  . . . . . . . . . . . . . . . . . . . . . 241
3.4.4.2  ■ RIP_DELAY . . . . . . . . . . . . . . . . . . . . . . . . . . 242
3.4.5    ■ Level-9 RIPscrip Commands . . . . . . . . . . . . . . . . . . 243
3.4.5.1  ■ RIP_ENTER_BLOCK_MODE  . . . . . . . . . . . . . . . . . . . . 244
3.4.5.2  ■ RIP_BEGIN_UUENCODE_BLOCK  . . . . . . . . . . . . . . . . . . 247
4        ■ Host Commands - a Tutorial and Reference Section  . . . . . . 248
4.1      ■ Control Characters  . . . . . . . . . . . . . . . . . . . . . 249
4.2      ■ Text Variables  . . . . . . . . . . . . . . . . . . . . . . . 250
4.2.1    ■ Text Variable Creation and Query  . . . . . . . . . . . . . . 252
4.2.1.1  ■ Pre-Defined Text Variables  . . . . . . . . . . . . . . . . . 253
4.2.1.2  ■ What Are User Variables . . . . . . . . . . . . . . . . . . . 254
4.2.1.3  ■ How Can User Variables Be Important . . . . . . . . . . . . . 255

═══════════════════════════════════════════════════════════════════════════════
                                      iii
                         TABLE OF CONTENTS (continued)
═══════════════════════════════════════════════════════════════════════════════

4.2.1.4  ■ Creating User Variables . . . . . . . . . . . . . . . . . . . 256
4.2.1.5  ■ Defining Text Variables . . . . . . . . . . . . . . . . . . . 257
4.2.1.6  ■ Querying Text Variables . . . . . . . . . . . . . . . . . . . 258
4.2.1.7  ■ Examples of Text Variable Query . . . . . . . . . . . . . . . 259
4.2.1.8  ■ Defining Permanent Variables  . . . . . . . . . . . . . . . . 260
4.2.1.9  ■ User Defined Variables and Data Security  . . . . . . . . . . 265
4.2.1.10 ■ User Defined Data Variable Format Options . . . . . . . . . . 266
4.2.1.11 ■ Limits on Length of Variable Names, Etc.  . . . . . . . . . . 267
4.2.1.12 ■ Examples of User-Defined Text Variables . . . . . . . . . . . 268
4.3      ■ Local RIPscrip File Playback  . . . . . . . . . . . . . . . . 269
4.4      ■ Local Audio File Playback . . . . . . . . . . . . . . . . . . 270
4.5      ■ Local Bitmap File Playback  . . . . . . . . . . . . . . . . . 271
4.6      ■ Local Image File Playback . . . . . . . . . . . . . . . . . . 272
4.7      ■ Pop-Up Lists  . . . . . . . . . . . . . . . . . . . . . . . . 273
4.8      ■ Templates . . . . . . . . . . . . . . . . . . . . . . . . . . 275
4.8.1    ■ Basic Template Mechanics  . . . . . . . . . . . . . . . . . . 277
4.8.2    ■ Radio Button and Check-Box Templates  . . . . . . . . . . . . 278
4.8.3    ■ Taking Advantage of Templates . . . . . . . . . . . . . . . . 280
4.8.4    ■ Embedded Templates  . . . . . . . . . . . . . . . . . . . . . 281
4.8.5    ■ Template Chaining . . . . . . . . . . . . . . . . . . . . . . 283
4.8.6    ■ Advanced Template Concepts  . . . . . . . . . . . . . . . . . 286
4.8.7    ■ Host Command Language and Templates . . . . . . . . . . . . . 288
4.8.8    ■ Processing of Templates . . . . . . . . . . . . . . . . . . . 290
4.8.9    ■ Command Block Segmentation and Templates  . . . . . . . . . . 291
4.8.10   ■ Command Blocks, Radio and Check Box Templates . . . . . . . . 293
4.9      ■ Host Command Directives - What Can Go Where?  . . . . . . . . 294
4.10     ■ Things to Take Special Care With Host Commands  . . . . . . . 295
5        ■ Text Variable Reference . . . . . . . . . . . . . . . . . . . 296
5.1      ■ Text Variable Syntax Descriptions . . . . . . . . . . . . . . 297
5.2      ■ Version Number and Vendor Text Variables  . . . . . . . . . . 300
5.2.1    ■ $IFS$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
5.2.2    ■ $NULL$  . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
5.2.3    ■ $RIPVER$  . . . . . . . . . . . . . . . . . . . . . . . . . . 303
5.2.4    ■ $TERMINFO$  . . . . . . . . . . . . . . . . . . . . . . . . . 303
5.3      ■ Date and Time Text Variables  . . . . . . . . . . . . . . . . 304
5.3.1    ■ $ADOW$  . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
5.3.2    ■ $AMPM$  . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
5.3.3    ■ $DATE$  . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
5.3.4    ■ $DATETIME$  . . . . . . . . . . . . . . . . . . . . . . . . . 305
5.3.5    ■ $DAY$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
5.3.6    ■ $DOW$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
5.3.7    ■ $DOY$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
5.3.8    ■ $FYEAR$ . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
5.3.9    ■ $HOUR$  . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
5.3.10   ■ $MHOUR$ . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
5.3.11   ■ $MIN$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
5.3.12   ■ $MONTH$ . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
5.3.13   ■ $MONTHNUM$  . . . . . . . . . . . . . . . . . . . . . . . . . 308
5.3.14   ■ $SEC$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
5.3.15   ■ $TIME$  . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
5.3.16   ■ $TIMEZONE$  . . . . . . . . . . . . . . . . . . . . . . . . . 308
5.3.17   ■ $WDAY$  . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
5.3.18   ■ $WOY$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
5.3.19   ■ $WOYM$  . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
5.3.20   ■ $YEAR$  . . . . . . . . . . . . . . . . . . . . . . . . . . . 310

═══════════════════════════════════════════════════════════════════════════════
                                       iv
                         TABLE OF CONTENTS (continued)
═══════════════════════════════════════════════════════════════════════════════

5.4      ■ Sound Related Text Variables  . . . . . . . . . . . . . . . . 311
5.4.1    ■ $ALARM$ . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
5.4.2    ■ $BEEP$  . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
5.4.3    ■ $BLIP$  . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
5.4.4    ■ $MUSIC$ . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
5.4.5    ■ $PHASER$  . . . . . . . . . . . . . . . . . . . . . . . . . . 313
5.4.6    ■ $REVPHASER$ . . . . . . . . . . . . . . . . . . . . . . . . . 314
5.4.7    ■ $T$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
5.5      ■ Mouse Related Text Variables  . . . . . . . . . . . . . . . . 317
5.5.1    ■ $M$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
5.5.2    ■ $MCURSOR$ . . . . . . . . . . . . . . . . . . . . . . . . . . 317
5.5.3    ■ $MSTAT$ . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
5.5.4    ■ $X$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
5.5.5    ■ $XY$  . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
5.5.6    ■ $XYM$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
5.5.7    ■ $Y$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
5.6      ■ Text Window Related Text Variables  . . . . . . . . . . . . . 322
5.6.1    ■ $ATW$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
5.6.2    ■ $COFF$  . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
5.6.3    ■ $CON$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
5.6.4    ■ $CURSOR$  . . . . . . . . . . . . . . . . . . . . . . . . . . 324
5.6.5    ■ $CURX$  . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
5.6.6    ■ $CURY$  . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
5.6.7    ■ $DTW$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
5.6.8    ■ $ETW$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
5.6.9    ■ $ISEXTWIN$  . . . . . . . . . . . . . . . . . . . . . . . . . 327
5.6.10   ■ $MTW$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
5.6.11   ■ $RTW$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
5.6.12   ■ $STW$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
5.6.13   ■ $TWERASEEOL$  . . . . . . . . . . . . . . . . . . . . . . . . 330
5.6.14   ■ $TWFONT$  . . . . . . . . . . . . . . . . . . . . . . . . . . 330
5.6.15   ■ $TWGOTO$  . . . . . . . . . . . . . . . . . . . . . . . . . . 331
5.6.16   ■ $TWH$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
5.6.17   ■ $TWHOME$  . . . . . . . . . . . . . . . . . . . . . . . . . . 334
5.6.18   ■ $TWIN$  . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
5.6.19   ■ $TWW$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
5.6.20   ■ $TWX0$  . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
5.6.21   ■ $TWX1$  . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
5.6.22   ■ $TWY0$  . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
5.6.23   ■ $TWY1$  . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
5.7      ■ Port/Viewport Related Text Variables  . . . . . . . . . . . . 344
5.7.1    ■ $AVP$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
5.7.2    ■ $DVP$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
5.7.3    ■ $EGW$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
5.7.4    ■ $MVP$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
5.7.5    ■ $OFFSCREEN$ . . . . . . . . . . . . . . . . . . . . . . . . . 347
5.7.6    ■ $PORTH$ . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
5.7.7    ■ $PORTW$ . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
5.7.8    ■ $PORTX0$  . . . . . . . . . . . . . . . . . . . . . . . . . . 349
5.7.9    ■ $PORTX1$  . . . . . . . . . . . . . . . . . . . . . . . . . . 350
5.7.10   ■ $PORTY0$  . . . . . . . . . . . . . . . . . . . . . . . . . . 351
5.7.11   ■ $PORTY1$  . . . . . . . . . . . . . . . . . . . . . . . . . . 351
5.8      ■ Terminal Operation Text Variables . . . . . . . . . . . . . . 352
5.8.1    ■ $APP$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
5.8.2    ■ $APPx$  . . . . . . . . . . . . . . . . . . . . . . . . . . . 352

═══════════════════════════════════════════════════════════════════════════════
                                       v
                         TABLE OF CONTENTS (continued)
═══════════════════════════════════════════════════════════════════════════════

5.8.3    ■ $BAUDEMUL$  . . . . . . . . . . . . . . . . . . . . . . . . . 353
5.8.4    ■ $D$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
5.8.5    ■ $DWAYOFF$ . . . . . . . . . . . . . . . . . . . . . . . . . . 354
5.8.6    ■ $DWAYON$  . . . . . . . . . . . . . . . . . . . . . . . . . . 354
5.8.7    ■ $FILEDEL$ . . . . . . . . . . . . . . . . . . . . . . . . . . 354
5.8.8    ■ $HKEYOFF$ . . . . . . . . . . . . . . . . . . . . . . . . . . 355
5.8.9    ■ $HKEYON$  . . . . . . . . . . . . . . . . . . . . . . . . . . 355
5.8.10   ■ $NOREFRESH$ . . . . . . . . . . . . . . . . . . . . . . . . . 355
5.8.11   ■ $OPTION$  . . . . . . . . . . . . . . . . . . . . . . . . . . 356
5.8.12   ■ $REFRESH$ . . . . . . . . . . . . . . . . . . . . . . . . . . 357
5.8.13   ■ $SBAROFF$ . . . . . . . . . . . . . . . . . . . . . . . . . . 357
5.8.14   ■ $SBARON$  . . . . . . . . . . . . . . . . . . . . . . . . . . 357
5.8.15   ■ $STATBAR$ . . . . . . . . . . . . . . . . . . . . . . . . . . 358
5.8.16   ■ $TABOFF$  . . . . . . . . . . . . . . . . . . . . . . . . . . 358
5.8.17   ■ $TABON$ . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
5.8.18   ■ $VT102OFF$  . . . . . . . . . . . . . . . . . . . . . . . . . 358
5.8.19   ■ $VT102ON$ . . . . . . . . . . . . . . . . . . . . . . . . . . 359
5.9      ■ RIPscrip Reset Related Text Variables . . . . . . . . . . . . 360
5.9.1    ■ $RESET$ . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
5.10     ■ RIPscrip Environment Configuration Text Variables . . . . . . 366
5.10.1   ■ $BASEMATH$  . . . . . . . . . . . . . . . . . . . . . . . . . 366
5.10.2   ■ $CLS$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
5.10.3   ■ $COLORMODE$ . . . . . . . . . . . . . . . . . . . . . . . . . 367
5.10.4   ■ $COLORS$  . . . . . . . . . . . . . . . . . . . . . . . . . . 368
5.10.5   ■ $COMPAT$  . . . . . . . . . . . . . . . . . . . . . . . . . . 368
5.10.6   ■ $COORDSIZE$ . . . . . . . . . . . . . . . . . . . . . . . . . 369
5.10.7   ■ $ISPALETTE$ . . . . . . . . . . . . . . . . . . . . . . . . . 369
5.10.8   ■ $RBS$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
5.10.9   ■ $RCP$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
5.10.10  ■ $RENV$  . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
5.10.11  ■ $RESTOREALL$  . . . . . . . . . . . . . . . . . . . . . . . . 371
5.10.12  ■ $RESX$  . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
5.10.13  ■ $RESY$  . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
5.10.14  ■ $RGS$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
5.10.15  ■ $PALENTRY$  . . . . . . . . . . . . . . . . . . . . . . . . . 373
5.10.16  ■ $SAVEALL$ . . . . . . . . . . . . . . . . . . . . . . . . . . 374
5.10.17  ■ $SBS$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
5.10.18  ■ $SCP$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
5.10.19  ■ $SENV$  . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
5.10.20  ■ $SGS$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
5.10.21  ■ $WORLD$ . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
5.10.22  ■ $WORLDH$  . . . . . . . . . . . . . . . . . . . . . . . . . . 378
5.10.23  ■ $WORLDW$  . . . . . . . . . . . . . . . . . . . . . . . . . . 379
5.11     ■ Clipboard Related Text Variables  . . . . . . . . . . . . . . 380
5.11.1   ■ $PCB$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
5.11.2   ■ $RCB$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
5.11.3   ■ $SCB$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
5.12     ■ Mouse Field Related Text Variables  . . . . . . . . . . . . . 383
5.12.1   ■ $MKILL$ . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
5.12.2   ■ $RMF$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
5.12.3   ■ $SMF$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
5.13     ■ Screen Related Text Variables . . . . . . . . . . . . . . . . 386
5.13.1   ■ $RESTORE$ . . . . . . . . . . . . . . . . . . . . . . . . . . 386
5.13.2   ■ $RESTOREx$  . . . . . . . . . . . . . . . . . . . . . . . . . 386
5.13.3   ■ $SAVE$  . . . . . . . . . . . . . . . . . . . . . . . . . . . 387

═══════════════════════════════════════════════════════════════════════════════
                                       vi
                         TABLE OF CONTENTS (continued)
═══════════════════════════════════════════════════════════════════════════════

5.13.4   ■ $SAVEx$ . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
5.14     ■ Data Table and Backup Area Text Variables . . . . . . . . . . 389
5.14.1   ■ $BACKSTAT$  . . . . . . . . . . . . . . . . . . . . . . . . . 389
5.14.2   ■ $COPY$  . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
5.14.3   ■ $CUR$ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
5.14.4   ■ $INUSE$ . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
5.14.5   ■ $ISPROT$  . . . . . . . . . . . . . . . . . . . . . . . . . . 397
5.14.6   ■ $PROT$  . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
5.14.7   ■ $UNPROT$  . . . . . . . . . . . . . . . . . . . . . . . . . . 400
6        ■ RIPscrip Icon File Format Specification . . . . . . . . . . . 402
6.1      ■ Device Independent Bitmap (DIB) File Format . . . . . . . . . 403
6.1.1    ■ DIB File Header . . . . . . . . . . . . . . . . . . . . . . . 404
6.1.2    ■ DIB Color Table Format  . . . . . . . . . . . . . . . . . . . 406
6.1.3    ■ DIB Bitmap Data Block Format  . . . . . . . . . . . . . . . . 407
6.1.4    ■ DIB Miscellaneous Notes . . . . . . . . . . . . . . . . . . . 409


═══════════════════════════════════════════════════════════════════════════════
                                      vii
   ╔══════════════════════════════════════════════════════════════╗
   ║                                                              ║░░
   ║                 RIPscrip Graphics Protocol                   ║░░
   ║                Language Technical Reference                  ║░░
   ║             ──────────────────────────────────               ║░░
   ║                   Copyright (c) 1992-1994                    ║░░
   ║               TeleGrafix Communications, Inc.                ║░░
   ║                     All Rights Reserved                      ║░░
   ║             ──────────────────────────────────               ║░░
   ║                        VERSION 2.00                          ║░░
   ║                      REVISION ALPHA 4                        ║░░
   ║                 ──────────────────────────                   ║░░
   ║                   (proposed enhancements)                    ║░░
   ║                                                              ║░░
   ║                     ┌─────────────────┐                      ║░░
   ║                     │  CONFIDENTIAL!  │                      ║░░
   ║                     └─────────────────┘                      ║░░
   ║                                                              ║░░
   ║                    December 13th, 1994                       ║░░
   ║                                                              ║░░
   ╚══════════════════════════════════════════════════════════════╝░░
     ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░



╔══════════════════╗
║ 1 ■ 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.



╔════════════════════════════════════╗
║ 1.1 ■ USE OF THE RIPscrip LANGUAGE ║
╚════════════════════════════════════╝

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

RIPscrip, RIPaint, RIPdraw, and RIPterm are trademarks of TeleGrafix
Communications, Inc.  If you make a product that uses RIPscrip, you
must state in your program's "About Box" and documentation that this
product uses RIPscrip and the trademark statement.  You may not use
RIPterm, RIPaint, RIPdraw, or RIPterm in the name of your product.
You may also not use any of the preceding names in your product       > v2.A3
literature without prior written consent from an officer of           > v2.A3
TeleGrafix Communications, Inc.                                       > v2.A3

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



╔══════════════════╗
║ 1.2 ■ 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.



╔═══════════════════════════════╗
║ 1.3 ■ HOW DOES RIPscrip WORK? ║
╚═══════════════════════════════╝

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

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

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



╔═════════════════════════════════╗
║ 1.4 ■ REVISION HISTORY NOTATION ║
╚═════════════════════════════════╝

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

THIS VERSION OF THE RIP 2.0 SPECIFICATION IS AN ONGOING CULMINATION   > v2.A0
OF THINGS AND IDEAS FROM MANY PEOPLE.  WITH THAT IN MIND, THERE ARE   > v2.A0
GOING TO BE NUMEROUS REVISIONS OF THE DOCUMENT, SO WE ARE             > v2.A3
USING A SPECIAL NOTATIONAL CONVENTION IN THE RIGHT MARGIN FOR         > v2.A0
THE SPECIFICATION.  THE FIRST REVISION OF THE DOCUMENT                > v2.A0
WILL HAVE "v.2A0" TO INDICATE V2.0 REVISION A0 (ALPHA 0).  EACH       > v2.A0
SUB-REVISION OF THIS DOCUMENT WILL INCREMENT THE 0 TO A HIGHER        > v2.A0
VALUE.  IF WE GO BEYOND 9 (WE HOPE NOT), THEN WE'LL CHANGE "A" TO     > v2.A0
"B", AND SO ON, AND SO ON...                                          > v2.A0

The following sub-sections give detailed information about what has   > v2.A4
changed in each sub-revision of the RIPscrip specification.           > v2.A4



┌───────────────────────┐
│ 1.4.1 ■ REVISION 2.A4 │
└───────────────────────┘

     ■ Changed some of the parameters for user defined text           > v2.A4
       variables.  Specifically, we removed "DATE" and "DECIMAL",     > v2.A4
       renamed "NAME" to "TONAME", and added "TOLOWER" and "TOUPPER". > v2.A4
       In addition, we clearly defined that two parameters are        > v2.A4
       allowed for this variable - a mode parameter and a conversion  > v2.A4
       parameter.                                                     > v2.A4

     ■ Removed justify values 2-3 from the RIP_REGION_TEXT command.   > v2.A4

     ■ Reformatted this document - giving it section numbers, a table > v2.A4
       of contents, and better diagrams.  This should make printing   > v2.A4
       out the specification and working with a printed copy much     > v2.A4
       easier for everyone!  This was done due to popular demand.     > v2.A4

     ■ Added two new commands for switching (they weren't in the      > v2.A4
       previous specs):                                               > v2.A4

          RIP_SWITCH_BUTTON_STYLE                                     > v2.A4
          RIP_SWITCH_ENVIRONMENT                                      > v2.A4

     ■ Removed the <slot> parameter from the RIP_BUTTON_STYLE         > v2.A4
       command.  This command should redefine the current button      > v2.A4
       style - allowing it to directly manipulate specific button     > v2.A4
       style entries goes against the symmetry of the data table      > v2.A4
       system and the rest of RIPscrip's commands that work with      > v2.A4
       them.                                                          > v2.A4

     ■ Order of operation of resident query expressions has been      > v2.A4
       clearly defined.                                               > v2.A4

     ■ Removed the <slot> parameter from the RIP_BUTTON command.      > v2.A4
       This was changed to a reserved parameter.  See the previous    > v2.A4
       item for a description of why we did this.                     > v2.A4

     ■ The parameters of the RIP_LOAD_BITMAP command have been        > v2.A4
       altered.  Specifically, the <duplicate>, <palette> and         > v2.A4
       <dither> parameters were removed and moved into a single       > v2.A4
       <flags> parameter.  Additionally, a new flag was added         > v2.A4
       at the same time for "transparency color".  Also a new         > v2.A4
       parameter was added called <trans_color> which specifies       > v2.A4
       which color is to be transparent in a BMP file.  The           > v2.A4
       reserved parameter was increased to 4 bytes in size after      > v2.A4
       all is said and done to give future grown potential.           > v2.A4

     ■ Re-documented color palette independence and situations        > v2.A4
       relating to color palettes, and color palette mapping.         > v2.A4

     ■ Renamed VIEWX0, VIEWY0, VIEWX1, VIEWY1, VIEWX and VIEWY text
       variables to PORTX0, PORTY0, PORTX1, PORTY1, PORTW, and PORTH
       respectively.

     ■ Added new text variables:

                     $SGS$ ... Save graphics style
                     $RGS$ ... Restore graphics style
                     $SBS$ ... Save button style
                     $RBS$ ... Restore button style


               $OFFSCREEN$ ... Determine offscreen pixel data
                $BACKSTAT$ ... Get status of backup area
                $ISEXTWIN$ ... Is a text window an extended text window?

     ■ Renamed the $SWITCH$ variable to $CUR$ and enhanced its
       capabilities.

     ■ Enhanced the $RESET$ text variable definition.

     ■ Removed the following text variables:

          $CLIP2CLIPOK$
          $CLIPSAVEOK$
          $STACKPOS$
          $STACKCLEAR$

     ■ Added syntax diagrams for every text variable definition to
       make the possible parameters much easier to determine.

     ■ Completely redesigned the $INUSE$, $PROT$, $UNPROT$ and
       $ISPROT$ text variables.  The new variations are much simpler
       in nature and less cumbersome to work with.

     ■ Removed all references to the "drawing coordinate frame"       > v2.A4

     ■ Documented the RIP_EXTENDED_TEXT_WINDOW command for resolution > v2.A4
       independent text windows.                                      > v2.A4

     ■ Revised the text variable system for the extended text window  > v2.A4
       definition.                                                    > v2.A4

     ■ Revised the RIP_KILL_ENCLOSED_MOUSE_FIELDS command to work     > v2.A4
       a bit more efficiently.                                        > v2.A4

     ■ Removed the $TEXTQUERY$ and $VIEWQUERY$ text variables.  They  > v2.A4
       were redundant, and not sufficient to deal with resolution     > v2.A4
       independent text windows, and viewports were simply redundant  > v2.A4
       so the command wasn't necessary.                               > v2.A4

     ■ Revised the definitions of the following text variables:       > v2.A4

               $TWH$               $TWY1$                             > v2.A4
               $TWW$               $TWIN$                             > v2.A4
               $TWHOME$            $CURX$                             > v2.A4
               $TWGOTO$            $CURY$                             > v2.A4
               $TWERASEEOL$        $CURSOR$                           > v2.A4
               $TWX0$              $CON$                              > v2.A4
               $TWY0$              $COFF$                             > v2.A4
               $TWX1$              $TWFONT$                           > v2.A4

     ■ Revised the keywords for some text variables that used the     > v2.A4
       keyword "VIDEO" to indicate hardware device pixel coordinates  > v2.A4
       instead of world coordinate pixels.  These new keywords are    > v2.A4
       now "DEVICE" instead for future extensibility with other       > v2.A4
       display environments (eg, hardcopy, etc).                      > v2.A4

     ■ Enhanced the documentation of "filled regions" to encompass    > v2.A4
       filled polygons and curved surfaces - now these situations     > v2.A4
       are clearly documented.                                        > v2.A4


     ■ Revised diagrams to be more understandable throughout the      > v2.A4
       specification.                                                 > v2.A4

     ■ Revised and enhanced the $RESET$ text variable to accomodate   > v2.A4
       more situations which were overlooked in its original          > v2.A4
       definition.                                                    > v2.A4

     ■ Documented exactly what gets saved in each data backup area.   > v2.A4

     ■ Text windows and viewports that used to be referred to as      > v2.A4
       "disabled" or "enable" are now using the new terminology of    > v2.A4
       "deactivated" and "activated".  This is to help distinguish    > v2.A4
       between the concept of a text window or viewport that is       > v2.A4
       "defined", as opposed to "active", as opposed to "current".    > v2.A4

     ■ Completely re-wrote the documentation on data tables and       > v2.A4
       data backup areas to be clearer on the concepts involved and   > v2.A4
       how "protection" works with data tables, and data backup       > v2.A4
       areas.  The data save stack and data save slot systems have    > v2.A4
       been completley revised to be more "generic" and easier to     > v2.A4
       implement on a target RIPscrip system.  Base save areas        > v2.A4
       can no longer be protected.                                    > v2.A4

     ■ Added a new graphical file format to the "image style"         > v2.A4
       command.  RIPscrip 2.0 now supports GIF (Graphics Interchange  > v2.A4
       Format) files in addition to JPEG files.  This was added due   > v2.A4
       to popular demand because JPEG doesn't handle line art or      > v2.A4
       fine-detail graphics anywhere near as well as GIF does both    > v2.A4
       in terms of size, and quality.  Also, GIF supports interleaved > v2.A4
       images which provide the user with nearly "immediate           > v2.A4
       gratification" when an interleaved image is being displayed.   > v2.A4

     ■ Added another protocol to the list of protocols supported in   > v2.A4
       the RIP_ENTER_BLOCK_MODE command.  It is Super Kermit and it   > v2.A4
       is assigned protocol #9 for block mode.  The $IFS$ protocol    > v2.A4
       keyword for this protocol is "SUPERKERMIT".                    > v2.A4

     ■ Removed the $TERMNAME$, $TERMMFG$ and $TERMVER$ text           > v2.A4
       variables.  Renamed the $TERMDATA$ variable to $TERMINFO$      > v2.A4
       and gave it parameters to cover the removal of the other       > v2.A4
       three variables.  This makes the vendor-specific text          > v2.A4
       variables more generic and flexible in nature.                 > v2.A4

     ■ Altered the multi-lingual support definitions in the spec.     > v2.A4
       Before, we were identifying languages by the three character   > v2.A4
       codes used to represent countries in the Olympics (USA, JAP,   > v2.A4
       SPN, etc).  Since many countries have many different           > v2.A4
       languages, we are changing our strategy to a new coding scheme > v2.A4
       designed to explicitly identify the language, not the country  > v2.A4
       that the user wants.                                           > v2.A4

     ■ The $FEATURE$ text variable has been renamed to $OPTION$ to    > v2.A4
       more closely identify its purpose - to enable or disable       > v2.A4
       specific system options.                                       > v2.A4

     ■ The $IFS$ (is feature supported) text variable has been        > v2.A4
       enhanced to work with the concept of "categories".  This makes > v2.A4
       it so the host can query back pieces of information about      > v2.A4
       specific topics (eg, "what protocols are supported", "what     > v2.A4
       image formats are supported", etc).                            > v2.A4


┌───────────────────────┐
│ 1.4.2 ■ REVISION 2.A3 │
└───────────────────────┘

     ■ Added the RIP_SWITCH_PALETTE command to switch from one        > v2.A3
       palette slot entry to another.                                 > v2.A3

     ■ Added the RIP_FILE_DELETE command to remove unneeded JPEG      > v2.A3
       or WAVE files off the user's hard disk so that they don't      > v2.A3
       clutter things up when they're no longer needed.               > v2.A3

     ■ Added the RIP_ROUNDED_RECT and RIP_FILLED_ROUNDED_RECT         > v2.A3
       commands to make rounded rectangles.                           > v2.A3

     ■ Added the RIP_ROUNDED_RECT and RIP_FILLED_ROUNDED_RECT         > v2.A3
       commands to make rectangles with rounded corners.              > v2.A3

     ■ Added the new port-based definitions for creating and working  > v2.A3
       with on-screen and off-screen drawable areas.  This technology > v2.A3
       upgrades the previous clipboard technology, and gives RIPscrip > v2.A3
       the ability to be able to draw to offscreen bitmaps.  The new  > v2.A3
       port-related commands are: RIP_DEFINE_PORT, RIP_SWITCH_PORT,   > v2.A3
       RIP_DELETE_PORT, RIP_PORT_COPY, and RIP_PORT_WRITE.            > v2.A3

     ■ RIP_SWITCH_TEXT_WINDOW had it's command character changed to   > v2.A3
       be compatible with the new port commands.                      > v2.A3

     ■ RIP_SWITCH_VIEWPORT had it's command character changed to      > v2.A3
       be compatible with the new port commands.                      > v2.A3

     ■ Added the RIP_PLAY_AUDIO command to playback a WAVE file.      > v2.A3

     ■ Removed the RIP_SCROLLER and the Form related text variables.  > v2.A3
       This was necessary to get RIPscrip 2.0 out the door.  These    > v2.A3
       commands and a couple others (eg, RIP_ANIMATE, etc) will       > v2.A3
       probably work their way into a future version of the           > v2.A3
       specification.                                                 > v2.A3



┌───────────────────────┐
│ 1.4.3 ■ REVISION 2.A2 │
└───────────────────────┘

     ■ Documented standard for setting and determining foreign        > v2.A2
       language support.                                              > v2.A2

     ■ Added two new level 0 commands for creating groups of RIPscrip > v2.A2
       commands.  These new commands are RIP_GROUP_BEGIN and          > v2.A2
       RIP_GROUP_END.  These are designed for a paint program to be   > v2.A2
       able to group a number of RIPscrip commands and have them be   > v2.A2
       treated as one object for the purpose of editing and moving.   > v2.A2
       The terminal program just ignores these commands.              > v2.A2

     ■ Added a new <no_border> parameter to the RIP_FILL_STYLE        > v2.A2
       command.  This new parm lets RIPscrip draw filled objects      > v2.A2
       without a border.  This was accomplished by splitting the two  > v2.A2
       byte <pattern> parameter into two one-byte parameters.  This   > v2.A2
       makes the new version of the command backwards compatible.     > v2.A2


     ■ Added RIP_FILLED_RECTANGLE command to complement the new       > v2.A2
       <no_border> parameter of the RIP_FILL_STYLE command.  RIP_BAR  > v2.A2
       could not be updated because by default it has no border, and  > v2.A2
       for backwards compatibility, the border would have to be on    > v2.A2
       by default.  Therefore, the new filled rectangle command.      > v2.A2

     ■ RIP_EXTENDED_FONT has been renamed RIP_EXTENDED_FONT_STYLE,    > v2.A2
       and also expended for furture use so that someday font         > v2.A2
       rotation can be expressed in 1/10's of degrees, and four       > v2.A2
       reserved bytes were added just in case!                        > v2.A2

     ■ Added RIP_POLY_BEZIER_LINE so that you can create a            > v2.A2
       poly-bezier that does not have it's endpoints connected.       > v2.A2

     ■ Added RIP_FILLED_POLY_BEZIER so that you can create a filled   > v2.A2
       poly-bezier object.                                            > v2.A2

     ■ Added RIP_FILLED_CIRCLE for a two-byte shorter filled circle   > v2.A2
       than you can get using RIP_FILLED_OVAL.                        > v2.A2

     ■ RIP_FILL_POLYGON was renamed to RIP_FILLED_POLYGON for         > v2.A2
       consistency with the naming of other filled objects.           > v2.A2

     ■ Changed all icon references to the new icon, hot icon, and     > v2.A2
       icon mask extensions (.ICN is now .BMP, .HIC is now .BMH, and  > v2.A2
       .MSK is now .BMM)                                              > v2.A2

     ■ Added <scale> parameter to the RIP_LOAD_ICON command           > v2.A2

     ■ Documented rename of RIP_COPY_REGION to RIP_SCROLL             > v2.A2

     ■ RIP_POLY_BEZIER added in v2.A1                                 > v2.A2

     ■ RIP_COPY_BLIT added in v2.A1                                   > v2.A2

     ■ LOAD_BITMAP added in v2.A1                                     > v2.A2



     ■ Made corrections to the spec so that all the commands using    > v2.A2
       clipboard slots specify how the slots are being used in the    > v2.A2
       command set.                                                   > v2.A2



┌───────────────────────┐
│ 1.4.4 ■ REVISION 2.A1 │
└───────────────────────┘

     ■ Added the ability to embed raw UU-Encoded data blocks inside   > v2.A1
       RIPscrip encoded files.  This allows you to transmit bitmaps,  > v2.A1
       sound files, and other raw generic binary data over 7-bit      > v2.A1
       ASCII text connections (like Internet, CompuServe, etc).       > v2.A1

     ■ Added some extra text variables for the purpose of extended    > v2.A1
       vendor determination.  Variables for determining the name      > v2.A1
       of the manufacturer, name of the terminal program, actual      > v2.A1
       version number of the terminal, and arbitrary vendor specific  > v2.A1
       data have been supplied for the most flexibility.  This        > v2.A1
       method of determining vendor information is more generic       > v2.A1
       and easier to work with than the vendor-codes used in the      > v2.A1
       $RIPVER$ text variable and the Query RIPscrip version ANSI     > v2.A1
       command.  In effect, the old method of determining vendor      > v2.A1
       codes is obsolete.                                             > v2.A1


     ■ Added a new command for the creation and manipulation of       > v2.A1
       scroller-type user interface objects.  The reason this was     > v2.A1
       added was due to popular demand.  The command for this new     > v2.A1
       object is RIP_SCROLLER.  Using this command really involves    > v2.A1
       some custom programming on the host system to process the      > v2.A1
       selections of a scroller.  We added this so that there's a     > v2.A1
       standardized way of performing scroller operations in          > v2.A1
       RIPscrip.                                                      > v2.A1

     ■ Added the ability to refresh (redraw) any buttons that exist   > v2.A1
       in a particular button style slot number.  This lets you       > v2.A1
       draw a bunch of buttons, alter the button style, then refresh  > v2.A1
       the buttons thus altering their appearance (possibly           > v2.A1
       highlighting all buttons in a group by changing their          > v2.A1
       colors, etc).                                                  > v2.A1

     ■ Added a new command (RIP_SET_REFRESH) which allows the host    > v2.A1
       to define a refresh sequence that, when transmitted, will      > v2.A1
       instruct the host to refresh (redisplay) the current screen.   > v2.A1
       This is defined as a host definable sequence because every     > v2.A1
       host may be different in the ways it refreshes screens and     > v2.A1
       menus, and even different sub-sections of a host may use       > v2.A1
       different refresh methods.  Also, text variables for           > v2.A1
       disabling refresh expressions and to force a refresh           > v2.A1
       operation have been added to round out the refresh feature.    > v2.A1

     ■ Added a RIP_HEADER command which is used to both identify      > v2.A1
       the revision of RIPscrip code that follows and also to         > v2.A1
       allow for widespread flexibility in performing reset           > v2.A1
       operations at the beginning of scenes (above and beyond        > v2.A1
       the RIP_RESET_WINDOWS) command.                                > v2.A1

     ■ Extended the specification where simple graphical primitives   > v2.A1
       are concerned.  In 1.xx versions of RIPscrip, raster           > v2.A1
       operations for simple graphics primitives were limited to      > v2.A1
       COPY and XOR modes.  XOR was only available for simple line    > v2.A1
       based primitives, not for curves like circles, ovals, and      > v2.A1
       various pie slices.  In addition, filled-in areas were not     > v2.A1
       qualified for XOR operations.  In RIPscrip 2.0, these          > v2.A1
       limitations are being lifted.  XOR applies to all primitives.  > v2.A1


       In addition, line patterns and thicknesses are also allowed    > v2.A1
       for the various primitives.  Thickness limitations are no      > v2.A1
       longer constrained to 1 pixel or 3 pixel thicknesses either.   > v2.A1
       Bitmap operations offered raster operations of COPY, XOR,      > v2.A1
       NOT, OR and AND.  In RIPscrip 2.0, these operations are        > v2.A1
       available for all primitives now.                              > v2.A1

     ■ Added an extended font system to the specification.  This      > v2.A1
       provides for the original font systems covering pre-defined    > v2.A1
       font sizes for the default bit-mapped font and simple vector   > v2.A1
       fonts.  This new command provides the ability to draw text     > v2.A1
       in high qualith outline fonts like TrueType (tm).  See         > v2.A1
       RIP_EXTENDED_FONT_STYLE for further details on this command.   > v2.A1

     ■ Added a "local audio playback" text variable command.  This    > v2.A1
       is a variant on the local RIPscrip file playback command.      > v2.A1
       Since you cannot be certain solely from a filename or a        > v2.A1
       file extension if the file is truly a sound file, we have      > v2.A1
       introduced this command to perform sound playback from         > v2.A1
       within host commands or query expressions.                     > v2.A1


       NOTE:  Formal sound file and music file formats have not       > v2.A1
              been established yet for RIPscrip 2.0.  They will       > v2.A1
              be shortly.  This command was added into the spec       > v2.A1
              because its format isn't limited to whatever format     > v2.A1
              is finally chosen.                                      > v2.A1

     ■ Added a "local bitmap playback" text variable command so that  > v2.A1
       you can place icons on the screen from within a host command.  > v2.A1

     ■ Added a "local image playback" text variable command so that   > v2.A1
       you can add photo-quality compressed images onto the screen    > v2.A1
       from within a host command (eg, JPEG files).                   > v2.A1

     ■ Added rule #16 which defines exactly what should be done if    > v2.A1
       a RIPscrip command has too much information or too little.     > v2.A1

     ■ Documented what should happen if multiple viewports overlap    > v2.A1
       or if text windows overlap, or viewports and text windows      > v2.A1
       overlap.                                                       > v2.A1

     ■ Expanded the pop-up picklist feature to support up to 64       > v2.A1
       individual picklist entries instead of the previously defined  > v2.A1
       maximum limit of 20.                                           > v2.A1

     ■ Added a RIP_SET_MOUSE_CURSOR command which allows you to       > v2.A1
       alter the currently defined mouse cursor style.  This lets     > v2.A1
       you change the mouse cursor to something like an hourglass,    > v2.A1
       a pointer, cross-hairs, etc.                                   > v2.A1

     ■ Added a new command, RIP_BACK_COLOR.  This command             > v2.A1
       affects the fill operations.  When you set the fill style or   > v2.A1
       custom user-defined fill pattern, you specify the foreground   > v2.A1
       color for fill operations.  Use this command to set a          > v2.A1
       background color for the fills so you can do two-toned fill    > v2.A1
       operations.  This color may or may not be used for the drawing > v2.A1
       of dashed lines for the odd-dash spaces (see RIP_LINE_STYLE).  > v2.A1



     ■ The RIP_LINE_STYLE command has been altered to support the     > v2.A1
       ability to turn on or off background color drawing for odd     > v2.A1
       dash sequences.  Also, the line thickness parameter of this    > v2.A1
       command has been generalized so that it can support any        > v2.A1
       arbitrary line thickness other than 1 or 3 pixel wide          > v2.A1
       lines.                                                         > v2.A1

     ■ Added a RIP_SET_COORDINATE_SIZE command which allows the       > v2.A1
       alteration of X/Y parameter byte widths.  By default, all      > v2.A1
       X or Y coordinates are 2-byte MegaNums (or UltraNums in        > v2.A1
       2.0).  For situations where a world coordinate system gets     > v2.A1
       very large (greater than 4096 wide), then you will need to     > v2.A1
       increase the size of the coordinates.  This command allows     > v2.A1
       you to make these parameters say, 3 bytes wide, or 4 bytes     > v2.A1
       wide.  In practice, this command probably won't be used        > v2.A1
       much - not until we start seeing very high resolution          > v2.A1
       video devices.                                                 > v2.A1

     ■ Extensive enhancements have been added to text variables.      > v2.A1
       Specifically, text variable "parameters" have been allowed     > v2.A1
       to alter the functionality of text variables.  This applies    > v2.A1
       to built-in text variables and to user-defined text            > v2.A1
       variables.                                                     > v2.A1


     ■ Data Entry Form generation has been added to one of the types  > v2.A1
       of host command data types.  This is a special case of data    > v2.A1
       text variables.                                                > v2.A1

     ■ All SAVE and RESTORE type text variables now adhere to three   > v2.A1
       different mechanisms (up to 10 slots for saving, a slot-less   > v2.A1
       save area and push/pop stack like operations).  In prior       > v2.A1
       releases each type of save/restore had different mechanisms.   > v2.A1
       Now, a uniform methodology has been added which is fully       > v2.A1
       backward compatible and totally identical in nature for all    > v2.A1
       of the various save/restore data types (screen, mouse fields,  > v2.A1
       text windows and clipboard slots).                             > v2.A2

     ■ Added a new mechanism to the save/restore areas that allows    > v2.A1
       slot-less and slot-based save regions to be protected.  A      > v2.A1
       protected slot cannot be erased, copied over or modified       > v2.A1
       by anything other than an unprotect operation or a hard        > v2.A1
       reset operation.  Push and pop operations skip over protected  > v2.A1
       slots.  Also, the ability to move data from slot-less areas    > v2.A1
       to particular slots, and vice versa have been added.           > v2.A1

     ■ Added protection facilities to viewport slots, text window     > v2.A1
       slots, clipboard slots, graphical style slots and to           > v2.A2
       button style slots.  This allows you to protect an entry so    > v2.A1
       that nothing can overwrite or delete it short of a hard        > v2.A1
       reset operation or an unprotect command.                       > v2.A1

     ■ Button styles now have button style slots - up to 36 separate  > v2.A1
       button style slots can be defined simultaneously.  This can    > v2.A1
       reduce data transmission for heavy button applications.        > v2.A1

     ■ An enhanced load icon command has been added which supports    > v2.A1
       scaling and dithering.  This is intended to replace the older  > v2.A1
       RIP_LOAD_ICON command because it does the same thing, and much > v2.A1
       more!                                                          > v2.A1


     ■ Formally defined what a "clipboard slot" is under 2.0          > v2.A2

     ■ Officially defined the file format specification for 2.0 icon  > v2.A1
       bitmap files.  The official file format is BMP files (device   > v2.A1
       independent bitmaps).  See the end of this document for a      > v2.A1
       technical file format specification.                           > v2.A1

     ■ Altered the default palette in 256 color modes.  The new       > v2.A1
       palette is a uniform distribution of Red, Green and Blue       > v2.A1
       for purposes of image reproduction.  A uniform distribution    > v2.A1
       of RGB values provides colors in all parts of the spectrum     > v2.A1
       for as accurate image display as possible without color        > v2.A1
       palette changes.                                               > v2.A1

     ■ Added another syntax rule (#14) to the language definition.    > v2.A1
       This new rule covers the inability in previous releases to     > v2.A1
       use special command characters in text parameters in the       > v2.A1
       language (eg, "$", "[", etc).                                  > v2.A1

     ■ Added the ability to embed comments inside a RIPscrip file.    > v2.A1
       This is syntax rule #15.                                       > v2.A1

     ■ Cropping rectangles for the RIP_IMAGE_STYLE command have       > v2.A1
       been eliminated.  The complexity of cropping sub-area of the   > v2.A1
       image hamper the open development of RIPscrip for v2.0.        > v2.A1
       This may be changed in future versions.                        > v2.A1


     ■ Dynamic image pan/zoom operations have been eliminated from    > v2.A1
       this revision.  Since cropping rectangles are no longer part   > v2.A1
       of the specification, pan and zoom operations aren't really    > v2.A1
       necessary.                                                     > v2.A1

     ■ TIFF files have been removed from the 2.0 specification for    > v2.A1
       image file displaying.  We will be using JPEG and BMP files    > v2.A1
       exclusively for all bitmap image reproductions.                > v2.A1



┌───────────────────────┐
│ 1.4.5 ■ REVISION 2.A0 │
└───────────────────────┘

     ■ Defined the resolution independent coordinate system nature of > v2.A1
       RIPscrip 2.0 (device coordinate frame, world coordinate frame  > v2.A1
       and local [viewport] coordinate frames).                       > v2.A1

     ■ Defined 24-bit color encoding vs. color palette coding         > v2.A1
       methods.                                                       > v2.A1

     ■ Defined 36 separate text window slots                          > v2.A1

     ■ Defined 36 separate graphical viewport slots                   > v2.A1

     ■ Defined 36 separate graphical drawing style slots              > v2.A1

     ■ Defined multiple clipboard slots                               > v2.A2

     ■ Added a Delay command                                          > v2.A1

     ■ Added a Baud Rate Emulation command for local RIP playback     > v2.A1

     ■ Enhanced the button style definitions to support some extra    > v2.A1
       display effect flags                                           > v2.A1

     ■ Enhanced the vector text font styles to support other text     > v2.A1
       font alignments (center, left, right, top, bottom)             > v2.A1

     ■ Defined default color palettes for various modes               > v2.A1

     ■ Defined rectangular fill operation rules for proper resolution > v2.A1
       independent viewing                                            > v2.A1

     ■ Added the ability to change the base math of parameters from   > v2.A1
       base 36 (meganums) to base 64 (ultranums).  This was so we     > v2.A1
       can accomodate larger numbers in the same space.               > v2.A1

     ■ Added ability to switch from one text window, viewport or      > v2.A1
       graphical drawing style to another.                            > v2.A1

     ■ Added another file transfer protocol to the                    > v2.A1
       RIP_ENTER_BLOCK_MODE command.  The new protocol is Zmodem      > v2.A1
       without crash recovery.                                        > v2.A1

     ■ Added facilities for display of JPEG photo-realistic images.   > v2.A1

     ■ Altered some of the RIP_ENTER_BLOCK_MODE dynamic modes.  Some  > v2.A1
       of the modes that were originally defined in v1.5x were not    > v2.A1
       defined well enough and were never used in the real world.     > v2.A1
       Those values have been recycled into more realistic uses.      > v2.A1



╔══════════════════════════════════════════════╗
║ 1.5 ■ DIFFERENCES FROM 1.54 and 2.00 FORMATS ║
╚══════════════════════════════════════════════╝

In previous versions of RIPscrip, we used a simple Icon file format   > v2.A1
for its disk based bitmap icons.  In 2.00 we introduce a newer, more  > v2.A1
superior file format (the BMP/DIB file format).  This is a device     > v2.A1
independent bitmap format that accomodates monochrome images, 16      > v2.A1
color images, 256 color images and 24 bit images.  There is no real   > v2.A1
form of compression internally but the capability for compression     > v2.A1
exists for future expandability.  The reason for changing file        > v2.A1
formats was a very important one because the older format did not     > v2.A1
have the built-in facilities for resolution and color palette         > v2.A1
independence.  This new format does.  We chose the BMP file format    > v2.A1
because it is truly a device independent bitmap format.  For details  > v2.A1
about the actual file format specification, see the end of this       > v2.A1
document.                                                             > v2.A1

Any place in the RIPscrip specification that used to refer to .ICN    > v2.A1
files now will use .BMP files.  Any 2.0 RIPscrip software should be   > v2.A1
intelligent with this change.  If it sees a .ICN file it should       > v2.A1
realize that it is the older format and translate the file to         > v2.A2
.BMP instead.  How those packages deal with .ICN files may vary from  > v2.A1
vendor to vendor but the recommended solution would be to convert the > v2.A1
older .ICN to a 16 color .BMP file "on the fly".  Reallistically,     > v2.A1
when a 2.0 package is installed, some conversion utility should be    > v2.A1
run on the icon(s) at boot-up time to convert all the existing files  > v2.A1
to the new format.  Files that are received via RIP_ENTER_BLOCK_MODE  > v2.A1
should do dynamic file format conversion to the new format.  The      > v2.A1
older .ICN file format will no longer be supported in 2.0 and later   > v2.A1
revisions.                                                            > v2.A1



╔═════════════════════════════════════╗
║ 1.6 ■ BACKWARD COMPATIBILITY TOPICS ║
╚═════════════════════════════════════╝

With this release, XOR write modes now apply to all graphical         > v2.A1
primitives (also fill patterns).  Overall this shouldn't pose any     > v2.A1
problems for 99% of all RIPscrip 1.54 files out there, but there      > v2.A1
might be a few that are affected - if in RIPaint, you enable XOR      > v2.A1
write mode and do a couple lines and rectangles, then do a circle or  > v2.A1
filled rectangle, the circle or filled rectangle will be drawn in     > v2.A1
COPY mode even though XOR mode is active.  In a 2.0 terminal, this    > v2.A1
would cause the circles and filled in areas to be XOR'ed as well.  In > v2.A1
this regard, 2.0 is not 100.0% fully backward compatible.             > v2.A1

Also with this release, the world coordinate/resolution independent   > v2.A1
aspect of the language handles filled-in areas a bit differently (see > v2.A1
the world coordinate system section below).  Filled-rectangles don't  > v2.A1
fill all the way to the right or bottom borders of the rectangle -    > v2.A1
they are inset by one pixel from the right and up one line from the   > v2.A1
bottom.  The reasons for this are described in the world coordinate   > v2.A1
section of this document.  This can cause one pixel gaps in 1.54      > v2.A1
files that wouldn't happen in 2.0 related files.                      > v2.A1

With v2.A3 of the specification, we have introduced a system of       > v2.A3
graphical ports, or drawing ports.  These drawing ports are areas     > v2.A3
where actual drawing takes place.  In 1.54 and prior versions, any    > v2.A3
graphics that are drawn (eg, lines, circles, etc) are drawn to the    > v2.A3
screen (the screen port).  Under 2.0 you can define multiple drawing  > v2.A3
ports which may or may not be on the screen (eg, screen ports, or     > v2.A3
offscreen "clipboard" ports).  Each drawing port can have one         > v2.A3
viewport associated with it, allowing you to modify the sub-region    > v2.A3
inside the port that drawn objects will be "clipped to" (a clipping   > v2.A3
rectangle).  The screen is always port #0 and is formally known as    > v2.A3
the default screen port.  Under 1.54 you were allowed to have an      > v2.A3
offscreen bitmap area known as the clipboard.  Under 2.0, the         > v2.A3
clipboard is simply an offscreen "clipboard" port.  You may switch    > v2.A3
to any defined port and subsequent drawing operations will apply to   > v2.A3
that port instead of the screen (unless the new port is a screen      > v2.A3
port).                                                                > v2.A3

The older RIPscrip commands that deal with the clipboard are in       > v2.A3
essence, obsolete.  When they are instructed to work with the         > v2.A3
clipboard, they work with the first offscreen "clipboard" port that   > v2.A3
they find.  Some newer commands have been included, which are more    > v2.A3
powerful, that allow you to specifically designate a given port       > v2.A3
number to work with.  You are allowed up to 36 separate graphical     > v2.A3
drawing ports, which port #0 is the screen and cannot be deleted.     > v2.A3

RIPscrip 1.x filled objects (filled ovals, filled polygons, etc) had  > v2.A3
a border around the object.  These borders were drawn using the       > v2.A3
current drawing color, line thickness, and in some cases, line        > v2.A3
pattern.  Under 2.0, these borders can be turned off (they are on     > v2.A3
by default).  This allows you to draw filled circles in a particular  > v2.A3
fill pattern without any borders.  We default to keeping borders on   > v2.A3
for backward compatibility reasons.  If you don't want borders, you   > v2.A3
will have to shut them off.                                           > v2.A3



╔═══════════════════════════════════════════════════╗
║ 2 ■ HOW RIPscrip IS DESIGNED - FUNDAMENTAL TOPICS ║
╚═══════════════════════════════════════════════════╝

The sections that following describe specific areas of RIPscrip that  > v2.A4
are fundamental aspects of the language and its design.  Each section > v2.A4
is designed to give you information on one basic area of RIPscrip.    > v2.A4



╔══════════════════════════════════════╗
║ 2.1 ■ DRAWING PORTS - WHAT ARE THEY? ║
╚══════════════════════════════════════╝

A drawing port is an area where graphics can be drawn.  This is much  > v2.A4
like having a tablet of paper, where each page can be drawn to        > v2.A4
individually.  However, just like a tablet of paper, only the piece   > v2.A4
of paper that is on the top of the tablet can be drawn to (the        > v2.A4
current piece of paper).  The same concept applies to drawing ports.  > v2.A4
At any one moment in time, there is a "current drawing port".  This   > v2.A4
current port is the one that will display graphical drawing           > v2.A4
operations when they are received.                                    > v2.A4

There are two types of drawing ports:                                 > v2.A4

     1) A screen (visual) drawing port, and                           > v2.A4
     2) An offscreen bitmap drawing port (also known as a             > v2.A4
        "Clipboard Port".                                             > v2.A4



┌──────────────────────────────┐
│ 2.1.1 ■ SCREEN DRAWING PORTS │
└──────────────────────────────┘

A screen drawing port is the most commonly used form of drawing       > v2.A4
ports.  A screen drawing port is a port that is somewhere on top of   > v2.A4
the screen.  What this means is when a graphical drawing operation    > v2.A4
occurs, it is displayed in that port and subsequently to the screen   > v2.A4
immediately.  Screen drawing ports are methods of dividing up the     > v2.A4
user's screen into separate regions, of which each can be thought of  > v2.A4
as completely separate drawing areas.  You can switch between them    > v2.A4
pretty much at will to draw your graphics.                            > v2.A4

Here is a typical example of one screen and how it can be divided up  > v2.A4
with multiple drawing ports:                                          > v2.A4

                                 ┌─── Screen boundary                 > v2.A4
                                 │                                    > v2.A4
                                 ▼                                    > v2.A4
     ╔══════════════════════════════════════════════════╗             > v2.A4
     ║ Port 0                                           ║             > v2.A4
     ║                                                  ║             > v2.A4
     ║  ┌────────────────────┐  ┌────────────────────┐  ║             > v2.A4
     ║  │ Port 1             │  │ Port 2             │  ║             > v2.A4
     ║  │                    │  │                    │  ║             > v2.A4
     ║  └────────────────────┘  └────────────────────┘  ║             > v2.A4
     ║  ┌────────────────────────────────────────────┐  ║             > v2.A4
     ║  │ Port 3                                     │  ║             > v2.A4
     ║  │                                            │  ║             > v2.A4
     ║  └────────────────────────────────────────────┘  ║             > v2.A4
     ║  ┌────────────────────────────────────────────┐  ║             > v2.A4
     ║  │ Port 4                                     │  ║             > v2.A4
     ║  │                                            │  ║             > v2.A4
     ║  └────────────────────────────────────────────┘  ║             > v2.A4
     ╚══════════════════════════════════════════════════╝             > v2.A4

As you can see, you have quite a bit of flexibility in placing your   > v2.A4
port's around on the screen.  In this example, we have five ports     > v2.A4
defined on the screen.  You might notice that port number 0 doesn't   > v2.A4
seem to have a rectangle associated with it.  Actually, it does - it  > v2.A4
is the screen's boundary.  Port number 0 is defined as the actual     > v2.A4
screen and cannot be redefined (you can alter its viewport though -   > v2.A4
see below for more details about viewports).  Port 0 is always the    > v2.A4
full size of the screen.  You can create your own screen ports, but   > v2.A4
port 0 is one that you cannot redefine the boundary of.  This gives   > v2.A4
you the the ability to always switch to port 0 to address the entire  > v2.A4
screen, but have the luxury of other ports when you only want to work > v2.A4
with a portion of the screen.                                         > v2.A4



┌──────────────────────────────────────────────────────────┐
│ 2.1.2 ■ OFFSCREEN BITPAP DRAWING PORTS (CLIPBOARD PORTS) │
└──────────────────────────────────────────────────────────┘

An offscreen bitmap port, otherwise known as a "clipboard port", is   > v2.A4
very much like a screen port, but it isn't actually a part of the     > v2.A4
screen.  It is more like another screen that you cannot see, but one  > v2.A4
that you can still draw to.  You might be asking yourself why         > v2.A4
something like this is part of RIPscrip?  The answer is quite         > v2.A4
simple - they are extremely powerful!  An offscreen port can be used  > v2.A4
for placing a piece of graphics data temporarily while you are        > v2.A4
showing a dialog box on the screen, only to be restore the original   > v2.A4
graphics when the user clicks the "OK" button on the dialog box. The  > v2.A4
graphical data that was overwritten by the dialog box isn't deleted - > v2.A4
it's been saved temporarily on a screen that you cannot see, but is   > v2.A4
restored to the screen when necessary.  Another use of this might be  > v2.A4
if you had a very complicated scene to display, but you didn't want   > v2.A4
the user to see each little graphics operation until the entire scene > v2.A4
was complete; switch to an offscreen bitmap port, draw your scene,    > v2.A4
then switch back to the screen and copy the offscreen port's graphics > v2.A4
to your screen.  Voila, the user sees the scene appear on his screen  > v2.A4
complete - not piecemeal!                                             > v2.A4

There are numerous reasons why you would use offscreen ports; things  > v2.A4
like storing a bitmap that you just loaded from the hard disk onto an > v2.A4
offscreen port so that when you paste it to the screen a large number > v2.A4
of times, there isn't a large amount of disk activity on the user's   > v2.A4
machine.  Another good example is in the situation of an online game  > v2.A4
where the screen is some kind of map, and one or more offscreen ports > v2.A4
are used to hold small "icons", or bitmaps of game pieces.  Simply    > v2.A4
copy the images from the offscreen port(s) to appropriate locations   > v2.A4
on the map and you've accomplished a rather complicated situation     > v2.A4
without adversely affecting the user's system with intense hard drive > v2.A4
activity due to constantly loading bitmaps off the disk - the side    > v2.A4
effect, the game moves much more swiftly and with a lot less          > v2.A4
"jerkiness" due to the hard disk accesses.                            > v2.A4

Just like with screen drawing ports, you can select an offscreen      > v2.A4
bitmap port as the one which will receive graphical drawing           > v2.A4
operations.  Selecting an offscreen port as the current port let's    > v2.A4
you draw simple graphics objects, photos and other such things        > v2.A4
to it.  But remember, the graphics you draw to an offscreen port      > v2.A4
are of little value unless at some point you actually copy it to      > v2.A4
the screen so that the user can see it.                               > v2.A4

Some things cannot be done to offscreen ports.  For example, you      > v2.A4
cannot place a mouse field or a clickable button on an offscreen      > v2.A4
port.  The reason for this is that the mouse only has any             > v2.A4
meaning to the screen - the environment that the user interacts       > v2.A4
with.  How can the user click on a button that he can't see?  He      > v2.A4
can't.  You also cannot place text windows or assign resident         > v2.A4
query expressions to offscreen ports (these topics are described      > v2.A4
more fully in later sections).                                        > v2.A4

An offscreen port is most easily thought of as a graphics screen      > v2.A4
that you can't see.  You can work with it to your heart's content,    > v2.A4
but the user can't see the contents of it until you copy the          > v2.A4
data to the screen.  As long as you keep this one fundamental         > v2.A4
concept in mind, there should be no confusion about ports.            > v2.A4



┌───────────────────────────────┐
│ 2.1.3 ■ PORTS AND COORDINATES │
└───────────────────────────────┘

A port is a specific drawing area.  No matter whether the port is a   > v2.A4
screen port of an offscreen bitmap port, it is still a drawing area,  > v2.A4
and as such, it has a legal number of horizontal and vertical pixels  > v2.A4
that can be drawn to.  Every graphical drawing operation uses         > v2.A4
graphical coordinates with which they draw their image to the current > v2.A4
port.  For example, a circle needs to know the center point, and the  > v2.A4
radius of the circle in order to draw itself.                         > v2.A4

Each port has what can be thought of as its own set of coordinates.   > v2.A4
Just like the screen where (0,0) is the upper-left corner of the      > v2.A4
screen, when a port is active (ie, current), (0,0) is the coordinate  > v2.A4
of the upper-left corner of the drawing port.  If a port had a width  > v2.A4
of W and a height of H, then the lower-right coordinate would be      > v2.A4
(W-1,H-1).  This holds true for all drawing ports, even offscreen     > v2.A4
bitmap ports.                                                         > v2.A4

For example, if you draw a circle at (50,50) with a radius of (25,25) > v2.A4
to the current port (a screen port), then you might have something    > v2.A4
like the following diagram:                                           > v2.A4

                               ┌──── Screen Boundary                  > v2.A4
 (0,0)                         ▼                                      > v2.A4
   ╔══════════════════════════════════════════════════╗               > v2.A4
   ║                                                  ║               > v2.A4
   ║    ┌───────────────────────────────────────┐     ║               > v2.A4
   ║    │(10,10)            │◄─25─►│            │◄───────Port         > v2.A4
   ║    │                 ▄▄▄▄▄                 │     ║               > v2.A4
   ║    │              ▄▀▀     ▀▀▄              │     ║               > v2.A4
   ║    │             █           █             │     ║               > v2.A4
   ║    │            █      ■ ◄─── █ ──────────────────── (60,60) on  > v2.A4
   ║    │             █  (50,50)  █             │     ║   the screen  > v2.A4
   ║    │              ▀▄▄     ▄▄▀              │     ║               > v2.A4
   ║    │                 ▀▀▀▀▀                 │     ║               > v2.A4
   ║    │                              (124,124)│     ║               > v2.A4
   ║    └───────────────────────────────────────┘     ║               > v2.A4
   ║                                                  ║               > v2.A4
   ╚══════════════════════════════════════════════════╝               > v2.A4

In this example, the port starts at (10,10) on the screen and goes    > v2.A4
down to (124,124) on the screen (a width of 115 and a height of 115). > v2.A4
Since you said to draw the circle centered at (50,50) in the current  > v2.A4
port, what actually happens on the screen is that the circle is       > v2.A4
physically drawn at (50+10,50+10) to the screen, or centered at the   > v2.A4
"absolute" coordinate of (60,60) in relation to the actual screen.    > v2.A4

As you can see, each port can be thought of as its own little drawing > v2.A4
universe, with its own set of coordinates.  This makes drawing things > v2.A4
like graphs, or showing game map windows easy - without having to     > v2.A4
make extensive calculations in the host software to figure out where  > v2.A4
things need to be placed.  This is considered "port relative"         > v2.A4
coordinates.                                                          > v2.A4

Screen ports are defined as some location on the actual screen from   > v2.A4
the upper-left corner to the lower-right corner.  From this           > v2.A4
information, the width and height of the port can be easily           > v2.A4
calculated.                                                           > v2.A4


Offscreen ports are a bit different though.  Since they're not part   > v2.A4
of the user's actual screen, they don't have this upper-left          > v2.A4
location on the screen.  In this manner, an offscreen port is always  > v2.A4
thought of as having an upper-left corner of (0,0) and its            > v2.A4
lower-right corner as (W-1,H-1).                                      > v2.A4



┌─────────────────────────────┐
│ 2.1.4 ■ PORTS AND VIEWPORTS │
└─────────────────────────────┘

Each drawing port has an associated viewport, or clipping rectangle.  > v2.A4
A viewport is a rectangle inside the port that defines the drawing    > v2.A4
limits inside that port.  Its similar in concept to a coloring book   > v2.A4
with invisible lines.  You can draw all you want, but you can't go    > v2.A4
outside the lines.  If any operation would extend beyond the edge of  > v2.A4
this clipping rectangle, it will be truncated.  For example, if you   > v2.A4
have a drawing port that is 100x100 pixels in size, and you define    > v2.A4
the viewport to be from (25,25) to (74,74), you would have a 50x50    > v2.A4
drawing area right in the center of the drawing port.  If you then    > v2.A4
draw a circle in the exact center of the drawing port with a radius   > v2.A4
of 60 pixels, you would have pieces of the circle that extend beyond  > v2.A4
the top, left, bottom and right borders of the viewport.  What you    > v2.A4
would see would be four arcs in each corner of the viewport as in the > v2.A4
following example:                                                    > v2.A4

                           Viewport from (25,25) to (74,74)           > v2.A4
                           ───────┬────────────────────────           > v2.A4
         (0,0)                    │                                   > v2.A4
            ╔═════════════════════│════╗                              > v2.A4
            ║          ░░░░░      │    ║                              > v2.A4
            ║       ░░░     ░░░   ▼    ║                              > v2.A4
            ║   ┌─██───────────██─┐    ║                              > v2.A4
            ║   │█               █│    ║                              > v2.A4
            ║   █                 █    ║                              > v2.A4
            ║  ░│                 │░   ║                              > v2.A4
            ║ ░ │                 │ ░  ║                              > v2.A4
            ║ ░ │                 │ ░  ║                              > v2.A4
            ║ ░ │                 │ ░  ║                              > v2.A4
            ║  ░│                 │░   ║                              > v2.A4
            ║   █                 █    ║                              > v2.A4
            ║   │█               █│    ║                              > v2.A4
            ║   └─██──────────-██─┘    ║                              > v2.A4
            ║       ░░░     ░░░        ║                              > v2.A4
            ║          ░░░░░           ║                              > v2.A4
            ╚══════════════════════════╝ (99,99)                      > v2.A4

If you notice in the above diagram, the rectangle inside the port     > v2.A4
defines the viewport.  The solid squares (█) denote pixels inside the > v2.A4
viewport that would actually be drawn, and the shaded squares (░)     > v2.A4
show pixels that will not be drawn because they are outside the       > v2.A4
viewport.                                                             > v2.A4

You can alter the location and size of the viewport inside any given  > v2.A4
drawing port.  By default, the viewport is set to the full size of    > v2.A4
the drawing port when the port is created.  If you attempt to make    > v2.A4
the viewport go outside the actual port, it will be adjusted to fit   > v2.A4
so that it is completely within the port.  If an attempt is made to   > v2.A4
define a viewport that is completely outside the boundary of its      > v2.A4
port, then the definition is ignored as an error condition.  If the   > v2.A4
lower-right corner is outside the boundary of the port, then the      > v2.A4
lower-right corner of the newly defined viewport is set to the        > v2.A4
lower-right corner of the port itself.                                > v2.A4

Just like drawing ports, a viewport also "adjusts" drawing            > v2.A4
coordinates.  When you alter the location of a viewport inside of a   > v2.A4
drawing port, the origin (0,0) for drawing operations relates to the  > v2.A4
upper-left corner of the viewport itself, not the actual underlying   > v2.A4


drawing port.  All drawing operations pertain to a port's viewport,   > v2.A4
not the port itself.  The port is considered the maximum limits for   > v2.A4
the viewport inside - just like the screen, you can only draw to      > v2.A4
areas inside the screen; the same applies to viewports and ports.     > v2.A4

As an example, let's say you have a screen port defined and you alter > v2.A4
the viewport (remember, by default it is the full size of the port    > v2.A4
when the port is defined until you re-define it).  The following      > v2.A4
diagram will give you an idea of our example:                         > v2.A4

                          ╔════ Screen boundary                       > v2.A4
                          ▼                                           > v2.A4
╔═════════════════════════════════════════════╗                       > v2.A4
║(0,0) screen                                 ║                       > v2.A4
║    ┌───────── (0,0) port                    ║                       > v2.A4
║    ▼          (25,25) screen                ║                       > v2.A4
║    ■───────────────────────────────────┐ ◄══════ Port boundary      > v2.A4
║    │           │ (0,0) viewport        │    ║                       > v2.A4
║    │        ┌──┤ (40,40) port          │    ║                       > v2.A4
║    │        ▼  │ (65,65) screen        │    ║                       > v2.A4
║    │        ■─────────────────────┐    │    ║                       > v2.A4
║    │        │                     │    │    ║                       > v2.A4
║    │        │                     │ ◄═══════════ Viewport boundary  > v2.A4
║    │        │          ■          │    │    ║                       > v2.A4
║    │        │          ▲          │    │    ║  │ (130,130) viewport > v2.A4
║    │        └──────────│──────────■ ◄──────────┤ (170,170) port     > v2.A4
║    │                   │               │    ║  │ (195,195) screen   > v2.A4
║    │                   │               │    ║                       > v2.A4
║    └───────────────────│───────────────■ ◄────── (200,200) port     > v2.A4
║                        │                    ║    (225,225) screen   > v2.A4
╚════════════════════════│════════════════════╝                       > v2.A4
                         │    │ (50,50) viewport                      > v2.A4
                         └────┤ (90,90) port                          > v2.A4
                              │ (125,125) screen                      > v2.A4

In this example, our port is defined from (25,25) to (225,225) on the > v2.A4
screen.  This makes our port 201 pixels wide and 201 pixels tall.     > v2.A4
Our viewport starts at (40,40) in the port's coordinate system and    > v2.A4
ends at (170,170).  This makes our viewport 131 pixels wide and       > v2.A4
131 pixels tall.  The upper-left coordinate of the viewport would map > v2.A4
to the screen coordinates (25+40,25+40) or (65,65), and the           > v2.A4
lower-right corner would map to (25+40+130,25+40+130) or (195,195).   > v2.A4

As you can see, mapping a screen port's coordinates to those actually > v2.A4
used on the screen can get quite involved.  But when you get down to  > v2.A4
the benefits of coordinate systems, this approach provides quite a    > v2.A4
bit of flexibility in moving things around without having to change   > v2.A4
coordinate systems all the time.                                      > v2.A4



┌───────────────────────────────────────────────────┐
│ 2.1.5 ■ PORTS, VIEWPORTS AND GRAPHICAL OPERATIONS │
└───────────────────────────────────────────────────┘

We've already discussed how a viewport "truncates" a graphical        > v2.A4
operation if it extends beyond the border of the port's viewport.     > v2.A4

What if you're copying graphical data from one port to another?       > v2.A4
Graphics data can only be copied from one port to another in          > v2.A4
rectangular portions, and just like all other graphical operations,   > v2.A4
this kind of situation adheres to the viewports of both the source    > v2.A4
and the destination ports' viewports!  Let's take an example where    > v2.A4
you are copying a rectangle of graphics from port 1 to port 2.  For   > v2.A4
sake of clarity, we'll copy the entire viewport over (not a sub-area  > v2.A4
of the viewport).  The following diagram shows what would happen if   > v2.A4
the two viewports aren't the exact same size (specifically, the       > v2.A4
source viewport is larger than the destination viewport):             > v2.A4

      ┌─── Port 1's viewport             ┌─── Port 2's viewport       > v2.A4
      │                                  │                            > v2.A4
╔═════│═══════════════════════╗     ╔════│══════════════════╗         > v2.A4
║     ▼                       ║     ║    ▼                  ║         > v2.A4
║   ┌───────────────────┐     ║     ║ ┌─────────────┐       ║         > v2.A4
║   │███████████████████│     ║     ║ │█████████████│░░░░░  ║         > v2.A4
║   │███████████████████│     ║     ║ │█████████████│░░░░░  ║         > v2.A4
║   │███████████████████│     ║     ║ │█████████████│░░░░░  ║         > v2.A4
║   │███████████████████│     ║     ║ └─────────────┘░░░░░  ║         > v2.A4
║   │███████████████████│     ║     ║  ░░░░░░░░░░░░░░░░░░░  ║         > v2.A4
║   └───────────────────┘     ║     ║                       ║         > v2.A4
╚═════════════════════════════╝     ╚═══════════════════════╝         > v2.A4
            Port 1                            Port 2                  > v2.A4

The squares that are shown as solid (█) are the graphics data that is > v2.A4
to be copied (port 1), and the graphics data that is actually copied  > v2.A4
(port 2).  The shaded squares (░) are graphics data from the source   > v2.A4
viewport that aren't copied to the destination.  This shows how a     > v2.A4
viewport "truncates" graphical drawing operations, even when copying  > v2.A4
data from one port to another.                                        > v2.A4



┌───────────────────────────────────────────────┐
│ 2.1.6 ■ COPYING DATA FROM ONE PORT TO ANOTHER │
└───────────────────────────────────────────────┘

When you copy graphical data from one port to another (or to another  > v2.A4
location on the same port for that matter), you are duplicating the   > v2.A4
graphical contents of the source port onto the destination port.      > v2.A4
Whether the result is an exact replica of the original image or not   > v2.A4
is another matter.  Whenever you copy a rectangle of data from one    > v2.A4
port to another, you need to specify a rectangle in the source port,  > v2.A4
and another one in the destination port.  These two rectangles do not > v2.A4
need to be the same pixel size.  If they are different either in the  > v2.A4
width or height dimensions, then scaling of the source image will     > v2.A4
occur!  For example, if the source image's rectangle doesn't have the > v2.A4
same dimensions as the rectanalge in the destination port, you could  > v2.A4
have a situation similar to the following:                            > v2.A4

╔══════════════════════════════╗   ╔══════════════════════════════╗   > v2.A4
║   ┌────────────────────┐     ║   ║  ┌────────────────────────┐  ║   > v2.A4
║   │██▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀██│     ║   ║  │██▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀██│  ║   > v2.A4
║   │█ ▀▄            ▄▀ █│     ║   ║  │█ ▀▄                ▄▀ █│  ║   > v2.A4
║   │█   ▀▄        ▄▀   █│     ║   ║  │█   █▀▀▀▀▀▀▀▀▀▀▀▀▀▀█   █│  ║   > v2.A4
║   │█     █▀▀▀▀▀▀█     █│     ║   ║  │█   █▄▄▄▄▄▄▄▄▄▄▄▄▄▄█   █│  ║   > v2.A4
║   │█     █      █     █│     ║   ║  │█ ▄▀                ▀▄ █│  ║   > v2.A4
║   │█     █      █     █│     ║   ║  │██▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄██│  ║   > v2.A4
║   │█     █▄▄▄▄▄▄█     █│     ║   ║  └────────────────────────┘  ║   > v2.A4
║   │█   ▄▀        ▀▄   █│     ║   ║                              ║   > v2.A4
║   │█ ▄▀            ▀▄ █│     ║   ║                              ║   > v2.A4
║   │██▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄██│     ║   ║                              ║   > v2.A4
║   └────────────────────┘     ║   ║                              ║   > v2.A4
╚══════════════════════════════╝   ╚══════════════════════════════╝   > v2.A4
        Source (Port 1)                  Destination (Port 2)         > v2.A4

Notice that the image in the destination is shorter, but much wider   > v2.A4
than the original.  This is because in this example we specified our  > v2.A4
destination rectangle to be shorter, but wider in size than the       > v2.A4
original image in the source port.  If the two rectangles had the     > v2.A4
same width and height values, then our destination image would be     > v2.A4
pixel-for-pixel identical to the original (providing that the         > v2.A4
viewport of the destination port didn't truncate the image of         > v2.A4
course).                                                              > v2.A4

When copying rectangular pieces of data from one port to another, you > v2.A4
have to be careful about viewports.  If either the source or the      > v2.A4
destination rectangle are completely outside that port's viewport,    > v2.A4
then the copy operation isn't performed - nothing would be visible if > v2.A4
it did happen, because either the source or the destination image     > v2.A4
wouldn't be visible inside the viewport.                              > v2.A4

Here is another example showing a straight copy operation without any > v2.A4
scaling being performed.  We are assuming that the source and         > v2.A4
destination rectangles are the same size.  The port's boundary and    > v2.A4
it's viewport are shown in the following diagram:                     > v2.A4



     ╔════════════════════╗       ╔═══════════════════════════╗       > v2.A4
     ║  ┌────────────┐    ║       ║  ┌───────────────────┐    ║       > v2.A4
     ║  │██  ██  ██  │░░░ ║       ║  │██  ██  ██  ░░░░   │    ║       > v2.A4
     ║  │  ██  ██  ██│░░░ ║       ║  │  ██  ██  ██░░░░   │    ║       > v2.A4
     ║  │██  ██  ██  │░░░ ║       ║  │██  ██  ██  ░░░░   │    ║       > v2.A4
     ║  │  ██  ██  ██│░░░ ║       ║  │  ██  ██  ██░░░░   │    ║       > v2.A4
     ║  │██  ██  ██  │░░░ ║       ║  │██  ██  ██  ░░░░   │    ║       > v2.A4
     ║  │  ██  ██  ██│░░░ ║       ║  │  ██  ██  ██░░░░   │    ║       > v2.A4
     ║  └────────────┘░░░ ║       ║  └───────────────────┘    ║       > v2.A4
     ║   ░░░░░░░░░░░░░░░░ ║       ║   ░░░░░░░░░░░░░░░░        ║       > v2.A4
     ║   ░░░░░░░░░░░░░░░░ ║       ║   ░░░░░░░░░░░░░░░░        ║       > v2.A4
     ╚════════════════════╝       ╚═══════════════════════════╝       > v2.A4

The shaded squares (░) are graphics that extend beyond the source's   > v2.A4
viewport.  Those pixels aren't copied to the destination port, but    > v2.A4
they are shown in the upper-right diagram to show where the graphics  > v2.A4
would have been in the destination port if they were copied.          > v2.A4

Let's take another example but this time we will show scaling because > v2.A4
this situation may not be intuitive.  Let's assume that our source    > v2.A4
rectangle is twice as large as our destination rectangle both in      > v2.A4
the width and height dimensions.  This means that our image will be   > v2.A4
reduced by 1/2.  But what happens if the source image needs to be     > v2.A4
"truncated" to fit in the viewport?  The answer is simple - only the  > v2.A4
data that remains after truncation is scaled into the destination     > v2.A4
rectangle.  If the destination rectangle also had to be truncated,    > v2.A4
then the scaling is still performed.  Under no circumstances will a   > v2.A4
vertical or horizontal "blank" zone be created during scaling.  When  > v2.A4
you say "scale to fit", it does exactly what you told it to - it      > v2.A4
makes the graphics fit in the given area.  Here is the diagram that   > v2.A4
shows this situation:                                                 > v2.A4

          ╔════════════════════╗       ╔══════════════╗               > v2.A4
          ║  ┌────────────┐    ║       ║  ┌─────────┐ ║               > v2.A4
          ║  │██  ██  ██  │░░░ ║       ║  │▀▄▀▄▀▄░░ │ ║               > v2.A4
          ║  │  ██  ██  ██│░░░ ║       ║  │▀▄▀▄▀▄░░ │ ║               > v2.A4
          ║  │██  ██  ██  │░░░ ║       ║  │▀▄▀▄▀▄░░ │ ║               > v2.A4
          ║  │  ██  ██  ██│░░░ ║       ║  │░░░░░░░░ │ ║               > v2.A4
          ║  │██  ██  ██  │░░░ ║       ║  │░░░░░░░░ │ ║               > v2.A4
          ║  │  ██  ██  ██│░░░ ║       ║  └─────────┘ ║               > v2.A4
          ║  └────────────┘░░░ ║       ╚══════════════╝               > v2.A4
          ║   ░░░░░░░░░░░░░░░░ ║                                      > v2.A4
          ║   ░░░░░░░░░░░░░░░░ ║                                      > v2.A4
          ╚════════════════════╝                                      > v2.A4



╔═══════════════════════════════════════════════╗
║ 2.2 ■ DATA TABLES - A FUNDAMENTAL 2.0 CONCEPT ║
╚═══════════════════════════════════════════════╝

RIPscrip 2.0 is different from its previous versions                  > v2.A1
architecturally on a number of levels.  One of the key fundamental    > v2.A1
differences is the introduction of data tables.

A data table is a table of information used in RIPscrip.  Data tables > v2.A3
may be the color palette table (where each table entry is a complete  > v2.A3
color palette definition), graphical style tables, button style       > v2.A3
tables, drawing port tables, text window definition tables, mouse     > v2.A4
field tables, or environment data tables.  Some data tables have an   > v2.A4
entry that is "currently active".  This might be the currently active > v2.A3
text window in the text window data table, or the currently active    > v2.A3
color palette in the palette data table.  Every data table has one or > v2.A3
more entries in it, in which each entry is a specific piece of data.  > v2.A3
Data table entries can be "in use" and/or protected (see below).      > v2.A3

Data can be moved from one table entry to another (in effect, making  > v2.A1
a copy of one table entry to another); this doesn't apply to all data > v2.A4
tables (eg, mouse field data table).  Also, most tables' entries can  > v2.A4
be protected so that the contents of a particular entry cannot be     > v2.A4
modified or deleted until either an unprotect entry function is       > v2.A1
executed, or a hard reset is performed (a hard reset completely       > v2.A1
resets the entire RIPscrip environment to ground zero).  Again the    > v2.A4
mouse field data table cannot have individual entries protected.      > v2.A4



╔══════════════════════════════╗
║ 2.2.1 ■ TYPES OF DATA TABLES ║
╚══════════════════════════════╝

There are six different data tables for general data storage.  They   > v2.A4
are: the drawing port table, color palette table, graphical style     > v2.A3
table, text window table, the button style table and the RIPscrip     > v2.A4
environment data table.  There are backup areas for these data tables > v2.A4
so you can make complete backup copies of these data tables for       > v2.A4
re-use later after some operation is performed (eg, executing a       > v2.A4
dialog box, running a door, etc).  There are actually more data       > v2.A4
backup areas than there are data tables, but this will be described   > v2.A4
in a later section entitled "DATA BACKUP AREAS".                      > v2.A4

The six general data table groups are described in more detail as     > v2.A4
follows:                                                              > v2.A1



┌──────────────────────────────┐
│ 2.2.1.1 ■ DRAWING PORT TABLE │
└──────────────────────────────┘

One of the most fundamental aspects of RIPscrip 2.0 is the concept of > v2.A4
a drawing port.  Any drawing of graphics occurs inside a drawing      > v2.A4
port.  There may be up to 36 ports defined simultaneously.  Port      > v2.A3
number 0 is always defined as the screen.  Its dimensions are that of > v2.A3
the screen.  The remaining 35 ports may be sub-sections of the screen > v2.A3
or may be offscreen memory drawing ports (ie, clipboard ports).  At   > v2.A3
any one moment in time, only one port may be the current port - the   > v2.A4
port that will receive graphical drawing operations.  If the current  > v2.A4
port is an offscreen clipboard port, then any drawing operations will > v2.A3
not appear on the screen.  The only way that those graphics can be    > v2.A3
viewed by the user is if the contents of the port are copied to a     > v2.A3
screen port.                                                          > v2.A3

All ports, when defined, are defined using the current world          > v2.A4
coordinate system.  From those coordinates, the port's actual         > v2.A4
physical pixel dimensions are determined and those dimensions are     > v2.A4
remembered by the port.  Any graphical operation that bypasses the    > v2.A4
viewport system (RIP_SCROLL_REGION, etc) will pay close attention to  > v2.A4
coordinates and the boundaries of the drawing port.  If any           > v2.A4
coordinate would go outside of the port, it is adjusted to fit        > v2.A4
inside.                                                               > v2.A4

A drawing port remembers a number of pieces of information which
characterize that drawing port.  Each port maintains its own list of
the following pieces of data:

     ■ Current X/Y location (used with RIP_TEXT commands)             > v2.A4
     ■ Current image style settings (see RIP_IMAGE_STYLE)             > v2.A4
     ■ Current viewport location and dimensions                       > v2.A4
     ■ Current fixed viewport "resident query" expression             > v2.A4
     ■ The current "source X/Y location" for graphically              > v2.A4
       stored data used with the PORT_COPY, RIP_GET_IMAGE,            > v2.A4
       RIP_PUT_IMAGE, and $PCB$ commands (see these commands for      > v2.A4
       more details).                                                 > v2.A4

The entire drawing port data table keeps track of the "current        > v2.A4
viewport" query expression (otherwise known as a floating viewport    > v2.A4
query).  See the RIP_QUERY command for more details.                  > v2.A4



┌───────────────────────────────┐
│ 2.2.1.2 ■ COLOR PALETTE TABLE │
└───────────────────────────────┘

In RIPscrip there is a graphical color palette.  The color palette    > v2.A3
is a group of 256 separate color RGB values, also known as a color    > v2.A3
lookup table.  This color palette is used to map a particular color   > v2.A3
number to some combination of red, green and blue color components.   > v2.A3
For example, color 0 is usually black (no red, green or blue), and    > v2.A3
color 255 is typically white (full intensity red, green and blue).    > v2.A3
This color palette is normally written directly into the video        > v2.A3
hardware of your computer to activate the colors.  So when you try    > v2.A3
to draw in color 255, you see a white line appear on the screen.      > v2.A3

RIPscrip 2.0 allows you to have up to 36 separate color palettes.     > v2.A3
Combined, these make up a color palette table.  Only one entry in     > v2.A3
the color palette table may be current at any one moment in time.     > v2.A4
An entry in the color palette table is a complete 256 color palette.  > v2.A3
When you switch from one color palette entry to another, the colors   > v2.A3
on the screen will typically change instantly (see below about        > v2.A3
24 bit modes).  This gives you the ability to quickly and easily      > v2.A3
switch from one color scheme to another without sending a large       > v2.A3
amount of information to the terminal every time you wish to switch   > v2.A3
color schemes.                                                        > v2.A3

RIPscrip 2.0 allows for two forms of color modes, color palette       > v2.A3
mapping mode (the default) and direct RGB color encoding.  Color      > v2.A3
palette mapping mode refers to a method of selecting colors where     > v2.A3
colors are specified as numbers from 0-255, which are indices into    > v2.A3
the current color palette.  This determines the actual color that     > v2.A4
will be rendered to the screen.  In direct RGB color mode though,     > v2.A3
colors are specified as raw red, green and blue components (see the   > v2.A3
sections below on "COLOR MAPPING VS. DIRECT RGB ENCODING").           > v2.A3

Under 24 bit configurations of a RIPscrip software package, a real    > v2.A3
color palette is not possible because there are no color registers    > v2.A3
on the video hardware.  In those cases, a color palette is merely     > v2.A3
used as an RGB color lookup table.  In other words, if you said to    > v2.A3
draw a line in color 255, you would be saying lookup color 255 in     > v2.A3
the color palette, take that RGB configuration and draw the line      > v2.A3
based on that color combination.  In a serious sense, it is the       > v2.A3
same as what the video hardware does, but the software has to do      > v2.A3
the job in that situation.  When the system is in 24 bit color        > v2.A3
modes, where color palettes are not truly possible, switching         > v2.A3
from one color palette to another will not make any changes to the    > v2.A3
colors on the screen - it only affects subsequent drawing operations. > v2.A3

When a normal reset operation is performed, all unprotected data      > v2.A4
table entries are reset to bootup default color palette values.  A    > v2.A4
"hard reset" will reset the entire color palette data table to        > v2.A4
default values.                                                       > v2.A4



┌─────────────────────────────────┐
│ 2.2.1.3 ■ GRAPHICAL STYLE TABLE │
└─────────────────────────────────┘

There are 36 separate graphical style table entries.  Initially,      > v2.A1
number 0 is current and is initialized to default values.  A          > v2.A4
graphical style entry defines a number of currently active graphical  > v2.A1
attributes.  A graphical style entry defines the following values     > v2.A1
(each entry has all of these attributes):                             > v2.A1

     ■ Current drawing color                                          > v2.A1
     ■ Current background drawing color                               > v2.A1
     ■ Current fill pattern number (or user-defined fill pattern)     > v2.A1
     ■ Current fill color                                             > v2.A1
     ■ Current line pattern number (or user-defined line pattern)     > v2.A1
     ■ Line pattern odd drawing rule (see RIP_LINE_STYLE)             > v2.A1
     ■ Current mouse cursor style number                              > v2.A1
     ■ Current font number (or font name for extended fonts)          > v2.A1
     ■ Current font size, orientation and horizontal/vertical         > v2.A1
       alignment                                                      > v2.A1
     ■ Current write mode (raster/transfer operation)                 > v2.A1
     ■ Current color mode (palette or direct RGB)                     > v2.A1

With the ability of having multiple graphical style entries defined   > v2.A1
simultaneously, you can setup an entire graphical environment, then   > v2.A1
with a single command, switch to a completely different configuration > v2.A1
in only a couple of bytes of RIPscrip code.  This can greatly reduce  > v2.A1
the amount of RIPscrip code that needs to be transmitted after the    > v2.A1
style data table entries are initially setup.                         > v2.A1

See below under Protected Data Table Entries for even more powerful   > v2.A4
aspects of the data table systems.                                    > v2.A4



┌──────────────────────────────┐
│ 2.2.1.4 ■ BUTTON STYLE TABLE │
└──────────────────────────────┘

Button style data table entries contain a complete button style       > v2.A1
definition as defined by a RIP_BUTTON_STYLE command.                  > v2.A4

Having multiple button style slots defined at the same time allows    > v2.A1
you to have many commonly used button styles defined at once, so that > v2.A1
you can simply reference an already defined button style rather than  > v2.A1
having to transmit a rather length button style command each and      > v2.A1
every time you wish to define a button.                               > v2.A1



┌─────────────────────────────┐
│ 2.2.1.5 ■ TEXT WINDOW TABLE │
└─────────────────────────────┘

A text window is simply a region on the screen where raw,             > v2.A1
non-RIPscrip text is routed once it is received from the host.        > v2.A1
Initially, the text window is full screen, using the MicroANSI font   > v2.A1
#2 (80x25).  This is different than previous versions of RIPscrip in  > v2.A1
that the initial setting was full screen using font #0 which          > v2.A1
corresponds to an 80x43 text configuration.  80x25 is more            > v2.A1
aesthetically pleasing to most people so it was made the default font > v2.A1
configuration.                                                        > v2.A1

A text window typically supports ANSI and VT-102 screen control codes > v2.A4
to support foreground and background colors, and other formatting     > v2.A1
options.  This information is all part of a text window.  Each text   > v2.A1
window table entry stores a number of pieces of information that      > v2.A1
define what a text window is.  The information stored in each text    > v2.A1
window entry is as follows:                                           > v2.A1

     ■ The upper-left and lower-right corner definitions for the      > v2.A1
       text window (coordinates are in text coordinates, not          > v2.A1
       graphical screen coordinates).                                 > v2.A1
     ■ The MicroANSI screen font number for the given window.         > v2.A1
     ■ The current ANSI color attributes                              > v2.A1
     ■ The current cursor X/Y location                                > v2.A1
     ■ The status of the cursor (is it on or off)                     > v2.A1
     ■ The current vertical scrolling margins (ANSI formatting)       > v2.A1
     ■ Whether the window is activated or deactivated.                > v2.A4

A text window can also be deactivated.  If the current text window    > v2.A4
slot is deactivated then any raw text that is received by the host    > v2.A4
will be discarded (ie, not shown on screen at all).                   > v2.A1

Having multiple defined text windows allows you to quickly switch     > v2.A1
from one text window configuration to another without having to lose  > v2.A1
any previously used information (color, location, cursor, etc).  Note > v2.A1
that the text contained inside the current text window is not stored  > v2.A1
as part of the text window definition - only the window's raw         > v2.A1
definition is preserved.  This can easily be used for multiple data   > v2.A4
entry fields, multiple chat windows, or other such things.            > v2.A4



┌─────────────────────────────┐
│ 2.2.1.6 ■ ENVIRONMENT TABLE │
└─────────────────────────────┘

The environment data table is a central table for the maintenance of  > v2.A4
critical values that define the characteristics of the RIPscrip       > v2.A4
environment.  This data table holds up to 36 separate environments.   > v2.A4
The following pieces of information are stored in the environment     > v2.A4
data table:                                                           > v2.A4

     ■ Current graphics style entry number                            > v2.A4
     ■ Current button style entry number                              > v2.A4
     ■ Current drawing port entry number                              > v2.A4
     ■ Current text window entry number                               > v2.A4
     ■ Current color palette entry number                             > v2.A4
     ■ Current World coordinate dimensions (X and Y)                  > v2.A4
     ■ Current base math settings (36 or 64)                          > v2.A4
     ■ Current coordinate size (2 through 5)                          > v2.A4
     ■ Current color mode (color palette mode or direct RGB mode)     > v2.A4
     ■ Current mouse pointer number                                   > v2.A4
     ■ Current baud rate emulation value                              > v2.A4

When you switch from one environment to another, you are effectively  > v2.A4
performing an entire "context swapping" operation.  This might best   > v2.A4
be taken with an example:                                             > v2.A4

     Let's say you have set up all of your data tables to work with   > v2.A4
     entry number 5 and entry 5 in each data table is the current     > v2.A4
     one.  This could have an entire drawing environment defined for  > v2.A4
     a particular situation.  Let's say that you have entry 6 in      > v2.A4
     every data table defined with a completely different             > v2.A4
     configuration of drawing environments.  You could easily switch  > v2.A4
     between one drawing environment to another simply by switching   > v2.A4
     environments, in effect completely redefining your entire        > v2.A4
     drawing world.  Nothing is destroyed in this switching process,  > v2.A4
     all you are doing is simply switching to another environment.    > v2.A4
     You would still be free to return to the previous environment    > v2.A4
     if you so desire (note that if you perform any reset operations  > v2.A4
     though, you best make sure that you protect things or they       > v2.A4
     will disappear when you reset).                                  > v2.A4

Note that there isn't a "current mouse field data table entry".  This > v2.A4
is because there's no such thing as a current mouse field in the      > v2.A4
mouse field data table.  So, switching from one environment to        > v2.A4
another has no effect on the current mouse fields (unlike it would    > v2.A4
with text windows, ports, graphical styles, palettes, etc).           > v2.A4



┌─────────────────────────────┐
│ 2.2.1.7 ■ MOUSE FIELD TABLE │
└─────────────────────────────┘

The mouse field data table is unlike the other data tables.  It can   > v2.A4
hold up to 128 separate mouse field definitions and does not have a   > v2.A4
"current mouse field" entry number.  Each mouse field that is defined > v2.A4
gets added to the mouse field data table at the very end until 128    > v2.A4
fields are defined, or the table is deleted and things start over.    > v2.A4
Mouse fields only pertain to drawing port #0, so they can only be     > v2.A4
on the screen, not on an offscreen drawing port.  See the RIP_MOUSE,  > v2.A4
RIP_BUTTON_STYLE and RIP_BUTTON command for more details on this      > v2.A4
special data table.                                                   > v2.A4



╔══════════════════════════════════════╗
║ 2.2.2 ■ PROTECTED DATA TABLE ENTRIES ║
╚══════════════════════════════════════╝

Data table entries by themselves have quite a bit of usefulness in    > v2.A1
short-term situations where a lot of different configurations need to > v2.A1
be switched between fairly often.  Their usefulness becomes even more > v2.A1
powerful with the concept of protected data table entries.  A         > v2.A1
protected entry is one that cannot be cleared by a normal reset       > v2.A1
operation or a clear table entry operation until the entry is         > v2.A1
unprotected, or until a "hard reset" operation is performed.  In      > v2.A4
addition, they cannot be modified while they are protected (see       > v2.A4
below).                                                               > v2.A4

A "hard reset" is a complete reset of the RIPscrip environment.       > v2.A1
Typically, a hard reset should only be performed immediately after    > v2.A1
connection to a RIPscrip compatible host system to clear the slate so > v2.A1
to speak.  Other uses for a hard reset are when the RIPscrip          > v2.A1
environment is hopelessly corrupted due to line noise, or when a      > v2.A1
complete re-synchronization of the enviornment is about to commence.  > v2.A1

Protected entries become quite powerful when you look at a larger     > v2.A1
host system.  For example, let's say that throughout your system you  > v2.A1
use five different graphical style configurations all over the place, > v2.A1
all of which require quite a bit of transmitted RIPscrip code.  If    > v2.A1
you define each of these styles as separate entries and then protect  > v2.A1
them, you don't need to re-transmit those blocks of data again unless > v2.A1
a hard reset operation is performed!  This can mean quite a bit of    > v2.A1
saved data transmission, and consequently faster transmission times.  > v2.A1
The same concept applies to text windows, ports, button styles,       > v2.A4
graphics style, palette and environment tables.  When taken from a    > v2.A4
system-wide perspective, where many sections of the system may be     > v2.A1
made by other manufacturers (eg, doors, BBS modules, etc), you may    > v2.A1
not be able to count on whether a section of the system uses one      > v2.A1
style or another, or does one kind of reset or another.  Having       > v2.A1
protected entries gives you the ability to protect your data          > v2.A1
configurations so that these sub-sections do not destroy your data.   > v2.A1
When you return from the sub-section, simply re-activate your table   > v2.A1
configuration(s) and away you go.                                     > v2.A1

We just described that a protected data table entry cannot be         > v2.A4
deleted.  We also mentioned that they cannot be modified.  Let's      > v2.A4
clarify what we mean by not modifiable.  A data table entry that is   > v2.A4
protected cannot be modified by any of the normal RIPscrip commands   > v2.A4
or text variables that alter their basic configuration (eg, you       > v2.A4
cannot alter the foreground drawing color in a protected graphical    > v2.A4
style data table entry, etc).  It should be noted however, that       > v2.A4
normal drawing operations like rectangles, circles, etc, can still be > v2.A4
performed to a port that is protected.  In this case, the port is     > v2.A4
protected from having its "configuration" modified (eg, the viewport  > v2.A4
cannot be modified nor can the actual port's orientation).  The same  > v2.A4
applies to text windows (eg, you can output text to a text window,    > v2.A4
perform ANSI/VT-102 operations to it, erase it, etc, but you cannot   > v2.A4
redefine it or delete it).  One tiny exception rests with text        > v2.A4
windows that support VT-102.  VT-102 has an ANSI escape sequence that > v2.A4
allows you to alter the wrap/chop setting of text windows.  Since     > v2.A4
ANSI operations are allowed on protected text windows, this is        > v2.A4
permissable even though it seemingly violates the nature of modifying > v2.A4
a text window's protected status.                                     > v2.A4


Terminal emulation modes are also unaffected by a text window's       > v2.A4
protection status.  If a text window is enabled, VT-102 mode can be   > v2.A4
turned on or off because this is a "global" setting, not a text       > v2.A4
window specific setting.  Also, as noted later, RIPscrip processing   > v2.A4
can be disabled via a special ANSI escape sequence.  This does not    > v2.A4
affect protection of text windows or drawing ports either.            > v2.A4

With these things in mind, performing operations like "copying a      > v2.A4
port's data to another port" where one or both are protected is       > v2.A4
allowable because you are not altering the basic configuration or the > v2.A4
ports in question, you are simply altering their data contents.  This > v2.A4
applies to "clipboard" related commands too which might dynamically   > v2.A4
pick and choose ports to define.  Since a clipboard related command   > v2.A4
will auto-define a new port (if one doesn't already exist, it will    > v2.A4
pick a currently undefined drawing port and define it (if it's not    > v2.A4
defined, then it cannot be protected).                                > v2.A4



╔═════════════════════════╗
║ 2.3 ■ DATA BACKUP AREAS ║
╚═════════════════════════╝

A data backup area is a backup area that composes one base save area  > v2.A3
and ten data save regions for specific data table types.  The data    > v2.A4
save regions are broken collectively up as a set of individually      > v2.A4
addressable data save slots (like an array in most programming        > v2.A4
languages), and a data save stack.  Each data backup area can contain > v2.A4
up to eleven separate, complete data tables of one particular type -  > v2.A4
one in the base save area, and up to ten other data tables in the     > v2.A4
data save slots or the data save stack, or in some combination of     > v2.A4
the two (save slots or stack).                                        > v2.A4

Each data backup area can store only one particular type of data      > v2.A4
table.  For example, the color palette data backup area can only      > v2.A4
store color palette data tables (remember a color palette data        > v2.A4
table consists of 36 separate color palette definitions).             > v2.A4

A data save slot is a backup area that is large enough to store an    > v2.A3
entire specific data table, or other object (graphics screen, mouse   > v2.A3
fields, etc).  Each data backup area's save slots can hold one entire > v2.A3
data table of the type designated for the data backup area.  Each     > v2.A4
data save slot has a specific slot number associated with it (0-9).   > v2.A4
When the data in a data save slot is restored back to the actual      > v2.A4
RIPscrip drawing environment, that slot is deleted (cleared),         > v2.A4
providing that it isn't protected (see below).                        > v2.A4

A base save area is very similar to a data save slot, except that a   > v2.A3
base save area does not have a specific "slot number" associated with > v2.A4
it.  Unlike data save slots, when you restore a data table object     > v2.A3
from a base save area, the base save area is not cleared (ie,         > v2.A3
deleted) so it can be restored multiple times without losing the      > v2.A4
saved data (the base save area cannot be protected like data save     > v2.A4
slots can be - see below for more details).                           > v2.A4

Finally, we have stack save areas.  Stack save areas are like a       > v2.A4
stack of plates - you put plates on top of the stack, and when you    > v2.A4
want one, you take one off the top of the stack.  The plate at the    > v2.A4
bottom of the stack was the first plate placed on it, and to get to   > v2.A4
it, you need to take off each of the plates above it to get to it.    > v2.A4
When you place a data table onto a save stack, it is like placing a   > v2.A4
plate on top of our stack of plates.  This is extremely useful (in    > v2.A4
fact, critical) to creating dialog boxes that overlap menus, and when > v2.A4
you close the dialog box, you restore the menu's environment.  The    > v2.A4
act of placing a data table onto a data save stack is called          > v2.A4
"pushing" a table onto the stack.  The act of removing a table from   > v2.A4
the top of the stack is called "popping" a table from the stack.  In  > v2.A4
order to remember where the "top" of the stack is (ie, how many       > v2.A4
layers are on the stack), a thing called a "stack pointer" is         > v2.A4
maintained internally which is simply a count of the number of items  > v2.A4
on the stack.  Each time you add a new data table onto the stack, the > v2.A4
pointer is increased by one (we have one more item on the stack).     > v2.A4

You can think of data tables and the data backup area conceptually    > v2.A4
in the following diagram:                                             > v2.A4



        Data Table                     Data Backup Area               > v2.A4
        ╔════════╗         ╔═══════════════════════════════════════╗  > v2.A4
entry 0 ╟────────╢         ║                                       ║  > v2.A4
entry 1 ╟────────╢         ║         Base Data Save Area           ║  > v2.A4
entry 2 ╟────────╢         ║                                       ║  > v2.A4
entry 3 ╟────────╢     ─── ╠═══╤═══╤═══╤═══╤═══╤═══╤═══╤═══╤═══╤═══╣  > v2.A4
entry 4 ╟────────╢      │  ║   │   │   │   │   │   │   │   │   │   ║  > v2.A4
entry 5 ╟────────╢      │  ║ s │ s │ s │ s │ s │ s │ s │ s │ s │ s ║  > v2.A4
entry 6 ╟────────╢    Data ║ l │ l │ l │ l │ l │ l │ l │ l │ l │ l ║  > v2.A4
entry 7 ╟────────╢    Save ║ o │ o │ o │ o │ o │ o │ o │ o │ o │ o ║  > v2.A4
entry 8 ╟────────╢   Slots ║ t │ t │ t │ t │ t │ t │ t │ t │ t │ t ║  > v2.A4
entry 9 ╟────────╢      │  ║   │   │   │   │   │   │   │   │   │   ║  > v2.A4
        ╟─  ..  ─╢      │  ║ 0 │ 1 │ 2 │ 3 │ 4 │ 5 │ 6 │ 7 │ 8 │ 9 ║  > v2.A4
            ..          │  ║   │   │   │   │   │   │   │   │   │   ║  > v2.A4
            ..         ─── ╟───┼───┼───┼───┼───┼───┼───┼───┼───┼───╢  > v2.A4
        ╟─      ─╢      │  ║   │   │   │   │   │   │   │   │   │   ║  > v2.A4
entry N ╟────────╢      │  ║   │   │   │   │   │   │   │   │   │   ║  > v2.A4
        ╚════════╝   Stack ║   │   │   │   │   │   │   │   │   │   ║  > v2.A4
                      Save ║   │   │   │   │   │   │   │   │   │   ║  > v2.A4
                      area ║   │   │   │   │   │   │   │   │   │   ║  > v2.A4
                        │  ║   │   │   │   │   │   │   │   │   │   ║  > v2.A4
                        │  ║   │   │   │   │   │   │   │   │   │   ║  > v2.A4
                        │  ║   │   │   │   │   │   │   │   │   │   ║  > v2.A4
                       ─── ╚═══╧═══╧═══╧═══╧═══╧═══╧═══╧═══╧═══╧═══╝  > v2.A4
                            /│\                                       > v2.A4
                             │   Stack                                > v2.A4
                             │  Pointer                               > v2.A4

Notice how there are ten different data save slots, and ten different > v2.A4
data save stack "locations".  What this means is that individually,   > v2.A4
either one of these may hold ten complete data tables.  But combined, > v2.A4
they cannot both contain more than 10 complete data tables.  What     > v2.A4
this means is that you can have 4 separate tables saved in the data   > v2.A4
save slots, and 6 data tables pushed onto the stack, but the you      > v2.A4
wouldn't be able to store one more data table into an "open" data     > v2.A4
save slot, or push it onto the save stack (the slot/stack system is   > v2.A4
effectively "full").  The diagram above shows a completely empty      > v2.A4
data backup area.                                                     > v2.A4

Let's take an example.  Let's say we have tables saved to data save   > v2.A4
slots 1, 3, 4, 6, 8 and 9 (six tables total), we could envision our   > v2.A4
data slot/stack areas like this (we have nothing on the stack yet     > v2.A4
in this example, so our stack pointer is 0, or pointing to the first  > v2.A4
stack entry which is open for filling):                               > v2.A4

                  0   1   2   3   4   5   6   7   8   9               > v2.A4
            ─── ╔═══╤═══╤═══╤═══╤═══╤═══╤═══╤═══╤═══╤═══╗             > v2.A4
           Data ║   │▒▒▒│   │▒▒▒│▒▒▒│   │▒▒▒│   │▒▒▒│▒▒▒║             > v2.A4
           Save ║   │▒▒▒│   │▒▒▒│▒▒▒│   │▒▒▒│   │▒▒▒│▒▒▒║             > v2.A4
          Slots ║   │▒▒▒│   │▒▒▒│▒▒▒│   │▒▒▒│   │▒▒▒│▒▒▒║             > v2.A4
            ─── ╠═══╪═══╪═══╪═══╪═══╪═══╪═══╪═══╪═══╪═══╣             > v2.A4
          Stack ║   │   │   │   │   │   │   │   │   │   ║             > v2.A4
           Save ║   │   │   │   │   │   │   │   │   │   ║             > v2.A4
           area ║   │   │   │   │   │   │   │   │   │   ║             > v2.A4
            ─── ╚═══╧═══╧═══╧═══╧═══╧═══╧═══╧═══╧═══╧═══╝             > v2.A4
                 /│\                                                  > v2.A4
                  │   Stack                                           > v2.A4
                  │  Pointer                                          > v2.A4



If we now push three data tables onto our stack, we would have the    > v2.A4
following diagram showing the data slot/stack areas:                  > v2.A4

                  0   1   2   3   4   5   6   7   8   9               > v2.A4
            ─── ╔═══╤═══╤═══╤═══╤═══╤═══╤═══╤═══╤═══╤═══╗             > v2.A4
           Data ║   │▒▒▒│   │▒▒▒│▒▒▒│   │▒▒▒│   │▒▒▒│▒▒▒║             > v2.A4
           Save ║   │▒▒▒│   │▒▒▒│▒▒▒│   │▒▒▒│   │▒▒▒│▒▒▒║             > v2.A4
          Slots ║   │▒▒▒│   │▒▒▒│▒▒▒│   │▒▒▒│   │▒▒▒│▒▒▒║             > v2.A4
            ─── ╠═══╪═══╪═══╪═══╪═══╪═══╪═══╪═══╪═══╪═══╣             > v2.A4
          Stack ║▒▒▒│▒▒▒│▒▒▒│   │   │   │   │   │   │   ║             > v2.A4
           Save ║▒▒▒│▒▒▒│▒▒▒│   │   │   │   │   │   │   ║             > v2.A4
           area ║▒▒▒│▒▒▒│▒▒▒│   │   │   │   │   │   │   ║             > v2.A4
            ─── ╚═══╧═══╧═══╧═══╧═══╧═══╧═══╧═══╧═══╧═══╝             > v2.A4
                             /│\                                      > v2.A4
                              │   Stack                               > v2.A4
                              │  Pointer                              > v2.A4

We now have nine data tables stored in our data slot/stack system.    > v2.A4
We can only hold one more.  If one more is pushed onto the stack, we  > v2.A4
would have the following:                                             > v2.A4

                  0   1   2   3   4   5   6   7   8   9               > v2.A4
            ─── ╔═══╤═══╤═══╤═══╤═══╤═══╤═══╤═══╤═══╤═══╗             > v2.A4
           Data ║   │▒▒▒│   │▒▒▒│▒▒▒│   │▒▒▒│   │▒▒▒│▒▒▒║             > v2.A4
           Save ║   │▒▒▒│   │▒▒▒│▒▒▒│   │▒▒▒│   │▒▒▒│▒▒▒║             > v2.A4
          Slots ║   │▒▒▒│   │▒▒▒│▒▒▒│   │▒▒▒│   │▒▒▒│▒▒▒║             > v2.A4
            ─── ╠═══╪═══╪═══╪═══╪═══╪═══╪═══╪═══╪═══╪═══╣             > v2.A4
          Stack ║▒▒▒│▒▒▒│▒▒▒│▒▒▒│   │   │   │   │   │   ║             > v2.A4
           Save ║▒▒▒│▒▒▒│▒▒▒│▒▒▒│   │   │   │   │   │   ║             > v2.A4
           area ║▒▒▒│▒▒▒│▒▒▒│▒▒▒│   │   │   │   │   │   ║             > v2.A4
            ─── ╚═══╧═══╧═══╧═══╧═══╧═══╧═══╧═══╧═══╧═══╝             > v2.A4
                                 /│\                                  > v2.A4
                                  │   Stack                           > v2.A4
                                  │  Pointer                          > v2.A4

Our stack system is now full.  We have four items on our stack and    > v2.A4
six in our data save slots.  If we tried to push another data table   > v2.A4
onto our stack, the operation would be ignored (an error because our  > v2.A4
slot/stack system is full).  If we tried to store a data table to     > v2.A4
data save slot #2 (which is currently open), it would also be ignored > v2.A4
because the slot/stack system is full.  If however, we tried to       > v2.A4
save a data table onto data save slot #3 (which is occupied), the     > v2.A4
operation would be performed providing that data save slot #3 is not  > v2.A4
protected (see below).                                                > v2.A4

A stack restore (also known as a "pop") is a method of restoring a    > v2.A3
data object from the data save stack into a data table.  When you     > v2.A4
perform a stack pop, the data table at the top of the stack (the      > v2.A4
entry just below the stack pointer) is removed from the stack and     > v2.A4
placed in the appropriate data table (which one is based on the type  > v2.A4
of data that is stored in the data backup area).  Once the restore    > v2.A4
operation is complete, the entry in that location of the stack is     > v2.A4
deleted (cleared), and the stack pointer is decremented by one, thus  > v2.A4
making room for one more entry in the data save slot/stack system to  > v2.A4
hold a new data table.                                                > v2.A4

Each data backup area maintains its own stack pointer.  Each backup   > v2.A3
area's stack pointer is unique and completely unrelated to the stack  > v2.A3
pointers of other backup areas.                                       > v2.A3


The base data save area is provided as a "temporary" storage location > v2.A4
for data tables.  The slot/stack system is designed for more          > v2.A4
permanent storage of tables.                                          > v2.A4

All totalled, a data backup area can store eleven separate data       > v2.A4
tables, and each data table in a data backup area is of the same type > v2.A4
of information (eg, text window, color palette, etc).  If a data      > v2.A4
table has 36 separate data table entries in it, then a data backup    > v2.A4
area for that data table would hold 396 separate data table entries   > v2.A4
in it!  This makes for a lot of backup storage.  You cannot           > v2.A4
individually access sub-elements of a data table inside of a data     > v2.A4
backup area - you can only save/restore "entire" data tables at any   > v2.A4
one moment.                                                           > v2.A4

Push and pop operations are vital to the concept of multiple          > v2.A4
overlapping windows and dialog boxes in RIPscrip.  When you close a   > v2.A4
window, you need to restore the background graphics, mouse regions,   > v2.A4
text windows and any other data tables that were in use at the time   > v2.A4
the dialog/window was created.  What if that restored background is   > v2.A4
itself a window that is on top of some background menu?  That window  > v2.A4
would also have tables pushed (the background environment).  When     > v2.A4
that window closes, it will pop the information and restore the       > v2.A4
background environment's configuration.                               > v2.A4

There are fourteen distinctly separate ways of copying data           > v2.A4
tables/objects around.  They are depicted in the following diagram    > v2.A4
and described in more detail immediately below:                       > v2.A4

      Data Table                                                      > v2.A4
    ╔════════════╗ 2         ╔═════════════════════════════════╗      > v2.A4
    ║            ║  ◄──────► ║         Base Save Area          ║      > v2.A4
    ╟────────────╢          1╚═════════════════════════════════╝      > v2.A4
    ║            ║                                8▲    11▲           > v2.A4
    ╟────────────╢                                 │      │           > v2.A4
    ║            ║                                 ▼9     │           > v2.A4
    ╟────────────╢           ╔═══╤═══╤═══╤═══╤═══╤═══╗    │           > v2.A4
    ║    7▲      ║ 4         ║   │   │   │   │ 14│   ║    │           > v2.A4
    ╟──── │ ─────╢  ◄──────► ║   │   │ ────────► │   ║    │           > v2.A4
    ║     │      ║          3║   │   │   │   │   │   ║    │           > v2.A4
    ╟──── │ ─────╢           ╚═══╧═══╧═══╧═══╧═══╧═══╝    │           > v2.A4
    ║     │      ║            Data Save Slots    13▲      │           > v2.A4
    ╟────────────╢                                 │      │           > v2.A4
    ║            ║                                 ▼12    ▼10         > v2.A4
    ╟────────────╢ 6         ╔═════════════════════════════════╗      > v2.A4
    ║            ║  ◄──────► ║         Data Save Stack         ║      > v2.A4
    ╟────────────╢          5╚═════════════════════════════════╝      > v2.A4
    ║            ║                                                    > v2.A4
    ╚════════════╝                                                    > v2.A4

     1.  Copy a data table to the base save area                      > v2.A4
     2.  Copy the base save area to the data table                    > v2.A4
     3.  Copy a data table to a data save slot                        > v2.A4
     4.  Copy a data save slot to a data table                        > v2.A4
     5.  Push a data table onto the stack                             > v2.A4
     6.  Pop a data table from the stack into a data table            > v2.A4
     7.  Copy an entry in a data table over another entry in the      > v2.A4
         same data table.                                             > v2.A4
     8.  Copy a data save slot to the base save area                  > v2.A4
     9.  Copy the base save area to a data save slot                  > v2.A4
    10.  Push the base save area onto the data save stack             > v2.A4
    11.  Pop a data table from the stack into the base save area      > v2.A4


    12.  Push a data save slot table onto the stack                   > v2.A4
    13.  Pop a data table from the stack into a data save slot        > v2.A4
    14.  Copy a data save slot to another data save slot              > v2.A4



╔════════════════════════════════════════════════════════╗
║ 2.3.1 ■ DATA BACKUP AREAS - PROTECTION AND RESTORATION ║
╚════════════════════════════════════════════════════════╝

The way that a stack operates has been clearly outlined in the        > v2.A4
previous section.  When you store a data table onto the stack, it     > v2.A4
grows by one table.  When you pop a data table off of the stack, you  > v2.A4
reduce the contents of the stack by one data table (ie, that data     > v2.A4
table is deleted from the stack).                                     > v2.A4

The base save area has already been described as a temporary storage  > v2.A4
location.  A data table in the base save area remains in the base     > v2.A4
save area until it is either explicitly deleted, or until a hard      > v2.A4
reset of the RIPscrip environment is performed.  In this manner, the  > v2.A4
base save area can be used as a source of a data table copy           > v2.A4
operations many times and still read the same data table.             > v2.A4

When you restore a data table from a data save slot back into the     > v2.A4
actual data table on the other hand, that data save slot is deleted   > v2.A4
(cleared) unless it is protected from deletion.  In other words, just > v2.A4
like individual data table entries, you can individually protect      > v2.A4
data save slots from deletion or overwriting.  Only a data save slot  > v2.A4
that is actually "in use" can be protected - it is pointless to       > v2.A4
protect a data save slot that isn't holding a data table because what > v2.A4
would you do with it?  You couldn't store anything in it and you      > v2.A4
couldn't read anything from it, so this situation is not allowed.     > v2.A4

There are only three ways of deleting or modifying a protected data   > v2.A4
save slot (two of which involve manually unprotecting the slot):      > v2.A4

     1)  Explicitly unprotect the slot and then overwrite or delete   > v2.A4
         it.                                                          > v2.A4

     2)  Explicitly unprotect the slot then copy the data table from  > v2.A4
         it to the actual data table designed to work with that data. > v2.A4
         This deletes the contents of the slot once the copy          > v2.A4
         operation is complete.                                       > v2.A4

     3)  Perform a hard reset of the RIPscrip environment.            > v2.A4

The base save area cannot be protected and neither can the data save  > v2.A4
stack.  Protection goes against the very nature of these two backup   > v2.A4
areas.                                                                > v2.A4

It should be noted that when a data table is stored in the data       > v2.A4
backup area, any of the entries in that data table "retain" their     > v2.A4
protection status!  This means that if you restore a data table from  > v2.A4
the backup area and put it back into action, the protection status    > v2.A4
of each entry in the table is restored as well.                       > v2.A4

You cannot protect an entire data table.  This means that if you have > v2.A4
entries in a data table that are protected and you perform a restore  > v2.A4
operation from a backup area, this will overide any individual        > v2.A4
entries in the data table with those stored in the actual data table  > v2.A4
in the backup area.  This is the only way that a data table entry's   > v2.A4
protection status can be bypassed.                                    > v2.A4



╔══════════════════════════════════════╗
║ 2.3.2 ■ INDIVIDUAL DATA BACKUP AREAS ║
╚══════════════════════════════════════╝

There are data backup areas for the following types of information    > v2.A3
(not all of them are normal data tables per se):                      > v2.A4



┌────────────────────────────────────────┐
│ 2.3.2.1 ■ BUTTON STYLE TABLE SAVE AREA │
└────────────────────────────────────────┘

A backup area for an entire button style data table (all 36 button    > v2.A3
styles that may be defined).                                          > v2.A4

This backup area stores the following information:                    > v2.A4

     ■ The current button style data table entry number               > v2.A4
     ■ The actual button style data table (all 36 entries)            > v2.A4



┌───────────────────────────────────────────┐
│ 2.3.2.2 ■ GRAPHICAL STYLE TABLE SAVE AREA │
└───────────────────────────────────────────┘

A backup area for an entire graphical style data table (all 36        > v2.A3
graphical styles that may be defined).                                > v2.A4

This backup area stores the following information:                    > v2.A4

     ■ The current graphical style data table entry number            > v2.A4
     ■ The actual graphical style data table (all 36 entries)         > v2.A4



┌────────────────────────────────────────┐
│ 2.3.2.3 ■ DRAWING PORT TABLE SAVE AREA │
└────────────────────────────────────────┘

A backup area that stores all 36 separately defined graphical ports   > v2.A3
in the Port Table.  Video Ports save only the specific definition of  > v2.A3
the ports.  Clipboard Ports store not only the port definition, but   > v2.A3
also the graphical data that is saved inside the Clipboard Ports.     > v2.A3

This backup area stores the following information:                    > v2.A4

     ■ The current drawing port data table entry number               > v2.A4
     ■ The actual drawing port data table (all 36 entries)            > v2.A4
     ■ All offscreen/clipboard ports' actual graphical contents       > v2.A4
     ■ The current "floating" viewport query expression               > v2.A4
     ■ The current "clipboard port pointer" (see RIP_GET_IMAGE for    > v2.A4
       more details).                                                 > v2.A4



┌───────────────────────────────────────┐
│ 2.3.2.4 ■ TEXT WINDOW TABLE SAVE AREA │
└───────────────────────────────────────┘

A backup area that stores the entire text window data table.  This    > v2.A3
stores all 36 of the possibly defined text window configurations.     > v2.A3
Only the text window definitions are saved in these areas, not the    > v2.A3
contents of the text window(s).                                       > v2.A3

This backup area stores the following information:                    > v2.A4

     ■ The current text window data table entry number                > v2.A4
     ■ The actual text window data table (all 36 entries)             > v2.A4
     ■ The current "floating" text window query expression            > v2.A4



┌─────────────────────────────────────────┐
│ 2.3.2.5 ■ COLOR PALETTE TABLE SAVE AREA │
└─────────────────────────────────────────┘

A backup area that stores all 36 currently defined color palettes in  > v2.A3
the color palette data table.                                         > v2.A4

This backup area stores the following information:                    > v2.A4

     ■ The current color palette data table entry number              > v2.A4
     ■ The actual color palette data table (all 36 entries)           > v2.A4



┌───────────────────────────────────────┐
│ 2.3.2.6 ■ MOUSE FIELD TABLE SAVE AREA │
└───────────────────────────────────────┘

A backup area that stores all currently defined simple mouse fields   > v2.A4
and mouse button fields currently active on the screen.  The mouse    > v2.A3
field boundaries and any mouse button configuration data is stored.   > v2.A3
Mouse fields do not have a directly accessible data table.  In other  > v2.A3
words, you cannot directly protect a specific entry in the mouse      > v2.A3
field data table.  The mouse field data table is different than       > v2.A3
normal data tables in that they can have up to 128 separate table     > v2.A3
entries and are not directly accessible like other simpler data       > v2.A3
tables like graphical style data tables, etc. When a mouse button     > v2.A3
definition is restored, the graphics displayed for a button are not   > v2.A3
restored - only the internal mouse button field definitions are       > v2.A4
restored.                                                             > v2.A3

This backup are stores the following information:

     ■ The total number of mouse fields defined                       > v2.A4
     ■ The actual mouse field data table (up to 128 entries)          > v2.A4



┌────────────────────────────┐
│ 2.3.2.7 ■ SCREEN SAVE AREA │
└────────────────────────────┘

The screen save area is a special data backup area.  The screen       > v2.A3
backup area has no real data table related to it, although you could  > v2.A4
think of it as a data table of video scan lines where each entry      > v2.A4
in the data table is one scan line of graphical data.  The data save  > v2.A4
slots and the base save area of the screen backup area each contain a > v2.A3
complete bitmap representation of a graphical screen, and its         > v2.A3
associated color palette.  This backup area embodies some of the      > v2.A3
concepts of the drawing port backup area when it stores a Clipboard   > v2.A3
Port and also parts of the color palette backup area.  This backup    > v2.A3
area allows you to have up to eleven separately saved graphical       > v2.A3
screens.                                                              > v2.A3

This backup are stores the following information:                     > v2.A4

     ■ The current color palette actually in use on the video         > v2.A4
       hardware (if any)                                              > v2.A4
     ■ The graphical screen contents of the data screen               > v2.A4
     ■ The on/off status of the status bar.                           > v2.A4



┌───────────────────────────────────────┐
│ 2.3.2.8 ■ ENVIRONMENT TABLE SAVE AREA │
└───────────────────────────────────────┘

The environment save area is a backup area to store the entire        > v2.A4
environment data table (all 36 entries).  It is used for the purpose  > v2.A4
of backing up the entire environment table for later restoration.     > v2.A4

This backup area stores the following information:                    > v2.A4

     ■ The current environment data table entry number                > v2.A4
     ■ The actual environment data table (all 36 entries)             > v2.A4



{$SEC:1.7:INTERNATIONAL SUPPORT IN RIPscrip}
╔═════════════════════════════════════════════╗
║ 2.3.2.8 ■ INTERNATIONAL SUPPORT IN RIPSCRIP ║
╚═════════════════════════════════════════════╝

The RIPscrip language itself is not tied to any particular language.  > v2.A2
However, there is a need to establish a means of determining and      > v2.A2
specifying what RIPscrip / text window fonts with special characters  > v2.A2
should be used, and what language should be used in the terminal      > v2.A2
software.  It is up to the individual application to use whatever     > v2.A2
files it needs to support a particular language.  RIPscrip provides   > v2.A2
a standardized way of specifying the language support to use.  A      > v2.A4
character code will be used for each of the languages supported.      > v2.A4

Currently, English is the only supported language in RIPscrip.  This  > v2.A4
will be changing in the future, so for the purposes of multi-lingual  > v2.A4
extensibility, we are establishing a convention now.  The current     > v2.A4
list of supported languages and their three character codes are as    > v2.A4
follows:                                                              > v2.A4

        ╔══════╤══════════════════════════╗
        ║ Code │ Description of Language  ║                           > v2.A4
        ╠══════╪══════════════════════════╣                           > v2.A4
        ║ ENG  │ English                  ║                           > v2.A4
        ╚══════╧══════════════════════════╝

The means of setting the language is for the user to specify in the   > v2.A2
terminal, preferably in the dialing directory.  This allows the user  > v2.A2
to select a different language for different systems.  There is no    > v2.A2
ability for the host to specify to the terminal what language to use. > v2.A2

The means of finding out what languages the terminal supports will be > v2.A2
handled via the $IFS()$ text variable.  For example, if the host were > v2.A2
to query the terminal with a $IFS(ENG)$, the terminal would respond   > v2.A4
with `YES'.                                                           > v2.A2



╔═══════════════════════════════════════════════════════════════╗
║ 2.4 ■ NUMERICAL PARAMETERS - FORMATS AND BASE-MATH VARIATIONS ║
╚═══════════════════════════════════════════════════════════════╝

Throughout the RIPscrip specification, numeric parameters are used    > v2.A0
extensively to indicate where to draw things, how to draw things and  > v2.A0
various other pieces of information.  For compactness, we do not use  > v2.A0
numbers that are normal decimal numbers (base-10).  By default,       > v2.A0
RIPscrip uses base-36 numbers (Hexa-Tri-Decimal or more fondly,       > v2.A0
MegaNums) which use the digits 0-9 followed by A-Z.  This was the     > v2.A0
original numbering system used in the 1.xx specification.             > v2.A0

In the 2.xx specification, the base math can be altered to something  > v2.A0
other than base-36!  With v2.xx, we are introducing a new numbering   > v2.A0
scheme that is base-64, otherwise known as Quadra-Hexa-Decimal, or    > v2.A0
more fondly known as UltraNums.  UltraNums use the following digits:  > v2.A0

                         0-9  A-Z  a-z  #  &                          > v2.A3

With this numbering scheme, you can squeeze larger numbers into an    > v2.A0
even smaller space than MegaNums!  Here is a table showing how big of > v2.A0
a number can be contained with X number of digits:                    > v2.A0

          Decimal  Hexa-Decimal    MegaNums        UltraNums          > v2.A0
        ╔═════════╤════════════╤═══════════════╤════════════════╗     > v2.A0
       1║       9 │         15 │            35 │             63 ║     > v2.A0
Total  2║      99 │        255 │         1,295 │          4,095 ║     > v2.A0
Digits 3║     999 │      4,095 │        46,655 │        262,143 ║     > v2.A0
 (X)   4║   9,999 │     65,535 │     1,679,615 │     16,777,215 ║     > v2.A4
       5║  99,999 │  1,048,575 │    60,466,175 │  1,073,741,823 ║     > v2.A2
       6║ 999,999 │ 16,777,215 │ 2,176,782,335 │ 68,719,476,735 ║     > v2.A2
        ╚═════════╧════════════╧═══════════════╧════════════════╝     > v2.A0

A RIPscrip Header command can be used to specify the global base math > v2.A0
used throughout the command sets.  By altering the base math, you can > v2.A0
make a single numeric parameter accept larger values without          > v2.A0
expanding the parameter in the specification.  A couple of the        > v2.A0
RIPscrip commands utilize specific base math values (eg, UltraNums,   > v2.A0
etc) under certain circumstances.  Any commands that are exceptions   > v2.A0
like this will be clearly documented as being exceptions to the rule. > v2.A0

NOTE:  6 digit UltraNums cannot be easily represented under most      > v2.A3
       personal computer compilers (beyond 32 bits).  Therefore,      > v2.A3
       UltraNums beyond 5 digits probably should not be used in a     > v2.A3
       real world situation.



The following is a basic table of Decimal, MegaNum and UltraNum       > v2.A0
values:                                                               > v2.A0

  ╔═════════╤═════════╤══════════╗  ╔═════════╤═════════╤══════════╗
  ║ Decimal │ MegaNum │ UltraNum ║  ║ Decimal │ MegaNum │ UltraNum ║  > v2.A0
  ╠═════════╪═════════╪══════════╣  ╠═════════╪═════════╪══════════╣  > v2.A0
  ║   00    │     0   │    0     ║  ║   32    │    0W   │    W     ║  > v2.A0
  ║   01    │    01   │    1     ║  ║   33    │    0X   │    X     ║  > v2.A0
  ║   02    │    02   │    2     ║  ║   34    │    0Y   │    Y     ║  > v2.A0
  ║   03    │    03   │    3     ║  ║   35    │    0Z   │    Z     ║  > v2.A0
  ║   04    │    04   │    4     ║  ║   36    │    10   │    a     ║  > v2.A0
  ║   05    │    05   │    5     ║  ║   37    │    11   │    b     ║  > v2.A0
  ║   06    │    06   │    6     ║  ║   38    │    12   │    c     ║  > v2.A0
  ║   07    │    07   │    7     ║  ║   39    │    13   │    d     ║  > v2.A0
  ║   08    │    08   │    8     ║  ║   40    │    14   │    e     ║  > v2.A0
  ║   09    │    09   │    9     ║  ║   41    │    15   │    f     ║  > v2.A0
  ║   10    │    0A   │    A     ║  ║   42    │    16   │    g     ║  > v2.A0
  ║   11    │    0B   │    B     ║  ║   43    │    17   │    h     ║  > v2.A0
  ║   12    │    0C   │    C     ║  ║   44    │    18   │    i     ║  > v2.A0
  ║   13    │    0D   │    D     ║  ║   45    │    19   │    j     ║  > v2.A0
  ║   14    │    0E   │    E     ║  ║   46    │    1A   │    k     ║  > v2.A0
  ║   15    │    0F   │    F     ║  ║   47    │    1B   │    l     ║  > v2.A0
  ║   16    │    0G   │    G     ║  ║   48    │    1C   │    m     ║  > v2.A0
  ║   17    │    0H   │    H     ║  ║   49    │    1D   │    n     ║  > v2.A0
  ║   18    │    0I   │    I     ║  ║   50    │    1E   │    o     ║  > v2.A0
  ║   19    │    0J   │    J     ║  ║   51    │    1F   │    p     ║  > v2.A0
  ║   20    │    0K   │    K     ║  ║   52    │    1G   │    q     ║  > v2.A0
  ║   21    │    0L   │    L     ║  ║   53    │    1H   │    r     ║  > v2.A0
  ║   22    │    0M   │    M     ║  ║   54    │    1I   │    s     ║  > v2.A0
  ║   23    │    0N   │    N     ║  ║   55    │    1J   │    t     ║  > v2.A0
  ║   24    │    0O   │    O     ║  ║   56    │    1K   │    u     ║  > v2.A0
  ║   25    │    0P   │    P     ║  ║   57    │    1L   │    v     ║  > v2.A0
  ║   26    │    0Q   │    Q     ║  ║   58    │    1M   │    w     ║  > v2.A0
  ║   27    │    0R   │    R     ║  ║   59    │    1N   │    x     ║  > v2.A0
  ║   28    │    0S   │    S     ║  ║   60    │    1O   │    y     ║  > v2.A0
  ║   29    │    0T   │    T     ║  ║   61    │    1P   │    z     ║  > v2.A0
  ║   30    │    0U   │    U     ║  ║   62    │    1Q   │    #     ║  > v2.A0
  ║   31    │    0V   │    V     ║  ║   63    │    1R   │    &     ║  > v2.A0
  ╚═════════╧═════════╧══════════╝  ╚═════════╧═════════╧══════════╝

The following C code fragment provides you with a way of converting   > v2.A0
decimal numbers to an UltraNum format:                                > v2.A0

     char ultra_num_table[64] = {                                     > v2.A0
          '0', '1', '2', '3', '4', '5', '6', '7',                     > v2.A0
          '8', '9', 'A', 'B', 'C', 'D', 'E', 'F',                     > v2.A0
          'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N',                     > v2.A0
          'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V',                     > v2.A0
          'W', 'X', 'Y', 'Z', 'a', 'b', 'c', 'd',                     > v2.A0
          'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l',                     > v2.A0
          'm', 'n', 'o', 'p', 'q', 'r', 's', 't',                     > v2.A0
          'u', 'v', 'w', 'x', 'y', 'z', '#', '&'                      > v2.A3
     };                                                               > v2.A0



     char *Dec2Ultra(long value)                                      > v2.A0
     {                                                                > v2.A0
          static char buf[8];                                         > v2.A0
          int    part, pos=0;                                         > v2.A0

          setmem(buf, 0, 8);                                          > v2.A0

          while (value >= 64L) {                                      > v2.A0
               part       = value & 0x003Fl;                          > v2.A0
               value      = value >> 6;                               > v2.A0
               buf[pos++] = ultra_num_table[part];                    > v2.A0
          }                                                           > v2.A0

          if (value) {                                                > v2.A0
               buf[pos++] = ultra_num_table[value];                   > v2.A0
          }                                                           > v2.A0

          strrev(buf);                                                > v2.A0
          return(buf);                                                > v2.A0
     }                                                                > v2.A0



╔════════════════════════════════╗
║ 2.5 ■ WORLD COORDINATE SYSTEMS ║
╚════════════════════════════════╝

Starting with the v2.0 specification of RIPscrip, we have introduced  > v2.A0
a "world coordinate system".  This means that you can alter the base  > v2.A0
coordinate system used to address the video's physical device         > v2.A0
coordinate system.  This is the first step in achieving device        > v2.A0
independence.  Each coordinate system is called a "Coordinate Frame". > v2.A0
There are actually two distinct levels of coordinate systems.  From   > v2.A4
the lowest (least abstract) to the highest level (the drawing board)  > v2.A0
you have the following coordinate systems:                            > v2.A0

     1) DEVICE COORDINATE FRAME - the resolution of the actual        > v2.A0
        display device.  This is not determined as part of the        > v2.A0
        RIPscrip language itself, it is actually determined by        > v2.A0
        the terminal - based upon whatever type of video              > v2.A0
        hardware is present (and what mode the user has chosen).      > v2.A0

     2) WORLD COORDINATE FRAME - This is the master coordinate        > v2.A0
        system.  This is the global set of coordinates.  Ideally,     > v2.A0
        it should be higher in dimensions than the Device Frame       > v2.A0
        so that you do not lose resolution when "mapping"             > v2.A0
        X/Y coordinates from the world coordinate system to the       > v2.A0
        device coordinate system.  If the dimensions of the           > v2.A0
        World Frame are the same as the Device Frame then the         > v2.A0
        mapping operation between World and Device Frames are         > v2.A0
        identical and can be skipped entirely since an X/Y            > v2.A0
        coordinate in the World Frame directly corresponds to         > v2.A0
        a pixel location in the Device Frame.                         > v2.A0

        The maximum dimensions of the world coordinate frame is       > v2.A4
        65535x65535.                                                  > v2.A4

Since versions of the RIPscrip specification prior to v2.0 were based > v2.A0
on a 640x350 resolution without any World Frame, a suitable set of    > v2.A0
defaults need to be assumed for the World Frame and the Logical       > v2.A0
Frame.  The World Frame would be set to a dimension of 640 across and > v2.A0
350 high.                                                             > v2.A4



╔═══════════════════════════════════════════════════╗
║ 2.6 ■ THE MATHEMATICS OF GRAPHICS AND COORDINATES ║
╚═══════════════════════════════════════════════════╝

Mathematics, unlike graphics, is abstract in nature.  Graphics on the > v2.A0
other hand, is very discrete in nature.  A pixel in graphics is the   > v2.A0
smallest displayable element on a graphics screen (Picture Element).  > v2.A0
The corresponding concept in mathematics is a single point.  A pixel  > v2.A0
has a discrete size and shape in graphics whereas in mathematics, a   > v2.A0
point is infinitely small and occupies no physical space in the       > v2.A0
cartesian coordinate system in which it exists.                       > v2.A0

In graphics we use the concept of coordinates and points to specify   > v2.A0
where a pixel is located.  If graphics were like mathematics where a  > v2.A0
pixel was infinitely small, a graphics monitor wouldn't show anything > v2.A0
other than black because a pixel would be infinitely small surrounded > v2.A0
by blackness.  But this is not the case.  Graphics hardware has to    > v2.A0
have pixels defined as discrete areas of the screen - addressable     > v2.A0
areas of the screen that can be set to a particular color.  This is   > v2.A0
how we see things on the screen, as individual pixels of data used    > v2.A0
together to represent some kind of image.                             > v2.A0

Just like the point in mathematics, a line is infinitely thin, but    > v2.A0
has length.  A line is composed of an infinite number of points       > v2.A0
between the beginning and ending locations of the line.               > v2.A0

Relating these two distinctly different concepts to each other though > v2.A0
doesn't always lend itself to a simple situation to understand.  On   > v2.A0
the surface, a pixel's coordinate location appears to be the same     > v2.A0
thing as it is in mathematics.  But, when you get into deeper issues  > v2.A0
of graphics theory this isn't truly the case because of the           > v2.A0
difference in sizes of a point compared to a pixel.  In math, points  > v2.A0
don't have to be on even integer boundaries - they can be fractional. > v2.A0
A point can be at (2.53,1.295), whereas in graphics, a pixel cannot   > v2.A0
be at a fractional location - there's no such thing as a part of a    > v2.A0
pixel!                                                                > v2.A0

A graphics screen is designed so that every pixel location on the     > v2.A0
screen has a unique location specified (in human terms) as an X/Y     > v2.A0
coordinate pair.  This is called the Cartesian Coordinate System.  It > v2.A0
is by far one of the easiest ways of representing a coordinate in a   > v2.A0
two-dimensional world like a monitor.  If you zoom in closely on a    > v2.A0
monitor and look at the layout of pixels and their relationships to   > v2.A0
coordinates, you might see something like this:                       > v2.A0



                          (X DIMENSION)                               > v2.A0

                             1│1│1│1│1│1│1│1│1│1│2│2│2│2│             > v2.A0
        │0│1│2│3│4│5│6│7│8│9│0│1│2│3│4│5│6│7│8│9│0│1│2│3│             > v2.A0
      ──╔═╤═╤═╤═╤═╤═╤═╤═╤═╤═╤═╤═╤═╤═╤═╤═╤═╤═╤═╤═╤═╤═╤═╤═╗             > v2.A0
       0║ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ║             > v2.A0
      ──╟─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢             > v2.A0
       1║ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ║             > v2.A0
      ──╟─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢             > v2.A0
  Y    2║ │ │ │ │ │ │ │ │ │ │ │█│█│ │ │ │ │ │ │ │ │ │ │ ║             > v2.A0
      ──╟─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢             > v2.A0
  D    3║ │ │ │ │ │ │ │ │ │ │ │█│█│ │ │ │ │ │ │ │ │ │ │ ║             > v2.A0
  I   ──╟─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢             > v2.A0
  M    4║ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ║             > v2.A0
  E   ──╟─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢             > v2.A0
  N    5║ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ║             > v2.A0
  S   ──╟─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢             > v2.A0
  I    6║ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ║             > v2.A0
  O   ──╟─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢             > v2.A0
  N    7║ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ║             > v2.A0
      ──╟─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢             > v2.A0
       8║ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ║             > v2.A0
      ──╚═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╝             > v2.A0

If you look at the previous diagram, you can see that there is a grid > v2.A0
of pixels that is 24 pixels wide (the X direction) and 10 pixels high > v2.A0
(the Y direction).  Each of the squares is a black pixel.  The pixels > v2.A0
contain a "#" are considered white pixels.  There are four pixels     > v2.A0
that are ON in this diagram, at locations (11,2), (12,2), (11,3) and  > v2.A0
(12,3).  This is how graphics hardware addresses graphics pixels, by  > v2.A0
specifying an X/Y coordinate location for a pixel to turn it on or    > v2.A0
off (or more generally, to set it to a particular color).             > v2.A0

If you look closely at the locations of the coordinates in the        > v2.A0
previous diagram, the X/Y coordinates address the physical pixel      > v2.A0
cells themselves.  Each pixel cell is separated by infinitely thin    > v2.A0
lines - the pixel cells' borders so to speak.  Now, each pixel is     > v2.A0
physically adjacent to the ones next to it and there are no gaps      > v2.A0
between them.  This is the way graphics hardware works.               > v2.A0

Now that we've described the way graphics hardware addresses pixel    > v2.A0
locations, let's look at why it's not really the best way of          > v2.A0
describing graphics mathematically.  For the hardware, this is the    > v2.A0
best way of handling things, but mathematically, it's not.            > v2.A0

The world of graphics hardware has many different facets.  One        > v2.A0
graphics display device can often times display graphics at different > v2.A0
resolutions.  A typical video card on the IBM-PC can display graphics > v2.A0
at 320x200, 640x350, 640x400, 640x480, 800x600, 1024x768 and even as  > v2.A0
high as 1280x1024 and higher.  That's quite a bit of difference in    > v2.A0
pixel grids (like the one shown earlier).  Not only can the number of > v2.A0
pixels change horizontally and vertically, but when the resolutions   > v2.A0
get higher, the pixels get smaller and harder to see.  When graphics  > v2.A0
hardware can achieve a resolution of infinity by infinity, then we    > v2.A0
will have achieved perfect sight (like what we see around us).  But   > v2.A0
obviously, this will probably never happen in our lifetimes (or our   > v2.A0
great granchildren's for that matter).                                > v2.A0



What would happen if you had a line drawn on a graphics screen from   > v2.A0
coordinates (0,0) to (639,349) at 640x350 resolution?  You would      > v2.A0
have a nice little line on the screen that stretches from the upper-  > v2.A0
left corner to the lower-right corner.  Now, if you drew the same     > v2.A0
line at 800x600 resolution?  Your line would no longer go all the way > v2.A0
to the bottom of the screen or to the far right of the screen.  It    > v2.A0
would stop about 2/3'rds of the way down and over.                    > v2.A0

The problems start to come up with mathematics and graphical          > v2.A0
representations when we try to make something look the same at one    > v2.A0
resolution as it does in another (resolution independence).  Sure     > v2.A0
you can translate a coordinate in one resolution to some other        > v2.A0
coordinate in a different resolution.  All you need to know are the   > v2.A0
dimensions of each resolution and a bit of algebra.  But pixels       > v2.A0
aren't the same thickness!  The line described previously could still > v2.A0
be drawn properly to the lower-right of the screen, but it would      > v2.A0
appear a lot thinner.  You could try drawing two lines offset by one  > v2.A0
pixel location and you would come "close" to the original thickness   > v2.A0
of the line at 640x350 resolution, but it wouldn't be a perfect       > v2.A0
match.  A perfect match is a rare thing when dealing with different   > v2.A0
resolutions.                                                          > v2.A0

Now, on to the real issue at hand here: translation of coordinates.   > v2.A0
We won't worry about the size of pixels, but will concentrate on      > v2.A0
getting the locations of points correct at different resolutions.     > v2.A0
Let's say you have a screen at 640x350 resolution with two filled     > v2.A0
rectangles drawn on it.  The first rectangle is drawn from (2,1) to   > v2.A0
(4,3) and the second one is drawn from (5,1) to (7,3) like this:      > v2.A0

                      │0│1│2│3│4│5│6│7│8│9│                           > v2.A0
                    ──╔═╤═╤═╤═╤═╤═╤═╤═╤═╤═╗                           > v2.A0
                     0║ │ │ │ │ │ │ │ │ │ ║     1st: (2,1) - (4,3)    > v2.A0
                    ──╟─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢     2nd: (5,1) - (7,3)    > v2.A0
                     1║ │ │█│█│█│░│░│░│ │ ║                           > v2.A0
                    ──╟─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢                           > v2.A0
                     2║ │ │█│█│█│░│░│░│ │ ║                           > v2.A0
                    ──╟─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢                           > v2.A0
                     3║ │ │█│█│█│░│░│░│ │ ║                           > v2.A0
                    ──╟─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢                           > v2.A0
                     4║ │ │ │ │ │ │ │ │ │ ║                           > v2.A0
                    ──╚═╧═╧═╧═╧═╧═╧═╧═╧═╧═╝                           > v2.A0

Now, you notice that both rectangles are right next to each other.    > v2.A0
There are no gaps between them.  Now, if you tried to draw these same > v2.A0
two rectangles on a graphics screen that was 1280x700 pixels in size, > v2.A0
and tried to make it appear in the exact same location and size on    > v2.A0
the monitor, you would have to translate the corners of the           > v2.A0
rectangles to the new resolution and re-plot the rectangles.  Now,    > v2.A0
640x2 is 1280 and 350x2 is 700 so our new resolution is exactly twice > v2.A0
as large in both the X and Y directions (this is RARELY the case!).   > v2.A0
So, in order to translate our original coordinates to this resolution > v2.A0
we simply multiply the numbers by 2.  Pretty simple.  Our previous    > v2.A0
rectangles in their old untranslated state and the newly translated   > v2.A0
ones would be:                                                        > v2.A0

                    ╔═══════════════╤═════════════════╗               > v2.A0
                    ║ Untranslated  │   Translated    ║               > v2.A0
      ╔═════════════╬═══════════════╪═════════════════╣               > v2.A0
      ║ Rectangle 1 ║ (2,1) - (4,3) │  (4,2) - (8,6)  ║               > v2.A0
      ║ Rectangle 2 ║ (5,1) - (7,3) │ (10,2) - (14,6) ║               > v2.A0
      ╚═════════════╩═══════════════╧═════════════════╝               > v2.A0


Now, let's plot these two rectangles on our new graphics screen at    > v2.A0
the newly translated coordinates:                                     > v2.A0

                            (X DIMENSION)                             > v2.A0

                                     │1│1│1│1│1│1│1│                  > v2.A0
                 │0│1│2│3│4│5│6│7│8│9│0│1│2│3│4│5│6│                  > v2.A0
               ──╔═╤═╤═╤═╤═╤═╤═╤═╤═╤═╤═╤═╤═╤═╤═╤═╤═╗                  > v2.A0
                0║ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ║                  > v2.A0
               ──╟─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢                  > v2.A0
                1║ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ║                  > v2.A0
               ──╟─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢                  > v2.A0
           Y    2║ │ │ │ │█│█│█│█│█│ │░│░│░│░│░│ │ ║                  > v2.A0
               ──╟─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢                  > v2.A0
           D    3║ │ │ │ │█│█│█│█│█│ │░│░│░│░│░│ │ ║                  > v2.A0
           I   ──╟─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢                  > v2.A0
           M    4║ │ │ │ │█│█│█│█│█│ │░│░│░│░│░│ │ ║                  > v2.A0
           E   ──╟─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢                  > v2.A0
           N    5║ │ │ │ │█│█│█│█│█│ │░│░│░│░│░│ │ ║                  > v2.A0
           S   ──╟─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢                  > v2.A0
           I    6║ │ │ │ │█│█│█│█│█│ │░│░│░│░│░│ │ ║                  > v2.A0
           O   ──╟─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢                  > v2.A0
           N    7║ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ║                  > v2.A0
               ──╟─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢                  > v2.A0
                8║ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ║                  > v2.A0
               ──╚═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╝                  > v2.A0

What happened?  We now have a black line in between the two           > v2.A0
rectangles.  That's definitely not what we wanted to happen.  Why did > v2.A0
this happen?  It's partly because of the nature of graphics hardware  > v2.A0
in the way they address pixels, and partly the way we humans think of > v2.A0
pixels mathematically from a programming standpoint.  What we need is > v2.A0
a better mathematical representation of pixels and graphics           > v2.A0
coordinates so that when we translate coordinates these things don't  > v2.A0
happen.                                                               > v2.A0

As we mentioned earlier, the lines on the above diagram represent the > v2.A0
borders around each pixel.  Each of these lines, like their           > v2.A0
mathematical counterparts, are infinitely thin.  The only thing in    > v2.A0
the above diagram that has any size (or area) physically are the      > v2.A0
pixels themselves.  Since the boundary lines around the pixels are    > v2.A0
defining the area that the pixel will occupy, it makes sense that we  > v2.A0
should think of those lines as the actual coordinates.  If we think   > v2.A0
of the areas in between the pixels as the actual coordinates, we can  > v2.A0
think of pixels as the areas in between coordinates that are filled   > v2.A0
in with color.  So, if we said to draw a filled in rectangle like we  > v2.A0
did earlier, we would actually be saying "fill in this rectangle's    > v2.A0
interior".  Just like coloring books as a child, you have to stay     > v2.A0
inside the lines (or at least we're supposed to).  Think about pixels > v2.A0
as spots between the lines that get filled in with color just like a  > v2.A0
coloring book - the only difference is, a pixel cannot go outside the > v2.A0
lines (don't you wish you were a pixel when you were younger?).       > v2.A0


Using this new way of thinking of graphics is not very difficult, it  > v2.A0
just seems a bit odd -especially if you've been working with graphics > v2.A0
for awhile.  To draw the previous two rectangles properly the         > v2.A0
coordinates for them would have to be changed somewhat - like this:   > v2.A0



                    ╔═════════════════════════════════╗               > v2.A0
                    ║         (old method)            ║               > v2.A0
                    ╟───────────────┬─────────────────╢               > v2.A0
                    ║ Untranslated  │   Translated    ║               > v2.A0
      ╔═════════════╬═══════════════╪═════════════════╣               > v2.A0
      ║ Rectangle 1 ║ (2,1) - (4,3) │  (4,2) - (8,6)  ║               > v2.A0
      ║ Rectangle 2 ║ (5,1) - (7,3) │ (10,2) - (14,6) ║               > v2.A0
      ╚═════════════╩═══════════════╧═════════════════╝               > v2.A0


                    ╔═════════════════════════════════╗               > v2.A0
                    ║         (new method)            ║               > v2.A0
                    ╟───────────────┬─────────────────╢               > v2.A0
                    ║ UNTRANSLATED  │  TRANSLATED     ║               > v2.A0
      ╔═════════════╬═══════════════╪═════════════════╣               > v2.A0
      ║ RECTANGLE 1 ║ (2,1) - (5,4) │  (4,2) - (10,8) ║               > v2.A0
      ║ RECTANGLE 2 ║ (5,1) - (8,4) │ (10,2) - (16,8) ║               > v2.A0
      ╚═════════════╩═══════════════╧═════════════════╝               > v2.A0

Notice that the untranslated rectangles' coordinates are almost the   > v2.A0
same.  In fact, the upper-left coordinates haven't changed at all.    > v2.A0
The only coordinates that have changed are the lower-right            > v2.A0
coordinates, and only by one pixel location.  Now, if we draw these   > v2.A0
two rectangles using our new mathematical model for graphics, we      > v2.A0
would get the following (in both resolution examples:                 > v2.A0

                                                   1 1 1 1 1 1 1 1    > v2.A0
                               0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7    > v2.A0
                              0╔═╪═╪═╪═╪═╪═╪═╪═╪═╪═╪═╪═╪═╪═╪═╪═╪═╗    > v2.A0
                        1      ║ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ║    > v2.A0
    0 1 2 3 4 5 6 7 8 9 0     1╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢    > v2.A0
   0╔═╪═╪═╪═╪═╪═╪═╪═╪═╪═╗      ║ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ║    > v2.A0
    ║ │ │ │ │ │ │ │ │ │ ║     2╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢    > v2.A0
   1╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢      ║ │ │ │ │█│█│█│█│█│█│░│░│░│░│░│ │ ║    > v2.A0
    ║ │ │█│█│█│░│░│░│ │ ║     3╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢    > v2.A0
   2╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢      ║ │ │ │ │█│█│█│█│█│█│░│░│░│░│░│ │ ║    > v2.A0
    ║ │ │█│█│█│░│░│░│ │ ║     4╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢    > v2.A0
   3╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢      ║ │ │ │ │█│█│█│█│█│█│░│░│░│░│░│ │ ║    > v2.A0
    ║ │ │█│█│█│░│░│░│ │ ║     5╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢    > v2.A0
   4╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢      ║ │ │ │ │█│█│█│█│█│█│░│░│░│░│░│ │ ║    > v2.A0
    ║ │ │ │ │ │ │ │ │ │ ║     6╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢    > v2.A0
   5╚═╧═╧═╧═╧═╧═╧═╧═╧═╧═╝      ║ │ │ │ │█│█│█│█│█│█│░│░│░│░│░│ │ ║    > v2.A0
                              7╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢    > v2.A0
                               ║ │ │ │ │█│█│█│█│█│█│░│░│░│░│░│ │ ║    > v2.A0
                              8╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢    > v2.A0
                               ║ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ║    > v2.A0
                              9╚═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╝    > v2.A0

If you look closely at the two graphs above you may notice a subtle   > v2.A0
difference in the numbering of the coordinates.  The numbers are all  > v2.A0
there, but instead of labeling the cells themselves with coordinates, > v2.A0
we have labeled the lines in between as the coordinates.  When we say > v2.A0
to draw a rectangle from (2,1) to (5,4) we are saying to draw a       > v2.A0
filled in area "between" coordinate lines 2 and 5 in the X direction  > v2.A0
and 1 and 4 in the Y direction.  If you look closely at the upper     > v2.A0
left diagram, you will notice that is exactly what we have done.  Now > v2.A0
look closely at the upper right diagram.  There are no gaps between   > v2.A0
the rectangles now.  Also if you look at the translated coordinates,  > v2.A0
the right edge of the first rectangle is at X coordinate 10, and the  > v2.A0
left edge of the second rectangle is also at X coordinate 10.  But    > v2.A0
they don't overlap each other.  That's the part about this new way of > v2.A0


thinking about things that gives people the hardest time.             > v2.A0

So far so good.  Let's look at another example - one which draws the  > v2.A0
same two rectangles but this time, let's not fill them in.  The       > v2.A0
diagram below shows the two at both example resolutions:              > v2.A0

                                                   1 1 1 1 1 1 1 1    > v2.A0
                               0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7    > v2.A0
                              0╔═╪═╪═╪═╪═╪═╪═╪═╪═╪═╪═╪═╪═╪═╪═╪═╪═╗    > v2.A0
                        1      ║ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ║    > v2.A0
    0 1 2 3 4 5 6 7 8 9 0     1╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢    > v2.A0
   0╔═╪═╪═╪═╪═╪═╪═╪═╪═╪═╗      ║ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ║    > v2.A0
    ║ │ │ │ │ │ │ │ │ │ ║     2╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢    > v2.A0
   1╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢      ║ │ │ │ │█│█│█│█│█│█│░│░│░│░│░│ │ ║    > v2.A0
    ║ │ │█│█│█│░│░│░│ │ ║     3╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢    > v2.A0
   2╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢      ║ │ │ │ │█│ │ │ │ │ │░│ │ │ │░│ │ ║    > v2.A0
    ║ │ │█│ │ │░│ │░│ │ ║     2╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢    > v2.A0
   3╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢      ║ │ │ │ │█│ │ │ │ │ │░│ │ │ │░│ │ ║    > v2.A0
    ║ │ │█│█│█│░│░│░│ │ ║     5╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢    > v2.A0
   4╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢      ║ │ │ │ │█│ │ │ │ │ │░│ │ │ │░│ │ ║    > v2.A0
    ║ │ │ │ │ │ │ │ │ │ ║     6╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢    > v2.A0
   5╚═╧═╧═╧═╧═╧═╧═╧═╧═╧═╝      ║ │ │ │ │█│ │ │ │ │ │░│ │ │ │░│ │ ║    > v2.A0
                              7╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢    > v2.A0
                               ║ │ │ │ │█│█│█│█│█│█│░│░│░│░│░│ │ ║    > v2.A0
                              8╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢    > v2.A0
                               ║ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ║    > v2.A0
                              9╚═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╝    > v2.A0

Not what you thought would happen, was it?  This example illustrates  > v2.A0
a key point in our mathematical model of graphics: that there is a    > v2.A0
difference between filled objects and outlined objects.  Filled       > v2.A0
objects fill everything inside an enclosed area whereas an outline    > v2.A0
(one or more lines) uses pixels to approximate an infinitely thin     > v2.A0
line.  When lines and points are plotted on the video device, they    > v2.A0
are "rounded up" to the next highest pixel location.  So, a point at  > v2.A0
(4,2) would not be on the intersecting lines at (4,2), it would be a  > v2.A0
pixel activated between 4 and 5 on the X axis and 2 and 3 on the Y    > v2.A0
axis.  Look at the upper right diagram to convince yourself this is   > v2.A0
the case.  Filled-in areas on the other hand, do not round up to the  > v2.A0
next highest pixel locations.  They always fill in an area in-between > v2.A0
the boundary lines.  This means that in a filled-in rectangle, the    > v2.A0
right and bottom edges are "off by one" so to speak.                  > v2.A0

To better illustrate these two different situations, we will draw a   > v2.A0
filled-in rectangle and a non-filled rectangle both using the same    > v2.A0
dimensions at the same resolution, then we will superimpose them on   > v2.A4
top of each other to better show the differences;



  0 1 2 3 4 5 6 7 8 9    0 1 2 3 4 5 6 7 8 9    0 1 2 3 4 5 6 7 8 9   > v2.A4
 0╔═╪═╪═╪═╪═╪═╪═╪═╪═╗   0╔═╪═╪═╪═╪═╪═╪═╪═╪═╗   0╔═╪═╪═╪═╪═╪═╪═╪═╪═╗   > v2.A4
  ║ │ │ │ │ │ │ │ │ ║    ║ │ │ │ │ │ │ │ │ ║    ║ │ │ │ │ │ │ │ │ ║   > v2.A4
 1╫─┼─┼─┼─┼─┼─┼─┼─┼─╢   1╫─┼─┼─┼─┼─┼─┼─┼─┼─╢   1╫─┼─┼─┼─┼─┼─┼─┼─┼─╢   > v2.A4
  ║ │░│░│░│░│░│░│ │ ║    ║ │█│█│█│█│█│█│█│ ║    ║ │▒│▒│▒│▒│▒│▒│█│ ║   > v2.A4
 2╫─┼─┼─┼─┼─┼─┼─┼─┼─╢   2╫─┼─┼─┼─┼─┼─┼─┼─┼─╢   2╫─┼─┼─┼─┼─┼─┼─┼─┼─╢   > v2.A4
  ║ │░│░│░│░│░│░│ │ ║    ║ │█│ │ │ │ │ │█│ ║    ║ │▒│░│░│░│░│░│█│ ║   > v2.A4
 3╫─┼─┼─┼─┼─┼─┼─┼─┼─╢   3╫─┼─┼─┼─┼─┼─┼─┼─┼─╢   3╫─┼─┼─┼─┼─┼─┼─┼─┼─╢   > v2.A4
  ║ │░│░│░│░│░│░│ │ ║    ║ │█│ │ │ │ │ │█│ ║    ║ │▒│░│░│░│░│░│█│ ║   > v2.A4
 4╫─┼─┼─┼─┼─┼─┼─┼─┼─╢   4╫─┼─┼─┼─┼─┼─┼─┼─┼─╢   4╫─┼─┼─┼─┼─┼─┼─┼─┼─╢   > v2.A4
  ║ │░│░│░│░│░│░│ │ ║    ║ │█│ │ │ │ │ │█│ ║    ║ │▒│░│░│░│░│░│█│ ║   > v2.A4
 5╫─┼─┼─┼─┼─┼─┼─┼─┼─╢   5╫─┼─┼─┼─┼─┼─┼─┼─┼─╢   5╫─┼─┼─┼─┼─┼─┼─┼─┼─╢   > v2.A4
  ║ │ │ │ │ │ │ │ │ ║    ║ │█│█│█│█│█│█│█│ ║    ║ │█│█│█│█│█│█│█│ ║   > v2.A4
 6╫─┼─┼─┼─┼─┼─┼─┼─┼─╢   6╫─┼─┼─┼─┼─┼─┼─┼─┼─╢   6╫─┼─┼─┼─┼─┼─┼─┼─┼─╢   > v2.A4
  ║ │ │ │ │ │ │ │ │ ║    ║ │ │ │ │ │ │ │ │ ║    ║ │ │ │ │ │ │ │ │ ║   > v2.A4
 7╚═╧═╧═╧═╧═╧═╧═╧═╧═╝   7╚═╧═╧═╧═╧═╧═╧═╧═╧═╝   7╚═╧═╧═╧═╧═╧═╧═╧═╧═╝   > v2.A4
    Filled rectangle      Unfilled rectangle      Both rectangles     > v2.A4
     (1,1) - (7,5)          (1,1) - (7,5)          (1,1) - (7,5)      > v2.A4

Notice that the two rectangles are not the exact same size.  Both the > v2.A0
left and top edges are at the exact same locations, but in the case   > v2.A0
of the unfilled rectangle, the right and bottom edges are one pixel   > v2.A0
over and down.  This shows that lines and points are rounded up to    > v2.A0
the next highest pixel location (the first pixel after the            > v2.A0
coordinate), but filled areas fill between the boundary lines.  This  > v2.A0
seemingly odd way of doing things becomes extremely important when    > v2.A0
you deal with one image at different resolutions - as you saw with    > v2.A0
the case of translating two filled-in rectangles earlier from one     > v2.A0
resolution to another.                                                > v2.A0

In a very real sense, you could easily think about coordinates and    > v2.A0
graphics in two different ways.  The way to think about them depends  > v2.A0
on the type of graphics operation being performed.  If you are        > v2.A0
dealing with a fill operation of some kind, then you think about the  > v2.A0
drawing surface with coordinate lines "in between" the physical pixel > v2.A0
cells.  If you are dealing with a line drawing situation (or drawing  > v2.A0
points, circles, etc), then you can think of coordinates directly     > v2.A0
addressing the pixel cells themselves (just like when we began this   > v2.A0
conversation at the beginning of this section).  When dealing with    > v2.A0
line drawing operations, there is no difference in mathematical       > v2.A0
models - there's only a difference when you get into filling areas    > v2.A0
in.  Whichever method of thinking of things works best for you, use.  > v2.A0

Other filled objects work the same way as do filled rectangles.  For  > v2.A4
example, consider an unfilled polygon with the following vertices:    > v2.A4

                       ╔═══════╤═══════╗                              > v2.A4
                       ║ X Pos │ Y Pos ║                              > v2.A4
            ╔══════════╬═══════╪═══════╣                              > v2.A4
            ║ Vertex 0 ║    0  │   0   ║                              > v2.A4
            ║ Vertex 1 ║    8  │   0   ║                              > v2.A4
            ║ Vertex 2 ║   14  │   3   ║                              > v2.A4
            ║ Vertex 3 ║   14  │   4   ║                              > v2.A4
            ║ Vertex 4 ║   12  │   6   ║                              > v2.A4
            ║ Vertex 5 ║    4  │   6   ║                              > v2.A4
            ║ Vertex 6 ║    0  │   2   ║                              > v2.A4
            ║ Vertex 7 ║    0  │   0   ║                              > v2.A4
            ╚══════════╩═══════╧═══════╝                              > v2.A4



With this polygon we would have a polygon that looks like the left    > v2.A4
diagram below.  The right diagram is what it would look like if it    > v2.A4
were filled and had a border drawn at the same time (the different    > v2.A4
shaded blocks indicates which is border, fill-color, or both):        > v2.A4

                       1 1 1 1 1 1                       1 1 1 1 1 1  > v2.A4
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5  > v2.A4
  0╔═╪═╪═╪═╪═╪═╪═╪═╪═╪═╪═╪═╪═╪═╪═╗  0╔═╪═╪═╪═╪═╪═╪═╪═╪═╪═╪═╪═╪═╪═╪═╗  > v2.A4
   ║█│█│█│█│█│█│█│█│█│ │ │ │ │ │ ║   ║▒│▒│▒│▒│▒│▒│▒│▒│█│ │ │ │ │ │ ║  > v2.A4
  1╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢  1╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢  > v2.A4
   ║█│ │ │ │ │ │ │ │ │█│█│ │ │ │ ║   ║▒│░│░│░│░│░│░│░│░│█│█│ │ │ │ ║  > v2.A4
  2╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢  2╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢  > v2.A4
   ║█│ │ │ │ │ │ │ │ │ │ │█│█│ │ ║   ║▒│░│░│░│░│░│░│░│░│░│░│█│█│ │ ║  > v2.A4
  3╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢  3╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢  > v2.A4
   ║ │█│ │ │ │ │ │ │ │ │ │ │ │█│█║   ║ │▒│░│░│░│░│░│░│░│░│░│░│░│█│█║  > v2.A4
  4╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢  4╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢  > v2.A4
   ║ │ │█│ │ │ │ │ │ │ │ │ │ │ │█║   ║ │ │▒│░│░│░│░│░│░│░│░│░│░│░│█║  > v2.A4
  5╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢  5╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢  > v2.A4
   ║ │ │ │█│ │ │ │ │ │ │ │ │ │█│ ║   ║ │ │ │▒│░│░│░│░│░│░│░│░│░│█│ ║  > v2.A4
  6╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢  6╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢  > v2.A4
   ║ │ │ │ │█│█│█│█│█│█│█│█│█│ │ ║   ║ │ │ │ │█│█│█│█│█│█│█│█│█│ │ ║  > v2.A4
  7╚═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╝  7╚═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╝  > v2.A4
          Unfilled polygon             Filled and unfilled polygon    > v2.A4

Taking a second example.  Let's consider an unfilled oval centered    > v2.A4
at (7,3) with a horizontal radius of 8 and a vertical radius of 4.    > v2.A4
The unfilled oval is depicted in the left diagram below.  The diagram > v2.A4
on the right is the same oval with the border drawn and also filled   > v2.A4
in.  Notice how the border is drawn in relation to the filled-in      > v2.A4
interior and how it adheres to resolution independence.               > v2.A4

                       1 1 1 1 1 1                       1 1 1 1 1 1  > v2.A4
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5  > v2.A4
  0╔═╪═╪═╪═╪═╪═╪═╪═╪═╪═╪═╪═╪═╪═╪═╗  0╔═╪═╪═╪═╪═╪═╪═╪═╪═╪═╪═╪═╪═╪═╪═╗  > v2.A4
   ║ │ │ │ │█│█│█│█│█│█│█│ │ │ │ ║   ║ │ │ │ │▒│▒│▒│▒│▒│▒│█│ │ │ │ ║  > v2.A4
  1╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢  1╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢  > v2.A4
   ║ │ │█│█│ │ │ │ │ │ │ │█│█│ │ ║   ║ │ │▒│▒│░│░│░│░│░│░│░│█│█│ │ ║  > v2.A4
  2╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢  2╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢  > v2.A4
   ║ │█│ │ │ │ │ │ │ │ │ │ │ │█│ ║   ║ │▒│░│░│░│░│░│░│░│░│░│░│░│█│ ║  > v2.A4
  3╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢  3╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢  > v2.A4
   ║█│ │ │ │ │ │ │■│ │ │ │ │ │ │█║   ║▒│░│░│░│░│░│░│■│░│░│░│░│░│░│█║  > v2.A4
  4╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢  4╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢  > v2.A4
   ║█│ │ │ │ │ │ │ │ │ │ │ │ │ │█║   ║▒│░│░│░│░│░│░│░│░│░│░│░│░│░│█║  > v2.A4
  5╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢  5╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢  > v2.A4
   ║ │█│ │ │ │ │ │ │ │ │ │ │ │█│ ║   ║ │▒│░│░│░│░│░│░│░│░│░│░│░│█│ ║  > v2.A4
  6╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢  6╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢  > v2.A4
   ║ │ │█│█│ │ │ │ │ │ │ │█│█│ │ ║   ║ │ │▒│▒│░│░│░│░│░│░│░│█│█│ │ ║  > v2.A4
  7╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢  7╫─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─╢  > v2.A4
   ║ │ │ │ │█│█│█│█│█│█│█│ │ │ │ ║   ║ │ │ │ │█│█│█│█│█│█│█│ │ │ │ ║  > v2.A4
  8╚═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╝  8╚═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╧═╝  > v2.A4

If you look closely at the right diagram, you will notice that the    > v2.A4
oval isn't "balanced".  This is because in this situation, the oval   > v2.A4
is centered about a particular point, but the filled oval is          > v2.A4
partially offset on an odd-boundary - the filled interior is 8 pixels > v2.A4
to the left of the center point (inclusive), and 7 pixels to the      > v2.A4
right of the center point (inclusive).  This is due to the resolution > v2.A4
independent nature of filled regions.  If you need to draw a          > v2.A4
perfectly smooth filled oval, draw one with a solid fill and with     > v2.A4
borders enabled, both with the same drawing and fill color.           > v2.A4


╔═══════════════════════════════════════════════════════╗
║ 2.7 ■ COLOR PALETTES AND HARDWARE - COLOR TRANSLATION ║
╚═══════════════════════════════════════════════════════╝

With versions of RIPscrip prior to v2.0, the color palette was        > v2.A0
limited to 16 colors maximum out of a total of 64 colors in the       > v2.A0
Master Color Palette.  This was due to the hardware origins of the    > v2.A4
language in its initial releases.  With the popularity of higher      > v2.A4
color video sub-systems, RIPscrip needed to grow to accomodate these  > v2.A4
advancing trends.  In addition, it needed to be open-ended enough to  > v2.A4
accomodate yet unknown hardware environments that might provide for   > v2.A4
even higher color resolution.                                         > v2.A4

The 1.xx RIPscrip specification provided for 16 colors out of a       > v2.A0
palette of 64 colors.  This 64 color palette corresponded to 2-bits   > v2.A4
of Red, Green and Blue information each, giving you four levels of    > v2.A0
color saturation in each of the three categories.  Unlike typical RGB > v2.A0
implementations the color palette entry numbers are not sequentially  > v2.A0
ordered based on the R, G and B components.  The bit-layouts of the   > v2.A4
color values as follows:                                              > v2.A4

                       Primary    Secondary                           > v2.A0
                     ├─────────┤ ├─────────┤                          > v2.A0
            ╔═══╤═══╦═══╤═══╤═══╦═══╤═══╤═══╗                         > v2.A0
            ║▒▒▒│▒▒▒║   │   │   ║   │   │   ║                         > v2.A0
            ║▒▒▒│▒▒▒║ R │ G │ B ║ r │ g │ b ║                         > v2.A0
            ║▒▒▒│▒▒▒║   │   │   ║   │   │   ║                         > v2.A0
            ╚═══╧═══╩═══╧═══╧═══╩═══╧═══╧═══╝                         > v2.A0
              80  40  20  10  8   4   2   1  (hex)                    > v2.A0
              7   6   5   4   3   2   1   0  (position)               > v2.A0

Notice that each of the R, G and B sections are broken up into two    > v2.A0
separate bit sections in the color palette entry number.  Also, the   > v2.A0
bits are reversed when they are encoded.  Let's look at four separate > v2.A0
colors of Red, Green and Blue to see how the bit patterns correspond  > v2.A0
to the actual Palette entries:                                        > v2.A0

        ╔══════════════════╦══════════════════╦══════════════════╗    > v2.A0
        ║        RED       ║       GREEN      ║       BLUE       ║    > v2.A0
╔═══════╬══════════╤═══════╬══════════╤═══════╬══════════╤═══════╣    > v2.A0
║ Level ║ xxRGBrgb │ Value ║ xxRGBrgb │ Value ║ xxRGBrgb │ Value ║    > v2.A0
╠═══════╬══════════╪═══════╬══════════╪═══════╬══════════╪═══════╣    > v2.A0
║   00  ║ 00000000 │    0  ║ 00000000 │   0   ║ 00000000 │   0   ║    > v2.A4
║   01  ║ 00100000 │   32  ║ 00010000 │  16   ║ 00001000 │   8   ║    > v2.A4
║   10  ║ 00000100 │    4  ║ 00000010 │   2   ║ 00000001 │   1   ║    > v2.A4
║   11  ║ 00100100 │   36  ║ 00010010 │  18   ║ 00001001 │   9   ║    > v2.A4
╚═══════╩══════════╧═══════╩══════════╧═══════╩══════════╧═══════╝    > v2.A0

The base 16 color palette in RIPscrip 1.54 and earlier was modified   > v2.A4
by the RIP_SET_PALETTE and RIP_ONE_PALETTE commands.  These commands  > v2.A4
are limited to a maximum of 16 colors and only accomodate 2-bits for  > v2.A4
each color component.  These commands are here on out referred to as  > v2.A4
the "desktop palette" alteration commands and are only designed to    > v2.A4
make "simple" changes to the lowest 16 colors with a limited set of   > v2.A4
color saturation in each of the red, green and blue components.       > v2.A4

Under RIPscrip 2.0 and later, we deal with the concept of a 256-entry > v2.A4
color lookup table (otherwise known as the drawing palette).  This    > v2.A4
palette of RGB colors is used to cross-reference a particular color   > v2.A4
number to some arbitrary RGB color combination much like the earlier  > v2.A4
1.xx palette counterparts, but with some more important differences.  > v2.A4


The newer set palette commands allow you to specify the number of     > v2.A4
bits for each red, green and blue component, and in addition, the     > v2.A4
internal layout of each RGB value isn't encoded in a seemingly        > v2.A4
haphazard fashion.  A color value is a raw binary number without any  > v2.A4
frills or complications.  If the bit value were 00100100 then the     > v2.A4
actual color saturation level would be 36, not encoded in a strange   > v2.A4
bit swapped fashion as in the older color palette commands.  It is    > v2.A4
prophesized that the older color palette commands will not be used    > v2.A4
much (if at all) in the newer 2.0 environments due to their           > v2.A4
complexity - about the only way that the older commands will be used  > v2.A4
is via software packages that only output colors in the older syntax. > v2.A4

Since RIPscrip 1.54 and earlier didn't know about the 256-entry       > v2.A4
color lookup table, we have introduced two new color palette          > v2.A4
commands:                                                             > v2.A4

     RIP_ONE_DRAWING_PALETTE ... Set one color in the drawing         > v2.A4
                                 palette to an arbitrary RGB          > v2.A4
                                 color combination.                   > v2.A4

     RIP_SET_DRAWING_PALETTE ... Set a block of colors in the         > v2.A4
                                 drawing palette to some set of       > v2.A4
                                 arbitrary RGB color values.          > v2.A4

These commands supercede the older 1.54 commands and are much more    > v2.A4
flexible.  They not only allow you to access the entire 256-entry     > v2.A4
color lookup table, but they allow you to specify how many bits of    > v2.A4
precision of RGB component data are used in the RGB encoded data.     > v2.A4

No matter what hardware configuration your actual RIPscrip software   > v2.A4
is running under, there is some low-level inherent bit-precision for  > v2.A4
each RGB color component (whether it be 2 bits each, 4, 6, 8 or more  > v2.A4
bits per color component).  With this in mind, the actual "set        > v2.A4
palette" commands need to internally convert any RGB color values to  > v2.A4
the "native" values of the target operating system's graphics         > v2.A4
environment.  The actual discussion of this goes beyond the scope of  > v2.A4
this document, however the actual conversion should be rather         > v2.A4
trivial.                                                              > v2.A4

Supporting the older 1.54 "set palette" commands that modify the      > v2.A4
lower 16 color of the drawing palette are also just as trivial.  All  > v2.A4
you need to do is map the 4 levels of RGB data to target values in    > v2.A4
the native graphics environment and you're done.  For example, if     > v2.A4
your target environment has 6 bits of precision (0-63), then your     > v2.A4
2-bit to 6-bit conversions might be something like this (a simple     > v2.A4
bit shift operation):                                                 > v2.A4

                       ╔═══════╤═══════╗                              > v2.A4
                       ║ 2-bit │ 6-bit ║                              > v2.A4
                       ╠═══════╪═══════╣                              > v2.A4
                       ║   0   │   0   ║                              > v2.A4
                       ║   1   │  16   ║                              > v2.A4
                       ║   2   │  32   ║                              > v2.A4
                       ║   3   │  48   ║                              > v2.A4
                       ╚═══════╧═══════╝                              > v2.A4

This is an overly simplistic example, and if you notice that the      > v2.A4
6-bit range goes from 0-63, not 0-48!  With this in mind, a simple    > v2.A4
bit shift operation (eg, shifting left 4 bits or multiplying by 16)   > v2.A4
in this example doesn't get the job done just right - a full          > v2.A4
intensity BLUE component (value 3 in 2-bit components) maps to a      > v2.A4


value of 48 in 6-bit components which is not a full-intensity blue).  > v2.A4
What you need to do is take the maximum target value (63 in this      > v2.A4
example), and divide it by the maximum value of the source range (3). > v2.A4
This yields a value of 21.  So, our range would evaluate to the       > v2.A4
following based on this new algorithm:                                > v2.A4

                       ╔═══════╤═══════╗
                       ║       │ (x21) ║                              > v2.A4
                       ║ 2-bit │ 6-bit ║                              > v2.A4
                       ╠═══════╪═══════╣                              > v2.A4
                       ║   0   │   0   ║                              > v2.A4
                       ║   1   │   21  ║                              > v2.A4
                       ║   2   │   42  ║                              > v2.A4
                       ║   3   │   63  ║                              > v2.A4
                       ╚═══════╧═══════╝                              > v2.A4

This gives a perfectly proportioned range where each division in the  > v2.A4
target color range is evenly spaced and covers the base (black) and   > v2.A4
the top (purest color) perfectly.                                     > v2.A4

If you considered another example of 8-bit target colors, this rule   > v2.A4
still applies - 255 / 3 = 85, which is our division as in the         > v2.A4
following 2 to 8 bit table:                                           > v2.A4

                       ╔═══════╤═══════╗
                       ║       │ (x85) ║                              > v2.A4
                       ║ 2-bit │ 8-bit ║                              > v2.A4
                       ╠═══════╪═══════╣                              > v2.A4
                       ║   0   │   0   ║                              > v2.A4
                       ║   1   │   85  ║                              > v2.A4
                       ║   2   │  170  ║                              > v2.A4
                       ║   3   │  255  ║                              > v2.A4
                       ╚═══════╧═══════╝                              > v2.A4

This same algorithm should work relatively well for any color         > v2.A4
component mapping operation from any bit precision to another where   > v2.A4
the source bit precision is less than the target's precision.  Some   > v2.A4
"fractional" component operations may need to be performed to         > v2.A4
compensate for non-integral divisions, but this shouldn't pose any    > v2.A4
problems in a real-world scenario.  In fact, this same algorithm can  > v2.A4
equally be used by the 2.0 extended "set palette" commands to map the > v2.A4
RGB color component values to the actual "bit precision" of the       > v2.A4
target graphics environment's video hardware.                         > v2.A4

If the source's bit precision is greater than the target's, then a    > v2.A4
simple right bit shift operation would accomplish the job without     > v2.A4
yielding any "uneven" divisions in the target environment's color     > v2.A4
components (eg, if you had 3-bit color values and a 2-bit target      > v2.A4
environment, shifting the values right by one bit (dividing by 2)     > v2.A4
would give you the perfect results.  Here's the translation table so  > v2.A4
that you can see this alternative algorithm at work:                  > v2.A4



                       ╔═══════╤═══════╗                              > v2.A4
                       ║       │ (÷2)  ║                              > v2.A4
                       ║ 3-bit │ 2-bit ║                              > v2.A4
                       ╠═══════╪═══════╣                              > v2.A4
                       ║   0   │   0   ║                              > v2.A4
                       ║   1   │   0   ║                              > v2.A4
                       ║   2   │   1   ║                              > v2.A4
                       ║   3   │   1   ║                              > v2.A4
                       ║   4   │   2   ║                              > v2.A4
                       ║   5   │   2   ║                              > v2.A4
                       ║   6   │   3   ║                              > v2.A4
                       ║   7   │   3   ║                              > v2.A4
                       ╚═══════╧═══════╝                              > v2.A4



╔═══════════════════════════════════════════════════════════╗
║ 2.7.1 ■ COLOR PALETTES AND HARDWARE - THE DRAWING PALETTE ║
╚═══════════════════════════════════════════════════════════╝

Now that we've discussed how to translate an RGB color from one       > v2.A4
environment to another, now let's discuss the larger picture as far   > v2.A4
as RIPscrip is concerned:  The Drawing Palette.                       > v2.A4

The Drawing Palette in RIPscrip is a table of 256 entries, where each > v2.A4
entry is a set of RGB color component values.  This table is a        > v2.A4
mechansim to "map" color codes (from 0-255) to arbitrary RGB color    > v2.A4
values.                                                               > v2.A4

It may be distinctly possible that the RIPscrip software is running   > v2.A4
in an environment that allows for an actual "color palette".  If this > v2.A4
is the case then this color lookup table will match the color palette > v2.A4
of the video hardware entry-for-entry.  Color 5 in the lookup table   > v2.A4
would correspond with color 5 in the video system's hardware color    > v2.A4
palette.  This works for environments where the color palette is      > v2.A4
"completely redefinable".  What this means is that the RIPscrip       > v2.A4
software can completely control the entire video hardware color       > v2.A4
palette.                                                              > v2.A4

It is also very possible that the RIPscrip software could be running  > v2.A4
on a video system that cannot support 256 simultaneous colors, and    > v2.A4
only has a color palette of smaller size (typically 16 colors).  In   > v2.A4
this case, the lowest 16 colors (the desktop palette) would typically > v2.A4
map one-for-one with the actual hardware color palette, although the  > v2.A4
programmer might opt to choose a more intelligent approach of color   > v2.A4
selection based on color distribution.  This rather complex issue     > v2.A4
goes beyond the scope of this discussion and it is recommended that   > v2.A4
for simplicity, the lowest 16 colors of the drawing palette be mapped > v2.A4
to the target palette..  This again, assumes that the RIPscrip        > v2.A4
software has complete control over the video color palette system and > v2.A4
can change any or all of the entries at its discretion.               > v2.A4

There are two other important situations that can occur:              > v2.A4

     1) The video hardware doesn't have a color palette (eg, its a    > v2.A4
        24-bit color system and doesn't have an actual palette), or   > v2.A4

     2) The operating system is running in an environment with only   > v2.A4
        a certain number of colors (eg, 256, 16, etc), but you        > v2.A4
        cannot redefine any or them, or you can only redefine some    > v2.A4
        of them (eg, Microsoft Windows under many configurations,     > v2.A4
        etc).                                                         > v2.A4

Situation #1 is the easiest to work with.  You don't have an actual   > v2.A4
color palette to modify, so any color values (from 0-255) simply      > v2.A4
lookup the RGB data in the color lookup table and use that raw color  > v2.A4
component data to set the color of the current drawing operation.     > v2.A4
In this manner, the lookup table is "pretending" to be a hardware     > v2.A4
video palette.  This is a situation where having the lookup table     > v2.A4
is very important.  It isn't extremely important when you have a      > v2.A4
one-to-one mapping of lookup colors to actual hardware color palette  > v2.A4
colors because the lookup table does the exact same thing as the      > v2.A4
hardware color palette.  But, in modes where you have no palette,     > v2.A4
this information becomes vital.  In practice, this local lookup table > v2.A4
aids in color translation of image files (JPEG, GIF, BMP, etc), and   > v2.A4
also aids in color translation in other situations.                   > v2.A4


Situation #2, where you don't have complete control over the target   > v2.A4
video palette is much more complicated.  For example, under           > v2.A4
Microsoft Windows, you typically cannot redefine the colors black     > v2.A4
or white.  This gives you only a sub-set of the actual palette to     > v2.A4
work with.  Also, other applications in the environment may have      > v2.A4
"locked" several entries in the color palette for their own exclusive > v2.A4
use.  This can reduce your target color palette even further.  How    > v2.A4
you handle which colors in the lookup table to "activate" (if any),   > v2.A4
and in what order you activate them is entirely up the discretion of  > v2.A4
the programmer(s) of the RIPscrip package dealing with this kind of   > v2.A4
environment.  The topic of algorithms for this situation goes         > v2.A4
completely beyond the scope of this RIPscrip specification.  Suffice  > v2.A4
it to say that the programmer would have to determine some way of     > v2.A4
mapping the lookup table to a suitable set of colors in the actual    > v2.A4
destination color environment.  If he uses strange methods of         > v2.A4
dithering (like Windows does), or other mechanisms to achieve the     > v2.A4
desired color to the user, so be it.                                  > v2.A4



╔══════════════════════════════════════════════════════════════╗
║ 2.7.2 ■ COLOR PALETTES - PALETTE MAPPING AND DIRECT RGB MODE ║
╚══════════════════════════════════════════════════════════════╝

Under RIPscrip 2.0, you have two methods of specifying color values.  > v2.A4
You have already seen how colors can be specified by a color index    > v2.A4
number into the color lookup table (from 0-255).  What RGB color that > v2.A4
actually maps to is based on the contents of that entry in the actual > v2.A4
color lookup table.  This is called "Palette mapping mode".  In       > v2.A4
palette mapping mode, most locations in RIPscrip commands that allow  > v2.A4
for color values take a color number (from 0-255) which references    > v2.A4
some RGB value in the color lookup table.                             > v2.A4

We also allow for another mode in RIPscrip, called "Direct RGB        > v2.A4
Encoding".  This mode allows you to specify actual "raw RGB" values   > v2.A4
instead of color lookup table indices.  When a direct RGB value is    > v2.A4
found, it is decoded (ie, breaking up the red, green and blue         > v2.A4
components) and is used for the actual color.  What happens at this   > v2.A4
particular moment depends on the environment that the RIPscrip        > v2.A4
software is running under.                                            > v2.A4

If the software is running in an environment with a color palette,    > v2.A4
where the hardware video palette is set to some combination of the    > v2.A4
colors used in the color lookup table, then the RGB encoded data is   > v2.A4
matched to the "closest" color in the actual target hardware video    > v2.A4
palette and that color number is actually used.  Under many           > v2.A4
situations, this color value will be the same one as used in the      > v2.A4
actual color lookup table (for situations where the software is       > v2.A4
running on a 256-color palette environment with complete control over > v2.A4
the hardware palette).  Under modes that are more limited, but where  > v2.A4
a hardware palette is still being used, the same algorithm can still  > v2.A4
be applied - but there won't be a one-to-one mapping of color lookup  > v2.A4
table values to the hardware palette.  This is unavoidable and in     > v2.A4
the case of direct RGB encoding, irrelevant.                          > v2.A4

If the software is running in an environment like 24-bit mode, then   > v2.A4
life couldn't be simpler.  Simply take the color value and use its    > v2.A4
RGB components (possibly with some color component remapping), and    > v2.A4
and activate that color in the environment.                           > v2.A4

Direct RGB encoding mode, unlike palette mapping mode, allows you to  > v2.A4
specify the bit-precision of RGB color codes used subsequently in     > v2.A4
RIPscrip code (where direct RGB colors are permitted - not all        > v2.A4
RIPscrip commands permit direct RGB encoded color codes).  This       > v2.A4
allows you to have color values with the same flexibility as "set     > v2.A4
color palette" commands, where you can specify arbitrary precisions   > v2.A4
of RGB data to potentially accomodate high-end color systems like     > v2.A4
24-bit, 16-bit, 15-bit, etc).                                         > v2.A4

By default, RIPscrip operates in palette mapping mode,  Whenever a    > v2.A4
reset operation occurs (any type of reset), palette mapping mode is   > v2.A4
once again re-enabled.  In order to go to RGB encoding mode, you must > v2.A4
explicitly specify a RIP_COLOR_MODE command, or a $COLORMODE()$ text  > v2.A4
variable to activate direct RGB encoding mode.  When you specify      > v2.A4
direct RGB encoding mode, you indicate how many bits of precisions to > v2.A4
allow for each red, green and blue component.  This value is used for > v2.A4
all three components.  For example, if you specify 8 bits of          > v2.A4
precision for each component, then combined they will amount to 24    > v2.A4
bits of RGB data (eg, 24-bit mode).  This is unlike some unusual      > v2.A4
environments on the IBM-PC where 16-bit modes (5 red, 6 green and 5   > v2.A4
blue bits) are allowed on some VGA environments.                      > v2.A4


When a direct RGB encoded color value is received, it is decoded      > v2.A4
uniformly based on the N bits of precision.  Blue is always in the    > v2.A4
lowest N bits of the RGB value, then green, then red in the highest   > v2.A4
bits.  Let's say we have an 8-bit RGB encoded value of 04140D         > v2.A4
hexadecimal.  Given this hexadecimal number, we would have the bit    > v2.A4
pattern of "000001000001010000001100".  Breaking this up into         > v2.A4
8-bit groups, we would have the following in binary, hexadecimal and  > v2.A4
decimal:                                                              > v2.A4

                       ╔══════════╤══════════╤══════════╗             > v2.A4
                       ║   RED    │  GREEN   │   BLUE   ║             > v2.A4
         ╔═════════════╬══════════╪══════════╪══════════╣             > v2.A4
         ║ binary      ║ 00000100 │ 00010100 │ 00001100 ║             > v2.A4
         ║ hexadecimal ║   04h    │    14h   │    0Dh   ║             > v2.A4
         ║ decimal     ║    4     │    20    │    12    ║             > v2.A4
         ╚═════════════╩══════════╧══════════╧══════════╝             > v2.A4

Given that we are working with 8-bit components (from 0-255), this    > v2.A4
would yield a very dark shade of cyan (approximately).                > v2.A4



╔══════════════════════════════════════════════════╗
║ 2.7.3 ■ DEFAULT RGB VALUES OF COLOR LOOKUP TABLE ║
╚══════════════════════════════════════════════════╝

When a reset command is executed, all unprotected color palette data  > v2.A4
table entries are reset to some suitable default values.  The exact   > v2.A4
RGB values used in this default color palette table are listed below. > v2.A4
In this table, we list the values with six bits of precision for      > v2.A4
red, green and blue.   This is a carefully calculated color palette   > v2.A4
designed to be of optimal use both in 16 color modes, and in 256      > v2.A4
color modes.                                                          > v2.A4

        ╔══╤══╤══╦══╤══╤══╦══╤══╤══╦══╤══╤══╦══╤══╤══╦══╤══╤══╗       > v2.A1
    Num ║ R│ G│ B║ R│ G│ B║ R│ G│ B║ R│ G│ B║ R│ G│ B║ R│ G│ B║       > v2.A1
        ╠══╪══╪══╬══╪══╪══╬══╪══╪══╬══╪══╪══╬══╪══╪══╬══╪══╪══╣       > v2.A1
      0 ║ 0│ 0│ 0║ 0│ 0│42║ 0│42│ 0║ 0│42│42║42│ 0│ 0║42│ 0│42║       > v2.A1
      6 ║42│21│ 0║42│42│42║21│21│21║21│21│63║21│63│21║21│63│63║       > v2.A1
     12 ║63│21│21║63│21│63║63│63│21║63│63│63║ 0│ 0│ 0║ 4│ 4│ 4║       > v2.A1
     18 ║ 8│ 8│ 8║13│13│13║17│17│17║21│21│21║25│25│25║29│29│29║       > v2.A1
     24 ║34│34│34║38│38│38║42│42│42║46│46│46║50│50│50║55│55│55║       > v2.A1
     30 ║59│59│59║63│63│63║ 0│ 0│ 0║ 0│ 0│21║ 0│ 0│42║ 0│ 0│63║       > v2.A1
     36 ║ 0│ 9│ 0║ 0│ 9│21║ 0│ 9│42║ 0│ 9│63║ 0│18│ 0║ 0│18│21║       > v2.A1
     42 ║ 0│18│42║ 0│18│63║ 0│27│ 0║ 0│27│21║ 0│27│42║ 0│27│63║       > v2.A1
     48 ║ 0│36│ 0║ 0│36│21║ 0│36│42║ 0│36│63║ 0│45│ 0║ 0│45│21║       > v2.A1
     54 ║ 0│45│42║ 0│45│63║ 0│54│ 0║ 0│54│21║ 0│54│42║ 0│54│63║       > v2.A1
     60 ║ 0│63│ 0║ 0│63│21║ 0│63│42║ 0│63│63║10│ 0│ 0║10│ 0│21║       > v2.A1
     66 ║10│ 0│42║10│ 0│63║10│ 9│ 0║10│ 9│21║10│ 9│42║10│ 9│63║       > v2.A1
     72 ║10│18│ 0║10│18│21║10│18│42║10│18│63║10│27│ 0║10│27│21║       > v2.A1
     78 ║10│27│42║10│27│63║10│36│ 0║10│36│21║10│36│42║10│36│63║       > v2.A1
     84 ║10│45│ 0║10│45│21║10│45│42║10│45│63║10│54│ 0║10│54│21║       > v2.A1
     90 ║10│54│42║10│54│63║10│63│ 0║10│63│21║10│63│42║10│63│63║       > v2.A1
     96 ║21│ 0│ 0║21│ 0│21║21│ 0│42║21│ 0│63║21│ 9│ 0║21│ 9│21║       > v2.A1
    102 ║21│ 9│42║21│ 9│63║21│18│ 0║21│18│21║21│18│42║21│18│63║       > v2.A1
    108 ║21│27│ 0║21│27│21║21│27│42║21│27│63║21│36│ 0║21│36│21║       > v2.A1
    114 ║21│36│42║21│36│63║21│45│ 0║21│45│21║21│45│42║21│45│63║       > v2.A1
    120 ║21│54│ 0║21│54│21║21│54│42║21│54│63║21│63│ 0║21│63│21║       > v2.A1
    126 ║21│63│42║21│63│63║31│ 0│ 0║31│ 0│21║31│ 0│42║31│ 0│63║       > v2.A1
    132 ║31│ 9│ 0║31│ 9│21║31│ 9│42║31│ 9│63║31│18│ 0║31│18│21║       > v2.A1
    138 ║31│18│42║31│18│63║31│27│ 0║31│27│21║31│27│42║31│27│63║       > v2.A1
    144 ║31│36│ 0║31│36│21║31│36│42║31│36│63║31│45│ 0║31│45│21║       > v2.A1
    150 ║31│45│42║31│45│63║31│54│ 0║31│54│21║31│54│42║31│54│63║       > v2.A1
    156 ║31│63│ 0║31│63│21║31│63│42║31│63│63║42│ 0│ 0║42│ 0│21║       > v2.A1
    162 ║42│ 0│42║42│ 0│63║42│ 9│ 0║42│ 9│21║42│ 9│42║42│ 9│63║       > v2.A1
    168 ║42│18│ 0║42│18│21║42│18│42║42│18│63║42│27│ 0║42│27│21║       > v2.A1
    174 ║42│27│42║42│27│63║42│36│ 0║42│36│21║42│36│42║42│36│63║       > v2.A1
    180 ║42│45│ 0║42│45│21║42│45│42║42│45│63║42│54│ 0║42│54│21║       > v2.A1
    186 ║42│54│42║42│54│63║42│63│ 0║42│63│21║42│63│42║42│63│63║       > v2.A1
    192 ║52│ 0│ 0║52│ 0│21║52│ 0│42║52│ 0│63║52│ 9│ 0║52│ 9│21║       > v2.A1
    198 ║52│ 9│42║52│ 9│63║52│18│ 0║52│18│21║52│18│42║52│18│63║       > v2.A1
    204 ║52│27│ 0║52│27│21║52│27│42║52│27│63║52│36│ 0║52│36│21║       > v2.A1
    210 ║52│36│42║52│36│63║52│45│ 0║52│45│21║52│45│42║52│45│63║       > v2.A1
    216 ║52│54│ 0║52│54│21║52│54│42║52│54│63║52│63│ 0║52│63│21║       > v2.A1
    222 ║52│63│42║52│63│63║63│ 0│ 0║63│ 0│21║63│ 0│42║63│ 0│63║       > v2.A1
    228 ║63│ 9│ 0║63│ 9│21║63│ 9│42║63│ 9│63║63│18│ 0║63│18│21║       > v2.A1
    234 ║63│18│42║63│18│63║63│27│ 0║63│27│21║63│27│42║63│27│63║       > v2.A1
    240 ║63│36│ 0║63│36│21║63│36│42║63│36│63║63│45│ 0║63│45│21║       > v2.A1
    246 ║63│45│42║63│45│63║63│54│ 0║63│54│21║63│54│42║63│54│63║       > v2.A1
    252 ║63│63│ 0║63│63│21║63│63│42║63│63│63║░░│░░│░░║░░│░░│░░║       > v2.A1
        ╚══╧══╧══╩══╧══╧══╩══╧══╧══╩══╧══╧══╩══╧══╧══╩══╧══╧══╝       > v2.A1


The first 16 entries in the above color table correspond to the       > v2.A1
default color palette used in v1.xx of RIPscrip and corresponds       > v2.A1
directly to the color palette used for 16 color ANSI text.  The next  > v2.A1
16 colors in the color table above is a 16 level gray-scale used for  > v2.A1
gray-scale image output and to provide a basic spectrum of grays.     > v2.A1

The remaining 224 entries is a "uniform distribution" of RGB colors.  > v2.A1
The actual organization of the colors is mathematically based such    > v2.A1
that an arbitrary RGB color value can be mapped to a color value in   > v2.A1
the default palette with a simple calculation (instead of searching   > v2.A1
through the entire palette for the closest entry).  This block tries  > v2.A1
to cover as many colors in the color spectrum as possible.            > v2.A1

There are four levels of Blue, eight levels of green and seven        > v2.A1
levels of red.  Each block is organized with Blue the color that      > v2.A1
changes every entry, green the next most changing, and red the        > v2.A1
least frequently changing.  If you have a RED value from 0-6, a       > v2.A1
GREEN value from 0-7 and a BLUE value from 0-3, you can easily        > v2.A1
calculate the correct palette index entry with the following          > v2.A1
equation:                                                             > v2.A1

            INDEX = 32 + BLUE + GREEN*4 + RED*32                      > v2.A1

Or in C with bit-shifting, you could do it like this:                 > v2.A1

            INDEX = 32 + BLUE + GREEN<<2 + RED<<5                     > v2.A1

The main reason for choosing this color palette was to facilitate the > v2.A1
ability to display many color images onto the screen at the same time > v2.A1
in 256 color mode without having to alter the color palette for each  > v2.A1
image.  The color representation may not be 100% exact, but it would  > v2.A1
be close enough with dithering to accurately represent the original   > v2.A1
image.                                                                > v2.A1

The exact determination of this color palette was very carefully      > v2.A4
chosen.  The lowest 16 colors, which happen to default to the basic   > v2.A4
colors of ANSI color codes (universally used throughout the computer  > v2.A4
world seemingly), are a good sub-set of colors for basic 16 color     > v2.A4
operations.  The next 16 colors are defined as a dedicated gray-scale > v2.A4
color palete (only of use in 256 color modes), and gives a very good  > v2.A4
breakdown of the gray-scale monotone color palette.  The remaining    > v2.A4
224 entries are broken down mathematically (as you've seen above)     > v2.A4
with 7 levels of red, 8 levels of green and 4 levels of blue.  This   > v2.A4
seemingly odd configuration of color distrubution was very            > v2.A4
scientifcally chosen.                                                 > v2.A4

Extensive experimental research has determined that the human eye is  > v2.A4
more susceptible to particular "hues" of light than others.           > v2.A4
Specifcally, the human eye is most susceptible to subtle changes in   > v2.A4
the shade of green than any other color.  Next comes red, then        > v2.A4
finally blue at the very lowest end of the perceptivity scale.  If    > v2.A4
you recall, red is at the lower end of the light spectrum (eg, near   > v2.A4
infrared), and blue is at the upper end of the spectrum (near ultra-  > v2.A4
violet).  Green is in the middle.  This tells us that our eye is      > v2.A4
most responsive to light in the middle-to-lower bands of the color    > v2.A4
spectrum.  After scientific analysis, our eye was determined to be    > v2.A4
responsive to the following levels of each color band (comparitively  > v2.A4
based on an 8 level scale, 1 being lowest):                           > v2.A4



                           8 - green                                  > v2.A4
                           7 - red                                    > v2.A4
                           4 - blue                                   > v2.A4

Taking this information into account, we constructed a default        > v2.A4
palette which reflected the best distribution of color that the human > v2.A4
eye can perceive.  By no means is it perfectly suited for all         > v2.A4
environments, but it is a "best case" situation for most images and   > v2.A4
environments.  As you can undoubtedly guess, a photograph with a lot  > v2.A4
of blues and violets would be significantly degraded in quality in    > v2.A4
this color environment, but many typical images where a broad range   > v2.A4
of colors is used works very well, and when dithering is used, the    > v2.A4
situation improves even more.                                         > v2.A4



╔═════════════════════════════════════╗
║ 2.8 ■ AUDIO (SOUND & MUSIC) FORMATS ║
╚═════════════════════════════════════╝

RIPscrip 2.0 permits the support of digitized audio to be played in   > v2.A4
the background whild graphics and other operations are being          > v2.A4
performed.  This includes playing sounds while graphical commands are > v2.A4
being received from the host (without interruption).                  > v2.A4

The format of audio data used by RIPscrip 2.0 is formally defined as  > v2.A4
straight audio data in the Microsoft WAVE file format.  When dealing  > v2.A4
with host systems and downloading digitized audio data, or being      > v2.A4
told to play back audio data, RIPscrip will assume that you are       > v2.A4
working with WAVE files.  For example, you might be told to playback  > v2.A4
a file named SOUND.WAV.  If you are not internally supporting the     > v2.A4
actual WAVE format, but some other format, then you need to translate > v2.A4
the name of the file to the correct name in your environment (if      > v2.A4
necessary) and perform the playback.                                  > v2.A4

When dealing with the RIP_FILE_QUERY command, you need to be careful  > v2.A4
if you're not dealing with true WAVE files.  The RIP_FILE_QUERY       > v2.A4
command is used to "detect" if a particular file is present on the    > v2.A4
target system and if so, if it is the right date/time and file size   > v2.A4
as the file on the host.  The file on the host will be in WAVE format > v2.A4
so if you're translating the files as they're received, you need to   > v2.A4
translate the RIP_FILE_QUERY information returned to the host so that > v2.A4
it thinks that the file you have on your local hard disk is actually  > v2.A4
a WAVE file (ie, translate the file size to a WAVE equivalent).  If   > v2.A4
the sizes and, or the time/date don't match, the host could download  > v2.A4
a new file to you (via the RIP_ENTER_BLOCK_MODE command) thinking     > v2.A4
that your's is out of date.                                           > v2.A4

If you receive a WAVE file via the RIP_ENTER_BLOCK_MODE command, or   > v2.A4
by some other meanss, and you're dealing with anther digitized audio  > v2.A4
file format, it is up to you to translate that WAVE file to your      > v2.A4
destination format.  Consequently, if you are requested to send a     > v2.A4
WAVE file to the host system, and the host system is requesting a     > v2.A4
.WAV file, then you must translate your file to WAVE format before    > v2.A4
sending it.                                                           > v2.A4

A Microsoft WAVE file is actually a normal "Pulse Code Modulation"    > v2.A4
digitized audio file stored with a bit of header information to       > v2.A4
identify whether it is stereo, 16-bit, 8-bit, etc, and other pieces   > v2.A4
of critical information for the decoding of the data.  See the        > v2.A4
"Microsoft Windows Programmer's Reference Guide" for more specific    > v2.A4
information on the internal format of WAVE files.                     > v2.A4



╔═════════════════════════════════════════════════════╗
║ 2.9 ■ TEXT WINDOWS AND TERMINAL EMULATION PROTOCOLS ║
╚═════════════════════════════════════════════════════╝

     [ BEGIN REWORD ]

     Discuss text windows and terminal emulations here

     [ END REWORD ]



╔════════════════════════════════════════════════════════╗
║ 2.10 ■ VIEWPORTS AND TEXT WINDOWS - OVERLAPPING ISSUES ║
╚════════════════════════════════════════════════════════╝

Since there are multiple text windows and ports (with their           > v2.A3
viewports) allowed in the RIPscrip specification, some elaboration    > v2.A3
needs to be made on what happens if any overlap each other.  Very     > v2.A1
simple, they do what they have always done - draw text, or draw       > v2.A1
graphics.  For example, if a viewport overlaps a text window and you  > v2.A1
draw some graphics (say a circle) over the top of some text in a text > v2.A1
window, and the text window subsequently scrolls, all or part of the  > v2.A1
circle could scroll with it!  Now, of course, from the viewport's     > v2.A1
standpoint, the graphics are no longer what you originally sent to    > v2.A1
the viewport, but that doesn't matter - you don't preserve any of the > v2.A1
commands you used to create the graphics - you simply draw the        > v2.A1
graphics and that's it.  So with this in mind, even if multiple       > v2.A1
viewports overlap each other it doesn't matter because the final      > v2.A1
result is what's on the screen - doing things in one viewport might   > v2.A1
do some overlapping graphics in another viewport but that is alright. > v2.A1

If a text window overlaps another text window, the same thing         > v2.A1
happens.  To a RIPscrip terminal, text is simply just a piece of      > v2.A1
graphical information that is being placed on the screen in a         > v2.A1
formatted fashion.  If two text windows overlap and text is placed on > v2.A1
an area that overlap the other window, then you will be drawing       > v2.A1
graphics (essentially) on top of another text window.  The same thing > v2.A1
as the circle example above would happen if that text window          > v2.A1
scrolled.                                                             > v2.A1



╔════════════════════════════════════════╗
║ 2.11 ■ MISCELLANEOUS NOTES/INFORMATION ║
╚════════════════════════════════════════╝

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

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

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

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



╔══════════════════════════════════╗
║ 3 ■ RIPscrip PROTOCOL DEFINITION ║
╚══════════════════════════════════╝

The following sub-sections define the actual structure of the         > v2.A4
RIPscrip graphical language.  The topic of Host Commands and Text     > v2.A4
Variables is covered in a section devoted specifically to that topic. > v2.A4



╔═════════════════════════════════════╗
║ 3.1 ■ ANSI SEQUENCES (AUTO-SENSING) ║
╚═════════════════════════════════════╝

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

ESC[!     Query RIPscrip version number.  RIPterm will respond with   > v1.54
          RIPSCRIPxxyyvs where "xx" is equal to the major version     > v1.54
          number (zero padded), "yy" is equal to the minor version    > v1.54
          number (zero padded), "v" is the vendor code of the         > v1.54
          terminal program (see below), and "s" is the vendor's       > v1.54
          sub-version code for their software.  For v1.54, the        > v1.54
          returned sequence for RIPterm (Vendor Code "1") would be    > v1.54
          RIPSCRIP015410.  Another example, v1.23 with a Vendor Code  > v1.54
          of "2" and a sub-revision code of "5" would return          > v1.54
          RIPSCRIP012325.                                             > v1.54

          Valid Vendor Codes are:                                     > v1.54

             ╔══════╤════════════════════════════════════════════╗    > v1.54
             ║ CODE │ VENDOR                                     ║    > v1.54
             ╠══════╪════════════════════════════════════════════╣    > v1.54
             ║   0  │ Generic RIPscrip terminal (vendor unknown) ║    > v1.54
             ║   1  │ RIPterm (from TeleGrafix Communications)   ║    > v1.54
             ║   2  │ Qmodem Pro (from Mustang Software, Inc)    ║    > v1.54
             ║   3  │ deltaComm Development (Telix)              ║    > v2.A1
             ║   4  │ Qmodem Pro for Windows (Mustang Software)  ║    > v2.A1
             ╚══════╧════════════════════════════════════════════╝    > v1.54

          This ANSI sequence is often used for "Auto-Sensing" if a    > v1.54
          RIPscrip terminal exists on the remote end of the           > v1.54
          connection.  If a non-RIPscrip terminal receives this       > v1.54
          ANSI sequence, it will ignore it.                           > v1.54

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

                 You still use this escape sequences to detect        > v2.A3
                 RIPscrip capability, but to determine the            > v2.A3
                 specific terminal program or manufacturer, use       > v2.A3
                 the $TERMINFO()$ text variable.  To determine        > v2.A4
                 specific capabilities of the terminal, use the       > v2.A3
                 $IFS()$ text variable (Is Function Supported).       > v2.A3
                 To determine the current language that the           > v2.A3
                 terminal is running in, use the $LANGUAGE$           > v2.A3
                 text variable (see the text variable section         > v2.A3
                 later for more details).                             > v2.A3

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.



╔════════════════════════════════════════════════════════╗
║ 3.2 ■ RIPscrip PROTOCOL - SYNTAX AND GENERAL STRUCTURE ║
╚════════════════════════════════════════════════════════╝

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

The basic syntax rules are as follows:

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

2.  A RIPscrip command line begins with an exclamation mark "!"
    (ASCII code 33 decimal).                                          > v2.A3

3.  Every RIPscrip command is preceded by the universal RIPscrip
    delimiter, vertical-bar "|" (ASCII code 124 decimal).             > v2.A3

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

5.  RIPscrip commands or command lines may be split across multiple
    lines with a backslash "\" (ASCII code 92 decimal) just before    > v2.A3
    each split.  This helps RIPscrip commands conform to right
    margins and escape word wrapping.

          An example:

               !|c02|L02030405|P0901020102010201020102\
               0102010201020102

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

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



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

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

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

9.  Every RIPscrip command includes a command type character.  In
    Level-0 commands, this character immediately follows the vertical
    bar.  At all other levels, it follows the level digits.  The
    command type character may be any of the following characters:    > v2.A0

        ABCDEFGHIJKLMNOPQRSTUVWXYZ                                    > v2.A0
        abcdefghijklmnopqrstuvwxyz                                    > v2.A0
        @#$&*()[]{}<>:;'",.?-_=+!                                     > v2.A0

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

    If a RIPscrip command does not have a string parameter, but       > v2.A3
    does have numeric parameters, the last parameter may be shortened > v2.A3
    to get a bit more efficiency out of it.  If the last parameter    > v2.A3
    is more than one digit long and the left-most digits are zeros,   > v2.A3
    they may be omitted.  At least one digit must remain though after > v2.A3
    all of the shortening is done (eg, "0001" can be shortened to "1" > v2.A3
    but "0000" cannot be shortened to "", it can only be shortened to > v2.A3
    "0").                                                             > v2.A3

    For example, the RIP_COLOR command, used to set the current       > v2.A3
    drawing color, requires one parameter - a color number.  If we    > v2.A3
    were going to set color 1 (usually dark blue), then the command   > v2.A3
    would appear formally as follows:                                 > v2.A3

                    !|c01                                             > v2.A3

    Under this shortening clause, you could omit the "0" and make     > v2.A3
    the command appear like this:                                     > v2.A3

                    !|c1                                              > v2.A3

    This allows you to shave one byte off of the command.  If you     > v2.A3
    were trying to set color number zero (normally black), then you   > v2.A3
    could still shorten the parameter, but you still have to leave    > v2.A3
    at least one digit there (0), so the command would appear like    > v2.A3
    this:                                                             > v2.A3


                    !|c0                                              > v2.A3


    There is an additional optimization that can be used for commands > v2.A2
    that have no string parameter, and have a reserved parameter as   > v2.A2
    the LAST parameter for that command.  In this case, the reserved  > v2.A2
    parameter may be omitted completely, and the value should be      > v2.A2
    assumed to be zero (`0').  Please take note that the previous     > v2.A2
    paragraphs still apply!  You can omit the reserved parameter AND  > v2.A2
    shorten the last transmitted parameter so as to squeeze out as    > v2.A2
    many unnecessary characters from the command as possible.         > v2.A2

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

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

11. An exclamation mark (!) or vertical bar (|) character can appear
    in a RIPscrip text parameter by preceding it with a backslash(\).
    This is known as "quoting" a special character.  A literal        > v2.A3
    backslash is represented with a double-backslash (\\).  Also, in  > v2.A3
    some situations you need to quote specific characters so that     > v2.A3
    they are not misinterpretted.  For example, in a button host      > v2.A3
    string, the characters [, ], (, and $ are used as special host    > v2.A3
    command characters and will need to be quoted (eg, \[, \],        > v2.A3
    \( and \$ respectively).  See rule #14 below for more details     > v2.A3
    on quoting these special sequences.

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] - ASCII character 1) character, or Ctrl-B         > v2.A3
    (STX - ASCII character 2) character.  Since 99.9% of all BBS' do  > v2.A3
    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.

    Let's take an example, where we have a piece of raw text and      > v2.A3
    then a RIPscrip command immediately following the text before     > v2.A3
    the carriage return (in this example <STX> stands for the STX     > v2.A3
    character):                                                       > v2.A3

          This is raw text<STX>|c01|@1010hello world                  > v2.A3

    In the above example, the text "This is raw text" would be        > v2.A3
    sent to the active text window, then the RIPscrip sequences       > v2.A3
    would be processed - set the color to blue (01), then print       > v2.A3
    the text "hello world" on the screen at (10,10) in meganums       > v2.A3
    or (36,36) in decimal.                                            > v2.A3


13. If the last couple of bytes on a RIPscrip text line are           > v1.54
    backslashes, special care must be taken to make sure that they    > v1.54
    are not interpreted as a line-continuation.  If a literal         > v1.54
    backslash is desired as the last position on the line, it must    > v1.54
    be specified as a double-backslash (eg, "\\").  If a line-        > v1.54


    continuation is used then there would have to be three            > v1.54
    backslashes used on the line as in the following example:         > v1.54

        !|@2233this is a text line with a literal \\\                 > v1.54
        used in the message                                           > v1.54

    This would text output at (22,33) [meganum] the message:          > v1.54

       this is a text line with a literal \used in the message        > v1.54

14. Some character sequences in text parameter strings can be         > v2.A1
    misinterpreted as RIPscrip command sequences (eg, $, <>,          > v2.A1
    ((, )), [, ], [], etc).  To avoid syntax confusion these          > v2.A1
    sequences can be "escaped" to indicate that they are actually     > v2.A1
    literal sequences, not to be confused with a RIPscrip command     > v2.A1
    sequence identifier.  For example, the sequence:                  > v2.A1

          $Name$                                                      > v2.A1

    would normally be interpreted as a RIPscrip text variable that    > v2.A1
    requires the user's response.  If however, you wanted this        > v2.A1
    sequence to be interpretted as literal text, you should perform   > v2.A1
    the following escape sequences:                                   > v2.A1

          \$Name\$                                                    > v2.A1

    This makes it so a RIPscrip terminal doesn't misinterpret the     > v2.A1
    dollar signs as text variable delimiters.                         > v2.A1

15. Extraneous information.  If too much data is encountered for a    > v2.A1
    particular RIPscrip command, or too little information is found   > v2.A1
    (aside from a short last parameter) then the command is           > v2.A1
    considered "hopelessly corrupted" and discarded.  The RIPscrip    > v2.A1
    parser should synchronize to the next vertical bar delimiter      > v2.A1
    to begin the next command.                                        > v2.A1



╔══════════════════════════════════════════════╗
║ 3.3 ■ DESCRIPTION OF RIPscrip COMMAND LEVELS ║
╚══════════════════════════════════════════════╝

As previously described, RIPscrip is composed of ten different levels > v2.A1
of commands.  The distribution of commands over different levels is   > v2.A1
done in a rather organized fashion based on command type.  Each level > v2.A1
of command in general, is progressively higher level in concept.  For > v2.A1
example, level 0 commands are the most basic building blocks of       > v2.A1
RIPscrip (eg, graphical primitives, protocol setup, etc).  Level one  > v2.A1
commands are simple user interface objects.  Level 2 commands are     > v2.A1
higher level still in that they deal with context swapping issues.    > v2.A1
At the highest level, level-9, we deal with binary transfer modes     > v2.A1
like file transfer protocols, etc.  A more formal definition of the   > v2.A1
currently used levels are:                                            > v2.A1

   ╔═══════╤══════════════════════════════════════════════════════╗   > v2.A1
   ║ Level │ Description                                          ║   > v2.A1
   ╠═══════╪══════════════════════════════════════════════════════╣   > v2.A1
   ║   0   │ Lowest-level RIPscrip primitives.  Simple graphical  ║   > v2.A1
   ║       │ drawing primitives, low-level RIPscrip protocol      ║   > v2.A1
   ║       │ mode settings, etc.                                  ║   > v2.A1
   ╟───────┼──────────────────────────────────────────────────────╢   > v2.A1
   ║   1   │ Simple user interface objects (buttons, mouse        ║   > v2.A1
   ║       │ fields, clipboard slots, formatted text regions).    ║   > v2.A2
   ║       │ This level consolidates one or more simple building  ║   > v2.A2
   ║       │ blocks from level 0 and also introduces more         ║   > v2.A1
   ║       │ abstract user interface objects (eg, mouse fields).  ║   > v2.A1
   ╟───────┼──────────────────────────────────────────────────────╢   > v2.A1
   ║   2   │ Basic context switching information (switching       ║   > v2.A1
   ║       │ styles, and other window or context senstive         ║   > v2.A1
   ║       │ commands.                                            ║   > v2.A1
   ╟───────┼──────────────────────────────────────────────────────╢   > v2.A1
   ║   3   │ Basic time-related commands (baud rate emulation     ║   > v2.A1
   ║       │ and delay commands).                                 ║   > v2.A1
   ╟───────┼──────────────────────────────────────────────────────╢   > v2.A1
   ║   4   │ Open for future development                          ║   > v2.A1
   ╟───────┼──────────────────────────────────────────────────────╢   > v2.A1
   ║   5   │ Open for future development                          ║   > v2.A1
   ╟───────┼──────────────────────────────────────────────────────╢   > v2.A1
   ║   6   │ Open for future development                          ║   > v2.A1
   ╟───────┼──────────────────────────────────────────────────────╢   > v2.A1
   ║   7   │ Open for future development                          ║   > v2.A1
   ╟───────┼──────────────────────────────────────────────────────╢   > v2.A1
   ║   8   │ Open for future development                          ║   > v2.A1
   ╟───────┼──────────────────────────────────────────────────────╢   > v2.A1
   ║   9   │ Binary related data transfer functions (ie, block    ║   > v2.A1
   ║       │ protocol modes, UU-Encoding, etc).                   ║   > v2.A1
   ╚═══════╧══════════════════════════════════════════════════════╝   > v2.A1



╔══════════════════════════════════╗
║ 3.4 ■ RIPscrip COMMAND REFERENCE ║
╚══════════════════════════════════╝

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

    SYMBOL - the symbolic constant that is referenced in RIPscrip     > v2.A3
             documents.  This is the universal name for the command.  > v2.A3

  FUNCTION - A short description of the command.

     LEVEL - The Command Level.  Sub-levels (if any) are              > v2.A3
             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 character identifying the command

 ARGUMENTS - The arguments or parameters for the command.
             Commands that do not require any parameters
             after the command type character are shown
             here as "<none>".  Each parameter is shown in
             the order it appears in the command, and is
             represented by a name.  If a parameter is
             numeric, it is followed by a width specifier
             indicating how many meganum or ultranum digits           > v2.A2
             the parameter consists of (e.g., ":2" means a
             2-digit number, or a value between 0 and                 > v2.A2
             1295 for meganums, or 0 and 4095 for ultranums).         > v2.A2
             If a parameter does not have a width specifier,
             it is by default a text parameter, and should be
             the last parameter of the command.                       > v2.A2

             If a command is variable length (see POLYGON),
             then it will appear with an ellipe (...),                > v2.A2
             meaning that the command repeats the specific            > v2.A2
             parameters a variable number of times.                   > v2.A2

             If the parameter is a variable-width coordinate          > v2.A2
             that can be set by the RIP_SET_COORDINATE_SIZE, or       > v2.A3
             via the RIP_HEADER commands, then the parameter          > v2.A3
             will be followed by a coordinate specifier (e.g.,        > v2.A2
             ":XY" means that the parameter is a variable-width       > v2.A2
             coordinate).                                             > v2.A2

             If the parameter is a color parameter whose format is    > v2.A3
             determined by the RIP_SET_COLOR_MODE command, (ie, the   > v2.A3
             parameter switches between "color mapping mode" or       > v2.A3
             "direct RGB encoding" mode), then a color mode           > v2.A3
             specifier will come after the parameter name (e.g.,      > v2.A3
             ":CM" indicates this parameter uses the current color    > v2.A3
             mode).                                                   > v2.A3

             Some commands do not allow color parameters to switch    > v2.A3
             modes based on RIP_SET_COLOR_MODE.  These exceptional    > v2.A3
             commands document these exceptions and the :CM           > v2.A3
             specifier will not be present.                           > v2.A3



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

   EXAMPLE - An actual example of the RIPscrip command.

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

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

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

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 STYLE - If YES, then this command uses or affects the            > v2.A3
             current Font Style/size/orientation.                     > v2.A3

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

USES PORT  - If YES, then this command adheres to, is affected by,    > v2.A3
             or modifies the definition of a port.                    > v2.A3

BASE MATH  - Indicates which base math this command responds to.      > v2.A2
             The possible settings are N/A (does not apply),          > v2.A2
             Meganums (uses meganums ONLY), Ultranums (uses Ultranums > v2.A2
             ONLY), and Current (uses current base math setting as    > v2.A2
             set by either RIP_HEADER or RIP_SET_BASE_MATH).          > v2.A2



╔═══════════════════════════════════╗
║ 3.4.1 ■ LEVEL-0 RIPscrip COMMANDS ║
╚═══════════════════════════════════╝

Level-0 commands are the graphical building blocks of RIPscrip.  They > v2.A4
embody all of the simple primitive commands for actually drawing      > v2.A4
simple graphics like lines, circles, normal graphical text.           > v2.A4

This level also contains all of the commands necessary to the basic   > v2.A4
setup and operation of RIPscrip (eg, base math, color modes, etc).    > v2.A4



┌───────────────────┐
│ 3.4.1.1 ■ RIP_ARC │
└───────────────────┘

       Function: Draw circular arc in current color/line thickness
          Level: 0
        Command: A
      Arguments: x:XY y:XY start_ang:2 end_ang:2 radius:XY            > v2.A2
         Format: !|A <x> <y> <start_ang> <end_ang> <radius>
        Example: !|A1E18003G0T                                        > v2.A2
Uses Draw Color: YES
Uses Back Color: YES                                                  > v2.A1
Uses Line Style: YES                                                  > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: YES                                                  > v2.A1
Uses Font Style: NO
  Uses Viewport: YES                                                  > v1.54
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

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

                          90°
                           │
                   180°────┼────0°
                           │
                          270°

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

If both angles are equal, nothing is drawn.

The radius is considered to be in the horizontal direction for the    > v2.A3
purpose of aspect ratio calculations.                                 > v2.A3

Both angles can be greater than 360 degrees.  The starting angle      > v2.A3
must be greater or equal to the ending angle.                         > v2.A3



┌──────────────────────────┐
│ 3.4.1.2 ■ RIP_BACK_COLOR │
└──────────────────────────┘

       Function: Set background Drawing Color for graphics            > v2.A1
          Level: 0                                                    > v2.A1
        Command: k                                                    > v2.A1
      Arguments: color:CM                                             > v2.A2
         Format: !|k <color>                                          > v2.A1
        Example: !|k0004                                              > v2.A2
Uses Draw Color: NO                                                   > v2.A1
Uses Back Color: YES                                                  > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO                                                   > v2.A1
Uses Font Style: NO                                                   > v2.A1
  Uses Viewport: NO                                                   > v2.A1
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

This command alters the setting of the background pen drawing color.  > v2.A1
This color is used for fill operations for the background pixels of   > v2.A1
the fill as well as some erase functions.  The color of the           > v2.A3
foreground pixels of the fill pattern are specified with a            > v2.A1
RIP_FILL_STYLE and RIP_FILL_PATTERN command.  Upon a                  > v2.A1
RIP_RESET_WINDOWS, the background color is automatically set to black > v2.A1
and remains that way unless overidden by a RIP_BACK_COLOR command.    > v2.A1

The background color can also affect the way line patterns/styles     > v2.A1
appear on the screen.  Normally a line pattern is a sequence of on    > v2.A1
and off pixels where the on pixels are drawn in the normal RIPscrip   > v2.A1
foreground drawing color as set by the RIP_COLOR command.  The other  > v2.A1
pixels (the off pixels) are normally not drawn at all (ie,            > v2.A3
transparent).  When you use the RIP_LINE_STYLE command, you can       > v2.A3
specify that these off pixels are to be drawn in the current          > v2.A3
background color (set with this command).  See the RIP_LINE_STYLE for > v2.A1
exact syntax on using this mode.                                      > v2.A1

See the RIP_COLOR command for an exact description of the <color>     > v2.A1
parameter used in this command (both Color Palette mode and Direct    > v2.A1
RGB color mode are supported).                                        > v2.A1



┌───────────────────┐
│ 3.4.1.3 ■ RIP_BAR │
└───────────────────┘

       Function: Draw filled rectangle using fill style/no border     > v2.A2
          Level: 0
        Command: B
      Arguments: x0:XY y0:XY x1:XY y1:XY                              > v2.A2
         Format: !|B <x0> <y0> <x1> <y1>
        Example: !|B00010A0E
Uses Draw Color: NO
Uses Back Color: YES                                                  > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: YES                                                  > v2.A2
Uses Write Mode: YES                                                  > v2.A1
Uses Font Style: NO
  Uses Viewport: YES                                                  > v1.54
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

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

  NOTE: If the borders are enabled, then this command will still draw > v2.A3
        a rectangle with no border.  This is the only RIPscrip        > v2.A3
        command that ignores the border option.                       > v2.A3

This command also does not adhere to the resolution independent       > v2.A3
method of performing fills.  In other words, the fill actually goes   > v2.A3
to the very lower-left corner of the rectangle.  In this manner,      > v2.A3
this command is not truly resolution independent.  If you want to     > v2.A3
draw a resolution independent filled rectangle, use the               > v2.A3
RIP_FILLED_RECTANGLE with borders disabled.                           > v2.A3

Before the rectangle is actually drawn, the (x0,y0) and (x1,y1)       > v2.A3
coordinates are "normalized".  This means that they are adjusted so   > v2.A3
that they specify the upper-left and lower-right coordinates          > v2.A3
respectively.  For example, if the parameters are received in the     > v2.A3
order of (50,25) and (25,75) - upper-right and lower-left             > v2.A3
respectively - they would be reorganized to be (25,25) and (50,75)    > v2.A3
before the rectangle is actually drawn.                               > v2.A3



┌──────────────────────┐
│ 3.4.1.4 ■ RIP_BEZIER │
└──────────────────────┘

       Function: Draw a bezier curve
          Level: 0
        Command: Z
      Arguments: x1:XY y1:XY x2:XY y2:XY x3:XY y3:XY                  > v2.A2
                 x4:XY y4:XY cnt:2                                    > v2.A2
         Format: !|Z <x1> <y1> <x2> <y2> <x3> <y3> <x4> <y4> <cnt>
        Example: !|Z0A0B0C0D0E0F0G0H1G
Uses Draw Color: YES
Uses Back Color: YES                                                  > v2.A1
Uses Line Style: YES                                                  > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: YES
Uses Font Style: NO
  Uses Viewport: YES                                                  > v1.54
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

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 (usually), but points 1 and 4 are.          > v2.A3

                          X2

                         ▄▀▀▀▄
                       ▄▀     ▀▀▄▄
                      █           ▀▄            X4
                     █              ▀▄          █
                   X1                 █       ▄▀
                                       █    ▄▀
                                        ▀▄▄▀

                                         X3

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.

The entire bezier curve is drawn using the current line pattern,      > v2.A3
thickness and write mode.                                             > v2.A3

The actual bezier curve can be described mathematically by the        > v2.A3
following parametric equations:                                       > v2.A3

   X = X1*(1-t)^3 + X2*3*t*(t-1)^2 + X3*3*t^2*(1-t) + X*4*t^3         > v2.A3
   Y = Y1*(1-t)^3 + Y2*3*t*(t-1)^2 + Y3*3*t^2*(1-t) + Y*4*t^3         > v2.A3

These are the normal equational forms of the weighted sum B-Spline    > v2.A3
function using four control points instead of directional vectors.    > v2.A3
The variable T is varied from 0.0 through 1.0 over some increment to  > v2.A3
achieve the total curve.                                              > v2.A3


┌──────────────────────┐
│ 3.4.1.5 ■ RIP_CIRCLE │
└──────────────────────┘

       Function: Draw circle in current color and line thickness
          Level: 0
        Command: C
      Arguments: x_center:XY y_center:XY radius:XY                    > v2.A2
         Format: !|C <x_center> <y_center> <radius>
        Example: !|C1E180M
Uses Draw Color: YES
Uses Back Color: YES                                                  > v2.A1
Uses Line Style: YES                                                  > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: YES                                                  > v2.A1
Uses Font Style: NO
  Uses Viewport: YES                                                  > v1.54
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

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 radius is considered to be in the horizontal direction for the    > v2.A3
purpose of aspect ratio calculations.                                 > v2.A3



┌─────────────────────┐
│ 3.4.1.6 ■ RIP_COLOR │
└─────────────────────┘

       Function: Set current Drawing Color for graphics
          Level: 0
        Command: c
      Arguments: color:CM                                             > v2.A2
         Format: !|c <color>
        Example: !|cA
Uses Draw Color: YES
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO
Uses Font Style: NO
  Uses Viewport: NO                                                   > v1.54
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

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 when borders are enabled.  (The interior of the ellipse would > v2.A3
be drawn according to the most recent RIP_FILL_STYLE command).

The <color> parameter of this command serves two purposes depending   > v2.A0
on what Color Mode is currently set.  The default mode, Color Map     > v2.A0
mode, signifies that the color parameter of this command will use the > v2.A0
parameter as an index into the 256 color Drawing Palette color        > v2.A0
mapping table.  In this mode, this parameter will use the current     > v2.A0
Base Math set by the global RIP_SET_BASE_MATH command.                > v2.A0

In Direct RGB Color Mode, the color parameter will be encoded in      > v2.A0
UltraNums (regardless of the current Base Math setting).  The total   > v2.A0
number of digits used will vary depending on the number of bits per   > v2.A0
color component (R, G and B).  The following table will provide a     > v2.A0
breakdown of bits vs. total number of UltraNum digits used for Direct > v2.A0
RGB Color codes:                                                      > v2.A0

     Bits  Total Digits                                               > v2.A0
     ──────────────────                                               > v2.A0
       1        1                                                     > v2.A0
       2        1                                                     > v2.A0
       3        2                                                     > v2.A0
       4        2                                                     > v2.A0
       5        3                                                     > v2.A0
       6        3                                                     > v2.A0
       7        4                                                     > v2.A0
       8        4                                                     > v2.A0

These numeric values will be an encoded RGB value allowing you to set > v2.A0
arbitrary RGB colors directly with the Set Color commands.  If the    > v2.A0
RGB color is not permissable, the closest match from the Color        > v2.A0
palette table will be located and used.  The number of bits of        > v2.A3
precision used in the encoded RGB value will be determined by the     > v2.A0
RIP_SET_COLOR_MODE command.                                           > v2.A0


When Direct RGB Colors Codes are used, the bits for each Red, Green   > v2.A0
and Blue are encoded as tightly as possible to ensure no wasted       > v2.A0
space.  For example, if 6 bits were used for R, G and B, you would    > v2.A0
have the following layout in binary form:                             > v2.A0

     rrrrrr gggggg bbbbbb                                             > v2.A0

where each of "r", "g" and "b" could be individual ones or zeros.     > v2.A0
This binary representation of the color code is then converted to     > v2.A0
UltraNum using the proper number of digits from the preceding table.  > v2.A0
For example, if you had binary values:                                > v2.A0

       RED:  011011                                                   > v2.A0
     GREEN:  001001                                                   > v2.A0
      BLUE:  100100                                                   > v2.A0

You would have the following binary number:                           > v2.A0

     011011 001001 100100 (111,204 decimal)                           > v2.A0

And in UltraNum, the value would be: R9a                              > v2.A0

When Color Mapping Mode is in use, the color parameter may be shorter > v2.A0
than four digits.  This is for space savings, as it is allowable in   > v2.A0
the specification for the last numeric parameter in a parameter list  > v2.A0
to be "shorter" than the full length.                                 > v2.A0

In Color Map mode, this command chooses one of the colors of the      > v2.A0
256-color Drawing Palette defined by the class of Set Palette         > v2.A0
commands.  Here is the default 16 lowest colors of the Desktop        > v2.A0
Palette (these correspond to the colors of ANSI text graphics):       > v2.A3

                            Master 64-Color                           > v2.A0
                           Palette Color Code                         > v2.A0
    16─Color RIP Palette   ─────────────────    R/G/B                 > v2.A0
        Color Code         Base-10 B-36 B-64    (0-3)  Color          > v2.A0
    ═════════════════════════════════════════════════════════════     > v2.A0
           00                0     (00) [0]     0 0 0  Black          > v2.A0
           01                1     (01) [1]     0 0 2  Blue           > v2.A0
           02                2     (02) [2]     0 2 0  Green          > v2.A0
           03                3     (03) [3]     0 2 2  Cyan           > v2.A0
           04                4     (04) [4]     2 0 0  Red            > v2.A0
           05                5     (05) [5]     2 0 2  Magenta        > v2.A0
           06                20    (0K) [K]     2 1 0  Brown          > v2.A0
           07                7     (07) [7]     2 2 2  Light Gray     > v2.A0
           08                56    (1K) [u]     1 1 1  Dark Gray      > v2.A0
           09                57    (1L) [v]     1 1 3  Light Blue     > v2.A0
           0A                58    (1M) [w]     1 3 1  Light Green    > v2.A0
           0B                59    (1N) [x]     1 3 3  Light Cyan     > v2.A0
           0C                60    (1O) [y]     3 1 1  Light Red      > v2.A0
           0D                61    (1P) [z]     3 1 3  Light Magenta  > v2.A0
           0E                62    (1Q) [#]     3 3 1  Yellow         > v2.A0
           0F                63    (1R) [@]     3 3 3  White          > v2.A0

The raw color values (0-63) correspond to an RGB color definition in  > v2.A0
which two bits are used for each of the Red, Green and Blue           > v2.A0
components.  The layout of the binary number is shown as follows:     > v2.A0



                       Primary    Secondary                           > v2.A0
                     ├─────────┤ ├─────────┤                          > v2.A0
            ╔═══╤═══╦═══╤═══╤═══╦═══╤═══╤═══╗                         > v2.A0
            ║▒▒▒│▒▒▒║   │   │   ║   │   │   ║                         > v2.A0
            ║▒▒▒│▒▒▒║ R │ G │ B ║ r │ g │ b ║                         > v2.A0
            ║▒▒▒│▒▒▒║   │   │   ║   │   │   ║                         > v2.A0
            ╚═══╧═══╩═══╧═══╧═══╩═══╧═══╧═══╝                         > v2.A0
              80  40  20  10  8   4   2   1  (hex)                    > v2.A0
              7   6   5   4   3   2   1   0  (position)               > v2.A0

Notice that each of the R, G and B sections are broken up into two    > v2.A0
separate bit sections in the color palette entry number.  Also, the   > v2.A0
bits are reversed when they are encoded.  Let's look at four separate > v2.A0
colors of Red, Green and Blue to see how the bit patterns correspond  > v2.A0
to the actual Palette entries:                                        > v2.A0

 RED   PALETTE ENTRY    GREEN  PALETTE ENTRY     BLUE  PALETTE ENTRY  > v2.A0
 ═══════════════════     ═══════════════════     ═══════════════════  > v2.A0
         xxRGBrgb                xxRGBrgb                xxRGBrgb     > v2.A0
         ────────                ────────                ────────     > v2.A0
 00      00000000        00      00000000        00      00000000     > v2.A0
 01      00100000        01      00010000        01      00001000     > v2.A0
 10      00000100        10      00000010        10      00000001     > v2.A0
 11      00100100        11      00010010        11      00001001     > v2.A0

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



┌───────────────────────┐
│ 3.4.1.7 ■ RIP_COMMENT │
└───────────────────────┘

       Function: Put in a comment as part of a RIPscrip sequence      > v2.A2
          Level: 0                                                    > v2.A2
        Command: !                                                    > v2.A2
      Arguments: string...                                            > v2.A2
         Format: !|!This is a comment                                 > v2.A2
        Example: !|!Everything from this point on is ignored          > v2.A2
Uses Draw Color: NO                                                   > v2.A2
Uses Back Color: NO                                                   > v2.A2
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO                                                   > v2.A2
Uses Font Style: NO                                                   > v2.A2
  Uses Viewport: NO                                                   > v2.A2
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: N/A                                                  > v2.A2

A comment may be embedded inside a RIPscrip file.  A comment is one   > v2.A2
line or longer in length.  A comment is a special case of a RIPscrip  > v2.A2
command letter.  In this case, it is the command letter "!".  If a    > v2.A2
"!" is encountered right after a "!|", a "SOH |" or an "STX |"        > v2.A2
sequence, then the remainder of the command line is a comment.        > v2.A2
Comments may be line-continued with backslashes just like regular     > v2.A2
RIPscrip commands can.  Some examples of comments might be:           > v2.A2

     !|!This is a comment                                             > v2.A2

     !|c0F|!Set the color to white|c00|!Set the color to black        > v2.A2

     !|c0F|!this is a very long, continued\                           > v2.A2
     comment line.  Line-continued comments\                          > v2.A2
     adhere to standard RIPscrip line continuation rules              > v2.A2

Note that the second example shows a comment starting after a         > v2.A2
legitimate RIPscrip command (set color).  This is valid.              > v2.A2

The RIP_COMMENT is treated exactly like any other RIPscrip command    > v2.A2
for the purposes of parsing RIPscrip commands, EXCEPT that the        > v2.A2
string is explicitly ignored for text variables.  Any use of `|' will > v2.A2
be interpreted as the beginning of the next command, and `\' will     > v2.A2
interpreted as a line continuation.  No other characters need be      > v2.A2
escaped out.                                                          > v2.A2



┌─────────────────────────┐
│ 3.4.1.8 ■ RIP_ERASE_EOL │
└─────────────────────────┘

       Function: Erase current line from cursor to end of line
          Level: 0
        Command: >
      Arguments: <none>
         Format: !|>
        Example: !|>
Uses Draw Color: NO
Uses Back Color: YES                                                  > v2.A3
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO
Uses Font Style: NO
  Uses Viewport: NO                                                   > v1.54
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: N/A                                                  > v2.A2

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.



┌──────────────────────────┐
│ 3.4.1.9 ■ RIP_ERASE_VIEW │
└──────────────────────────┘

       Function: Clear Graphics Window to current background color
          Level: 0
        Command: E
      Arguments: <none>
         Format: !|E
        Example: !|E
Uses Draw Color: NO
Uses Back Color: YES                                                  > v2.A3
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO
Uses Font Style: NO
  Uses Viewport: NO                                                   > v1.54
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: N/A                                                  > v2.A2

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 text window portion(s) also.                              > v2.A3



┌─────────────────────────────┐
│ 3.4.1.10 ■ RIP_ERASE_WINDOW │
└─────────────────────────────┘

       Function: Clears Text Window to current background color
          Level: 0
        Command: e
      Arguments: <none>
         Format: !|e
        Example: !|e
Uses Draw Color: NO
Uses Back Color: NO                                                   > v2.A3
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO
Uses Font Style: NO
  Uses Viewport: NO                                                   > v1.54
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: N/A                                                  > v2.A2

This clears the TTY text window to the current graphics background    > v2.A4
color (color #0) and positions the cursor in the upper-left corner of > v2.A4
the window.                                                           > v2.A4

The area that is erased is actually the bounding rectangle of the     > v2.A4
text window, not only the display region inside the bounding          > v2.A4
rectangle.  This is different than ANSI commands which erase the text > v2.A4
window to a certain color.  ANSI/VT-102 commands only erase the       > v2.A4
display region, not the entire bounding rectangle.                    > v2.A4

If the text window is not in use or deactivated, then                 > v2.A4
this command is ignored.  If the text window and any viewports        > v2.A4
overlap, then this command will clear the overlapping viewport(s)     > v2.A4
also.                                                                 > v2.A3



┌────────────────────────────────────┐
│ 3.4.1.11 ■ RIP_EXTENDED_FONT_STYLE │
└────────────────────────────────────┘

       Function: Select current outline font style (True Type style)  > v2.A3
          Level: 0                                                    > v2.A1
        Command: y                                                    > v2.A1
      Arguments: direction:3 size:2 style:2 h_align:1 v_align:1       > v2.A2
                 reserved:4 font_name_string                          > v2.A2
         Format: !|y <direction> <size> <style> <h_align>             > v2.A1
                 <v_align> <reserved> <font_name_string>              > v2.A2
        Example: !|y0P01203000000courier                              > v2.A2
Uses Draw Color: NO                                                   > v2.A1
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO                                                   > v2.A1
Uses Font Style: YES                                                  > v2.A1
  Uses Viewport: NO                                                   > v2.A1
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

This command is an extended form of the RIP_FONT_STYLE command.  The  > v2.A1
use of this command opens up a large number of other fonts that       > v2.A1
aren't like the older RIPscrip 1.x fonts.  They are not vector based  > v2.A1
and they're not bitmapped based like those used with the              > v2.A1
RIP_FONT_STYLE command.  The older fonts are very useful for many     > v2.A1
applications, but when it comes to production video graphics they     > v2.A1
leave a bit to be desired.  This command utilizes True-Type (tm)      > v2.A1
style fonts which are "outline" fonts.  By outline, we mean that they > v2.A1
draw the outline of the font and fill-in the interior of the font.    > v2.A1
They also have a number of special attributes that you may assign to  > v2.A1
them (ie, Bold, Italic, Strikeout and Underline).                     > v2.A1

The addition of this extended font system fills a need in RIPscrip    > v2.A1
for solid fonts that are extensible (ie, specifying fonts not in the  > v2.A1
default system).  Fonts are scalable to an arbitrary point size       > v2.A1
(unlike the fonts in RIP_FONT_STYLE which have pre-defined font       > v2.A1
sizes).                                                               > v2.A1

The commands RIP_TEXT, RIP_TEXT_XY, RIP_REGION_TEXT and RIP_BUTTON    > v2.A1
use whichever font command is most recent (eg, RIP_FONT_STYLE or      > v2.A1
RIP_EXTENDED_FONT_STYLE).  In other words, whichever font style that  > v2.A1
has been selected will be the one that is used for rendering the      > v2.A1
associated RIPscrip text related commands.                            > v2.A1

This command differs from the RIP_FONT_STYLE in several respects.     > v2.A1
One, it doesn't use built-in font sizes like the older format does    > v2.A1
(see RIP_FONT_STYLE); this command specifies fonts in a more          > v2.A1
universal format of Point Sizes.  A "point" is technically defined as > v2.A1
1/72nd of an inch.  Secondly, these fonts have the ability to alter   > v2.A1
the text "facing" which should be shown to the user (bold, italic,    > v2.A1
etc).                                                                 > v2.A1

This font system supports simple horizontal or vertical orientations  > v2.A1
for the text.  The way you specify the font direction is different!   > v2.A1
The direction of the font is specified in tenths (1/10's) of degrees  > v2.A2
for future expadability. The possible values for the font <direction> > v2.A2
are (in decimal, meganum, and ultranum):                              > v2.A2


    Dec Meg Ult Description                                           > v2.A2
    ────────────────────────────────────────────────────────────────  > v2.A2
    000 000 000 Horizontal text (left to right text)                  > v2.A2
    900 0P0 0E4 Vertical text (bottom to top - rotated 90.0 degrees)  > v2.A2

The <direction> parameter may be enhanced in a future revision to     > v2.A1
support arbitrary rotation of the font (in tenths of a degree         > v2.A3
increments).  For now, valid values for this parameter are 0.0 and    > v2.A3
90.0 degrees.                                                         > v2.A3

The <h_align> parameter determines the orientation of the displayed   > v2.A1
text around the specified text beginning coordinates.  In other       > v2.A1
words, the text might begin at the coordinate and move left, right,   > v2.A1
or be centered around the location.  The possible values for the      > v2.A1
<h_align> parameter are as follows:                                   > v2.A1

   Value   Description of Horizontal Alignment                        > v2.A1
   ─────────────────────────────────────────────────────────────      > v2.A1
     0     Align text to the left - X/Y location is the far left      > v2.A1
           of the text                                                > v2.A1
     1     Right align text.  The X/Y location is the far right       > v2.A1
           of the text                                                > v2.A1
     2     Center the text horizontally around the X/Y location       > v2.A1

The <v_align> parameter is much like the <h_align> parameter in that  > v2.A1
it defines the orientation of the font in relation to the X/Y text    > v2.A1
coordinates.  This command though performs vertical justification of  > v2.A1
the font instead of horizontal justification (like the <h_align>      > v2.A1
parameter).  The possible values for this parameter are:              > v2.A1

   Value   Description of Vertical Alignment                          > v2.A1
   ─────────────────────────────────────────────────────────────      > v2.A1
     0     Align the text vertically with the X/Y location at         > v2.A1
           the very top of the tallest character in the font.         > v2.A1
     1     Make the X/Y location of the text at the very bottom       > v2.A1
           of the tallest character in the font.                      > v2.A1
     2     Center the text vertically around the X/Y location         > v2.A1
           (this takes descenders into consideration).                > v2.A1
     3     Align the text where the X/Y base point defines the        > v2.A1
           location where the baseline of the font will appear.       > v2.A1

The <size> parameter defines the point size of the font to be         > v2.A1
displayed on the screen.                                              > v2.A1

In order to maintain resolution independence with extended fonts and  > v2.A1
various resolutions, we need to formally define how a point size is   > v2.A1
rendered at different resolutions.  For the purposes of RIPscrip font > v2.A1
systems, we formally define a point size as one physical pixel on a   > v2.A1
640x480 resolution device.  Since a 640x480 device on a 13"           > v2.A1
monitor is exactly 1 point per pixel, this definition holds well.     > v2.A1
For other resolutions, we simply adjust the point size to some        > v2.A1
proportion.  For example, a 1280x1024 resolution is exactly twice as  > v2.A1
wide as a 640x480 screen, but the height is 2.1333 times that of its  > v2.A1
480 counterpart.  So a little bit of adjustment must be made on the   > v2.A1
fonts to accomodate this precisely.  The ideal method for this would  > v2.A1
be if you could apply certain scaling parameters to the font system   > v2.A1
in both the horizontal and vertical directions separately.  Not all   > v2.A1
font systems will allow this though so a "closest approximation"      > v2.A1
might have to occur.  In our 1280x1024 example, you might decide to   > v2.A1
just use twice the specified point size and leave it at that (and not > v2.A1
worrying about the slight discrepency on the height portion of the    > v2.A1


font).  When getting into resolution independence, it is not always   > v2.A1
possible to get 100.0% pixel perfect accuracy.  If you can,           > v2.A1
wonderful, but it can't be expected 100.0% on all platforms.          > v2.A1

For the standard RIPterm resolutions of 640x350, 640x480, 800x600,    > v2.A1
1024x768 and 1280x1024, only two of the resolutions do not have       > v2.A1
perfectly square pixels - these are 640x350 and 1280x1024.  These are > v2.A1
not the only resolutions possible under RIPscrip - they're just the   > v2.A1
ones that TeleGrafix's RIP products utilize.  The 640x350 resolution  > v2.A1
is like the 1280x1024 resolution in that the height of fonts will     > v2.A1
need to be adjusted to be pixel accurate with their 640x480           > v2.A1
counterparts.  If you cannot do this with your font system, then you  > v2.A1
might wish to reduce the point size a little bit so that the vertical > v2.A1
component more closely matches the visual size of the font on a       > v2.A1
640x480 screen (note that your horizontal size will shrink a little   > v2.A1
bit smaller than the 640x480 font - this is a compromise - the choice > v2.A3
is your's).                                                           > v2.A3

The <style> parameter defines the style in which the font is to be    > v2.A1
rendered (eg, Normal, Bold, etc).  The style options are organized as > v2.A1
a set of flags which may be combined (OR'ed) together to produce a    > v2.A1
final, composite result:                                              > v2.A1

               Style     Description                                  > v2.A1
               ────────────────────────────                           > v2.A1
                 00      Normal font sizing                           > v2.A1
                 01      Bold font                                    > v2.A1
                 02      Italic font                                  > v2.A1
                 04      Strike-out font                              > v2.A1
                 08      Underlined font                              > v2.A1

The last, and possibly most important parameter in this command is    > v2.A1
the text parameter, <font_name_string>.  This string of text defines  > v2.A1
the name of the font to activate.  If a specified font is not         > v2.A1
recognized, then the default font in the RIP_FONT_STYLE is selected   > v2.A1
(with size of 1).                                                     > v2.A1

The possible (pre-defined) font names are:                            > v2.A1

     Name                Description                                  > v2.A1
     ───────────────────────────────────────────────────────────────  > v2.A1
     COURIER             Courier mono-spaced font                     > v2.A1
     HELV                Helvetica proportional font                  > v2.A1
     TIMESROM            Times Roman proportional font                > v2.A1
     OLDENGL             Old English (gothic) proportional font       > v2.A1
     SANSSERF            Sans Serif proportional font                 > v2.A1

These pre-defined fonts must be supported by all RIPscrip 2.0 and     > v2.A1
later software packages.  A font name is up to eight characters in    > v2.A1
length.  Other fonts may be specified by an application designer.  In > v2.A1
order for these fonts to be usable by the terminal system, they must  > v2.A1
already exist on the system and have some form of recognizable name   > v2.A1
associated with them.  In RIPscrip 2.0, we define an extended font    > v2.A1
name as a name up to eight character in length.  In order for the     > v2.A1
font to be recognized by the target terminal system it has to         > v2.A1
understand the same font name (presumably a font filename).           > v2.A1



┌─────────────────────────────────────┐
│ 3.4.1.12 ■ RIP_EXTENDED_TEXT_WINDOW │
└─────────────────────────────────────┘

       Function: Define a resolution independent text window          > v2.A4
          Level: 0                                                    > v2.A4
        Command: b                                                    > v2.A4
      Arguments: x0:XY y0:XY x1:XY y1:XY width:2 height:2 font_no:1   > v2.A4
                 flags:4 reserved:3                                   > v2.A4
         Format: !|b <x0> <y0> <x1> <y0> <width> <height> <font_no>   > v2.A4
                 <flags> <reserved>                                   > v2.A4
        Example: !|b0000ZKQO280P2000H000                              > v2.A4
Uses Draw Color: NO                                                   > v2.A4
Uses Back Color: NO                                                   > v2.A4
Uses Line Style: NO                                                   > v2.A4
Uses Fill Style: NO                                                   > v2.A4
Uses Write Mode: NO                                                   > v2.A4
Uses Font Style: NO                                                   > v2.A4
  Uses Viewport: NO                                                   > v2.A4
      Uses Port: NO                                                   > v2.A4
 Uses Base Math: Current setting                                      > v2.A4

This RIPscrip command is a more sophisticated way of defining a text  > v2.A4
window than by using the older RIP_TEXT_WINDOW command.  The older    > v2.A4
command doesn't permit you the luxury of creating a truly resolution  > v2.A4
independent text window - this command does and is far superior in    > v2.A4
design to the older RIPscrip 1.xx RIP_TEXT_WINDOW command.  If at all > v2.A4
possible, you should use this command instead of the older command as > v2.A4
it provides more flexibility and more methods of interfacing with the > v2.A4
text window via text variable query statements.                       > v2.A4

This version of a text window works by establishing a bounding        > v2.A4
rectangle that is to contain the actual text window display region.   > v2.A4
This bounding rectangle is specified just like you would in drawing   > v2.A4
a filled rectangle, by indicating the upper-left X/Y coordinates and  > v2.A4
the lower-right X/Y coordinates of the bounding rectangle.  Note that > v2.A4
the lower-right corner of the bounding rectangle is non-inclusive to  > v2.A4
the bounding rectangle region, just like with filled rectangles.  See > v2.A4
the earlier section entitled "THE MATHEMATICS OF GRAPHICS AND         > v2.A4
COORDINATES" for more detailed information on this subject and why it > v2.A4
is important.                                                         > v2.A4

Once a bounding rectangle is established, you indicate how many       > v2.A4
columns wide and how many lines tall you wish your text window to be, > v2.A4
and also indicate the desired text font you wish to use for your      > v2.A4
window.  The RIPscrip software will take your desired width, height   > v2.A4
and text font into consideration and determine if it can fit a text   > v2.A4
window inside your bounding rectangle with this font's dimensions.    > v2.A4
If it can make a text window exactly the width and height of your     > v2.A4
request, it does so - centering the text window inside the bounding   > v2.A4
rectangle as in the following diagram:                                > v2.A4



       ╔═════════════════════════════════════════════════╗            > v2.A4
       ║                                                 ║            > v2.A4
       ║    ╔═══════════════════════════════╗            ║            > v2.A4
       ║    ║                               ║            ║            > v2.A4
       ║    ║    ╔╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╤╗    ║            ║            > v2.A4
       ║    ║    ╟┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼╢    ║            ║            > v2.A4
       ║    ║    ╟┼Text window display┼╢    ║            ║            > v2.A4
       ║    ║    ╟┼┼┼┼┼┼rectangle┼┼┼┼┼┼╢    ║            ║            > v2.A4
       ║    ║    ╟┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼╢    ║            ║            > v2.A4
       ║    ║    ╟┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼┼╢    ║            ║            > v2.A4
       ║    ║    ╚╧╧╧╧╧╧╧╧╧╧╧╧╧╧╧╧╧╧╧╧╧╝    ║            ║            > v2.A4
       ║    ║                               ║            ║            > v2.A4
       ║    ╚═══════════════════════════════╝            ║            > v2.A4
       ║     Text window bounding rectangle              ║            > v2.A4
       ║                                                 ║            > v2.A4
       ╚═════════════════════════════════════════════════╝            > v2.A4
                          Graphics Screen                             > v2.A4

If the font number provided would make either the width or height of  > v2.A4
the text window "too large" to fit inside the bounding rectangle,     > v2.A4
then several things may happen (in the following order):              > v2.A4

     1) The font number is checked.  If a narrower or shorter font    > v2.A4
        is available in the RIPscrip text window system, it will      > v2.A4
        be chosen, then everything will be recalculated to see if     > v2.A4
        the width and/or height can now be fit inside the bounding    > v2.A4
        rectangle.  If it can, then this new font will be used to     > v2.A4
        accomodate the request.  This evaluation process is           > v2.A4
        incremental in nature.  If the width and/or height is too     > v2.A4
        large, then the next smaller font is checked, so on and       > v2.A4
        so forth.  Here is the table of fonts, their row/column       > v2.A4
        sizes, and which font number will be checked if the width     > v2.A4
        or the height (or both) is out of range for the given         > v2.A4
        bounding rectangle:                                           > v2.A4

                                       Next font to check             > v2.A4
                                    ───────────────────────           > v2.A4
                                    Shrink   Shrink  Shrink           > v2.A4
              Font   Columns  Rows   Width   Height   Both            > v2.A4
              ═════════════════════════════════════════════           > v2.A4
                0       80      43     1      n/a     n/a             > v2.A4
                1       91      43    n/a     n/a     n/a             > v2.A4
                2       80      25     3       0       1              > v2.A4
                3       91      25    n/a      1      n/a             > v2.A4
                4       40      25     2       0       0              > v2.A4

        If a new font must be chosen, then you evaluate whether you   > v2.A4
        need to shrink the font in the width, height or in both       > v2.A4
        directions.  Consult the preceding table to determine which   > v2.A4
        font number to check next.  If the entry specifies "n/a",     > v2.A4
        then you cannot shrink the font any further and must move on  > v2.A4
        to step number 2 (see below).                                 > v2.A4

     2) If you have moved down to the smallest font and you still     > v2.A4
        cannot obtain the desired height and width of your text       > v2.A4
        window, you have no alternative then to reduce the width      > v2.A4
        and/or height to make it fit inside the bounding rectangle.   > v2.A4
        This is a last resort situation, but must be done if the      > v2.A4
        text window is to fit inside the bounding rectangle.  If      > v2.A4
        the width is too wide, then one column will be trimmed off    > v2.A4
        of the text window and then its new pixel width would be      > v2.A4


        evaluated.  If it still doesn't fit, you keep removing        > v2.A4
        more columns, one-by-one, until you either get a window       > v2.A4
        that fits, or you hit zero columns.  If your bounding         > v2.A4
        rectangle is so small that you can't have even a one column   > v2.A4
        wide or one line tall text window then the text window is     > v2.A4
        made exactly one line tall, or one column wide to accomodate  > v2.A4
        the situation and the bounding box is adjusted accordingly    > v2.A4
        to fit exactly the outer dimensions of the newly defined      > v2.A4
        text window (albeit an incorrect one).                        > v2.A4

When the text window is actually defined, the cursor is placed in the > v2.A4
upper-left corner (0,0) and any ANSI/VT-102 attributes are reset to   > v2.A4
normal defaults.  The vertical scrolling margin for the text window   > v2.A4
defined in ANSI/VT-102 is set to the full height of the text window.  > v2.A4
The colors are set to light-gray text on a black background           > v2.A4
(low intensity white on black - standard ANSI colors).                > v2.A4

The <flags> parameter of this command allows you to specify some      > v2.A4
extra options to control how the text window is defined and how it    > v2.A4
will operate.  The available flags, which must be OR'ed togther to    > v2.A4
create a final flags "value", are as follows:                         > v2.A4

     Flag      Description                                            > v2.A4
     ──────────────────────────────────────────────────────────────   > v2.A4
        1      Enable character-wrap.  If this flag is not present,   > v2.A4
               then "chop" mode is in use.  See the RIP_TEXT_WINDOW   > v2.A4
               command for more details on this mode of text window   > v2.A4
               operation.                                             > v2.A4

        2      Disable the cursor immediately (as if a $COFF$ text    > v2.A4
               variable were processed).  This hides the cursor       > v2.A4
               immediately when the text window is created (see flag  > v2.A4
               16 for more on this).  This doesn't mean that text     > v2.A4
               won't be displayed, it only means that you won't see   > v2.A4
               a cursor in the text window when it is current and     > v2.A4
               active.                                                > v2.A4

        4      Deactivate the text window immediately upon creation.  > v2.A4
               This acts as if immediately after defining the text    > v2.A4
               window, a $DTW$ text variable command were issued.     > v2.A4
               Any raw text received by the terminal would not be     > v2.A4
               displayed in this text window if it is the current     > v2.A4
               one.  When deactivated, the cursor for this text       > v2.A4
               window is hidden and any text variables requesting     > v2.A4
               information about this text window will return a       > v2.A4
               result indicating that the text window is deactivated. > v2.A4
               Note, that the $INUSE(TW)$ text variable will still    > v2.A4
               respond that this text window is "in use", even        > v2.A4
               though it is deactivated.                              > v2.A4

        8      Ignore the font number parameter.  This flag gives     > v2.A4
               the text window definition software the task of        > v2.A4
               finding the best font to use for the text window.      > v2.A4
               This alleviates the coder from having to determine     > v2.A4
               the proper font to use.  This makes life a bit         > v2.A4
               easier in choosing fonts.                              > v2.A4

       16      Erase the text window immediately after it is          > v2.A4
               created.  This erases the contents of the entire       > v2.A4
               bounding rectangle, not just the text window display   > v2.A4
               area!  The area is erased to color #0 (which is        > v2.A4


               typically black).  This operation is performed before  > v2.A4
               the text window's cursor is displayed (if it is        > v2.A4
               displayed at all based on flag 2), and before the      > v2.A4
               text window can possibly be deactivated (via flag 4).  > v2.A4

       32      The text window is protected immediately after it is   > v2.A4
               created.                                               > v2.A4

It should be noted that there are some fundamental differences in     > v2.A4
nature from the extended text window command and the older normal     > v2.A4
text window command.  This one is obviously more powerful and has the > v2.A4
benefit of being resolution independent.  When working with text      > v2.A4
variables to query the status or configuration of text windows, some  > v2.A4
text variables cannot query particular pieces of information about    > v2.A4
extended text windows (eg, $TWX0$, $TWY0$, $TWX1$ and $TWY1$).  The   > v2.A4
types of information that cannot be obtained are the text cell        > v2.A4
coordinates of the upper-left and lower-right corners of the extended > v2.A4
text window - there aren't any - they're specified in graphical       > v2.A4
coordinates, not in text coordinates like with the RIP_TEXT_WINDOW    > v2.A4
command.  See these text variables for more details about this kind   > v2.A4
of situation.                                                         > v2.A4

NOTE:  A text window definition command is ignored if the current     > v2.A4
       text window data table entry is protected!                     > v2.A4

       The <reserved> parameter is reserved for future use in         > v2.A4
       RIPscrip and should be set to "000" for compatibility with     > v2.A4
       future releases of RIPscrip.                                   > v2.A4



┌──────────────────────────────────────────────────────────┐
│ 3.4.1.13 ■ RIP_FILL (this command is no longer supported │
└──────────────────────────────────────────────────────────┘

       Function: Flood fill screen area with current fill settings
          Level: 0
        Command: F

This command has been removed from the RIPscrip language.  Due to the > v2.A2
numerous issues trying to make it work reliably at all resolutions,   > v2.A2
it was decided that this command could not be implemented without     > v2.A2
compromising the integrity of the scene.  Also, fills work            > v2.A2
differently under Windows, OS/2, Macintosh, Amiga, and DOS.  With all > v2.A2
of the complexities involved, having a reliable fill operation cannot > v2.A2
be achieved under multiple resolutions and platforms.                 > v2.A2

There are a number of alternatives to using a flood fill.  In fact, a > v2.A2
large number of screens could have been drawn much more efficiently   > v2.A2
using the filled object commands listed below, than using a fill.     > v2.A2

    Basic Drawing Objects   Filled Equivalent:                        > v2.A2
    ─────────────────────────────────────────────                     > v2.A2
    RIP_PIXEL               N/A                                       > v2.A2
    RIP_LINE                N/A                                       > v2.A2
    RIP_RECTANGLE           RIP_FILLED_RECTANGLE                      > v2.A2
    N/A                     RIP_BAR                                   > v2.A2
    RIP_CIRCLE              RIP_FILLED_CIRCLE                         > v2.A2
    RIP_OVAL                RIP_FILLED_OVAL                           > v2.A2
    RIP_ARC                 RIP_PIE_SLICE                             > v2.A2
    RIP_OVAL_ARC            RIP_OVAL_PIE_SLICE                        > v2.A2
    RIP_POLYGON             RIP_FILLED_POLYGON                        > v2.A2
    RIP_POLYLINE            N/A                                       > v2.A2
    RIP_BEZIER              N/A                                       > v2.A2
    RIP_POLY_BEZIER         RIP_FILLED_POLY_BEZIER                    > v2.A2
    RIP_POLY_BEZIER_LINE    N/A                                       > v2.A2
    RIP_ROUNDED_RECT        RIP_FILLED_ROUNDED_RECT                   > v2.A3



┌─────────────────────────────┐
│ 3.4.1.14 ■ RIP_FILL_PATTERN │
└─────────────────────────────┘

       Function: Set user-definable (custom) fill pattern/color
          Level: 0
        Command: s
      Arguments: c1:2 c2:2 c3:2 c4:2 c5:2 c6:2 c7:2 c8:2 col:CM       > v2.A2
         Format: !|s <c1> <c2> <c3> <c4> <c5> <c6> <c7> <c8> <col>
        Example: !|s11223344556677880F
Uses Draw Color: NO
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: YES                                                  > v2.A2
Uses Write Mode: NO
Uses Font Style: NO
  Uses Viewport: NO                                                   > v1.54
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

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

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

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

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

The <col> parameter of this command serves two purposes depending     > v2.A0
on what Color Mode is currently set.  The default mode, Color Map     > v2.A0
mode, signifies that the color parameter of this command will use the > v2.A0
parameter as an index into the 256 color Drawing Palette color        > v2.A0
mapping table.  In this mode, this parameter will use the current     > v2.A0
Base Math set by the global RIP_SET_BASE_MATH command.                > v2.A0

In Direct RGB Color Mode, the color parameter will be a four-digit    > v2.A0
UltraNum (regardless of the current Base Math setting).  This numeric > v2.A0
value will be an encoded RGB value, allowing you to set arbitrary RGB > v2.A0
colors directly with the Set Color commands.  If the RGB color is not > v2.A0
permissable, the closest match from the Color Map table will be       > v2.A0
located and used.  The number of bits of precision used in the        > v2.A0
encoded RGB value will be determined by the RIP_SET_COLOR_MODE        > v2.A0
command.                                                              > v2.A0


When Color Mapping Mode is in use, the color parameter may be shorter > v2.A0
than four digits.  This is for space savings, as it is allowable in   > v2.A0
the specification for the last numeric parameter in a parameter list  > v2.A0
to be "shorter" than the full length.                                 > v2.A0

This command does not affect whether borders are enabled or disabled. > v2.A3
See RIP_SET_BORDER command for details on how to alter the status     > v2.A3
of borders.                                                           > v2.A3

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



┌───────────────────────────┐
│ 3.4.1.15 ■ RIP_FILL_STYLE │
└───────────────────────────┘

       Function: Set current fill style (predefined) & fill color
          Level: 0
        Command: S
      Arguments: pattern:2 color:CM                                   > v2.A3
         Format: !|S <pattern> <color>                                > v2.A3
        Example: !|S05000F                                            > v2.A2
Uses Draw Color: NO
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: YES                                                  > v2.A2
Uses Write Mode: NO
Uses Font Style: NO
  Uses Viewport: NO                                                   > v1.54
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

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 pen background color.  Fill pattern 00 will > v2.A3
set the entire fill area to the background color.  (In this case, the
fill color doesn't matter).

The <color> parameter of this command serves two purposes depending   > v2.A0
on what Color Mode is currently set.  The default mode, Color Map     > v2.A0
mode, signifies that the color parameter of this command will use the > v2.A0
parameter as an index into the 256 color Drawing Palette color        > v2.A0
mapping table.  In this mode, this parameter will use the current     > v2.A0
Base Math set by the global RIP_SET_BASE_MATH command.                > v2.A0

In Direct RGB Color Mode, the color parameter will be a four-digit    > v2.A0
UltraNum (regardless of the current Base Math setting).  This numeric > v2.A0
value will be an encoded RGB value, allowing you to set arbitrary RGB > v2.A0
colors directly with the Fill Style commands. If the RGB color is not > v2.A0
permissable, the closest match from the Color Map table will be       > v2.A0
located and used.  The number of bits of precision used in the        > v2.A0
encoded RGB value will be determined by the RIP_SET_COLOR_MODE        > v2.A0
command.                                                              > v2.A0


When Color Mapping Mode is in use, the color parameter may be shorter > v2.A0
than four digits.  This is for space savings, as it is allowable in   > v2.A0
the specification for the last numeric parameter in a parameter list  > v2.A0
to be "shorter" than the full length.                                 > v2.A0

This command does not affect whether borders are enabled or disabled. > v2.A3
See RIP_SET_BORDER command for details on how to alter the status     > v2.A3
of borders.                                                           > v2.A3

The following twelve diagrams show visually what each fill pattern    > v1.54
appears like.  Next to each diagram are the eight numerical values    > v1.54
which represent the monochrome bit-pattern of each line of each       > v1.54
pattern.  Numbers are shown in Hexadecimal (base 16), decimal (base   > v1.54
10) and MegaNum (base 36):                                            > v1.54


       BACKGROUND FILL                      SOLID FILL                > v1.54

    ╔════════╗  HEX DEC MEGA ULTRA   ╔════════╗  HEX DEC MEGA ULTRA   > v1.54
    ║        ║  00    0  00   00     ║████████║  FF  255  73   3@     > v1.54
    ║        ║  00    0  00   00     ║████████║  FF  255  73   3@     > v1.54
    ║        ║  00    0  00   00     ║████████║  FF  255  73   3@     > v1.54
    ║        ║  00    0  00   00     ║████████║  FF  255  73   3@     > v1.54
    ║        ║  00    0  00   00     ║████████║  FF  255  73   3@     > v1.54
    ║        ║  00    0  00   00     ║████████║  FF  255  73   3@     > v1.54
    ║        ║  00    0  00   00     ║████████║  FF  255  73   3@     > v1.54
    ║        ║  00    0  00   00     ║████████║  FF  255  73   3@     > v1.54
    ╚════════╝                       ╚════════╝                       > v1.54
        00                               01                           > v1.54


           LINE FILL                     LIGHT SLASH FILL             > v1.54

    ╔════════╗  HEX DEC MEGA ULTRA   ╔════════╗  HEX DEC MEGA ULTRA   > v1.54
    ║████████║  FF  255  73   3@     ║       █║  01    1  01   01     > v1.54
    ║████████║  FF  255  73   3@     ║      █ ║  02    2  02   02     > v1.54
    ║        ║  00    0  00   00     ║     █  ║  04    4  04   04     > v1.54
    ║        ║  00    0  00   00     ║    █   ║  08    8  08   08     > v1.54
    ║████████║  FF  255  73   3@     ║   █    ║  10   16  0G   0G     > v1.54
    ║████████║  FF  255  73   3@     ║  █     ║  20   32  0W   0W     > v1.54
    ║        ║  00    0  00   00     ║ █      ║  40   64  1S   10     > v1.54
    ║        ║  00    0  00   00     ║█       ║  80  128  3K   20     > v1.54
    ╚════════╝                       ╚════════╝                       > v1.54
        02                               03                           > v1.54


        NORMAL SLASH FILL               LIGHT BACKSLASH FILL          > v1.54

    ╔════════╗  HEX DEC MEGA ULTRA   ╔════════╗  HEX DEC MEGA ULTRA   > v1.54
    ║███     ║  E0  224  68   3W     ║████    ║  F0  240  60   3m     > v1.54
    ║██     █║  C1  193  5D   31     ║ ████   ║  78  120  3C   1u     > v1.54
    ║█     ██║  83  131  3N   23     ║  ████  ║  3C   60  1O   0y     > v1.54
    ║     ███║  07    7  07   07     ║   ████ ║  1E   30  0U   0U     > v1.54
    ║    ███ ║  0E   15  0F   0F     ║    ████║  0F   15  0F   0F     > v1.54
    ║   ███  ║  1C   28  0S   0S     ║█    ███║  87  135  3R   27     > v1.54
    ║  ███   ║  38   56  1K   0u     ║██    ██║  C3  195  5F   33     > v1.54
    ║ ███    ║  70  112  34   1m     ║███    █║  E1  225  69   3X     > v1.54
    ╚════════╝                       ╚════════╝                       > v1.54
        04                               05                           > v1.54



      LIGHT BACKSLASH FILL               LIGHT HATCH FILL             > v1.54

    ╔════════╗  HEX DEC MEGA ULTRA   ╔════════╗  HEX DEC MEGA ULTRA   > v1.54
    ║█ █  █ █║  A5  165  4L   2b     ║████████║  FF  255  73   3@     > v1.54
    ║██ █  █ ║  D2  210  5U   3I     ║█   █   ║  88  136  3S   28     > v1.54
    ║ ██ █  █║  69  105  2X   1f     ║█   █   ║  88  136  3S   28     > v1.54
    ║█ ██ █  ║  B4  180  50   2q     ║█   █   ║  88  136  3S   28     > v1.54
    ║ █ ██ █ ║  5A   90  2I   1Q     ║████████║  FF  255  73   32     > v1.54
    ║  █ ██ █║  2D   45  19   0j     ║█   █   ║  88  136  3S   28     > v1.54
    ║█  █ ██ ║  96  150  46   2M     ║█   █   ║  88  136  3S   28     > v1.54
    ║ █  █ ██║  4B   75  23   1B     ║█   █   ║  88  136  3S   28     > v1.54
    ╚════════╝                       ╚════════╝                       > v1.54
        06                               07                           > v1.54


     HEAVY CROSS HATCH FILL           INTERLEAVING LINE FILL          > v1.54

    ╔════════╗  HEX DEC MEGA ULTRA   ╔════════╗  HEX DEC MEGA ULTRA   > v1.54
    ║█      █║  81  129  3L   21     ║██  ██  ║  CC  204  5O   3C     > v1.54
    ║ █    █ ║  42   66  1U   12     ║  ██  ██║  33   51  1F   0p     > v1.54
    ║  █  █  ║  24   36  10   0a     ║██  ██  ║  CC  204  5O   3C     > v1.54
    ║   ██   ║  18   24  0O   0O     ║  ██  ██║  33   51  1F   0p     > v1.54
    ║   ██   ║  18   24  0O   0O     ║██  ██  ║  CC  204  5O   3C     > v1.54
    ║  █  █  ║  24   36  10   0a     ║  ██  ██║  33   51  1F   0p     > v1.54
    ║ █    █ ║  42   66  1U   12     ║██  ██  ║  CC  204  5O   3C     > v1.54
    ║█      █║  81  129  3L   21     ║  ██  ██║  33   51  1F   0p     > v1.54
    ╚════════╝                       ╚════════╝                       > v1.54
        08                               09                           > v1.54


     WIDELY SPACED DOT FILL           CLOSELY SPACED DOT FILL         > v1.54

    ╔════════╗  HEX DEC MEGA ULTRA   ╔════════╗  HEX DEC MEGA ULTRA   > v1.54
    ║█       ║  80  128  3K   20     ║█   █   ║  88  136  3S   28     > v1.54
    ║        ║  00    0  00   00     ║        ║  00    0  00   00     > v1.54
    ║    █   ║  08    8  08   08     ║  █   █ ║  22   34  0Y   04     > v1.54
    ║        ║  00    0  00   00     ║        ║  00    0  00   00     > v1.54
    ║█       ║  80  128  3K   20     ║█   █   ║  88  136  3S   28     > v1.54
    ║        ║  00    0  00   00     ║        ║  00    0  00   00     > v1.54
    ║    █   ║  08    8  08   08     ║  █   █ ║  22   34  0Y   24     > v1.54
    ║        ║  00    0  00   00     ║        ║  00    0  00   00     > v1.54
    ╚════════╝                       ╚════════╝                       > v1.54
        0A                               0B                           > v1.54



┌──────────────────────────────┐
│ 3.4.1.16 ■ RIP_FILLED_CIRCLE │
└──────────────────────────────┘

       Function: Draw a filled circle in current color/line style     > v2.A2
          Level: 0                                                    > v2.A2
        Command: G                                                    > v2.A2
      Arguments: x_center:XY y_center:XY radius:XY                    > v2.A2
         Format: !|G <x_center> <y_center> <radius>                   > v2.A3
        Example: !|G1E180M                                            > v2.A3
Uses Draw Color: YES                                                  > v2.A2
Uses Back Color: YES                                                  > v2.A2
Uses Line Style: YES                                                  > v2.A2
Uses Fill Style: YES                                                  > v2.A2
Uses Write Mode: YES                                                  > v2.A2
Uses Font Style: NO                                                   > v2.A2
  Uses Viewport: YES                                                  > v2.A2
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

This command draws a complete filled circle on the screen.  The       > v2.A2
interior of the circle is drawn using the current fill pattern and    > v2.A2
fill color.  The outline of the circle is drawn using the current     > v2.A2
drawing color and line thickness (if borders are enabled).            > v2.A3

The radius is considered to be in the horizontal direction for the    > v2.A3
purpose of aspect ratio calculations.                                 > v2.A3

When borders are disabled, this command adheres to the resolution     > v2.A3
independent method of filled regions.                                 > v2.A3



┌────────────────────────────┐
│ 3.4.1.17 ■ RIP_FILLED_OVAL │
└────────────────────────────┘

       Function: Draw filled ellipse using current color/pattern
          Level: 0
        Command: o
      Arguments: x_center:XY y_center:XY x_rad:XY y_rad:XY            > v2.A2
         Format: !|o <x_center> <y_center> <x_rad> <y_rad>
        Example: !|o1G2B0M0G
Uses Draw Color: YES
Uses Back Color: YES                                                  > v2.A1
Uses Line Style: YES                                                  > v2.A2
Uses Fill Style: YES                                                  > v2.A2
Uses Write Mode: YES                                                  > v2.A1
Uses Font Style: NO
  Uses Viewport: YES                                                  > v1.54
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

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.

When borders are disabled, this command adheres to the resolution     > v2.A3
independent method of filled regions.                                 > v2.A3



┌───────────────────────────────────────────────────────────┐
│ 3.4.1.18 ■ RIP_FILLED_POLYGON (formerly RIP_FILL_POLYGON) │
└───────────────────────────────────────────────────────────┘

       Function: Draw filled polygon in current color/fill pattern
          Level: 0
        Command: p
      Arguments: npoints:2 x1:XY y1:XY ... xn:XY yn:XY                > v2.A2
         Format: !|p <npoints> <x1> <y1> ... <xn> <yn>
        Example: !|p03010105050909
Uses Draw Color: YES
Uses Back Color: YES                                                  > v2.A1
Uses Line Style: YES                                                  > v2.A2
Uses Fill Style: YES                                                  > v2.A2
Uses Write Mode: YES
Uses Font Style: NO
  Uses Viewport: YES                                                  > v1.54
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

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 utilize Write Mode, but the outline of the polygon        > v2.A3
       does not.



┌───────────────────────────────────┐
│ 3.4.1.19 ■ RIP_FILLED_POLY_BEZIER │
└───────────────────────────────────┘

       Function: Draw a poly-bezier curve (multi-segmented)           > v2.A2
          Level: 0                                                    > v2.A2
        Command: x                                                    > v2.A2
      Arguments: num:2 count:2 x_base:XY y_base:XY ...                > v2.A2
                 type:1 x1:XY y1:XY x2:XY y2:XY x3:XY y3:XY ...       > v2.A2
                 type:1 x1:XY y1:XY ...                               > v2.A2
         Format: !|z <num> <count> <x_base> <y_base> ...              > v2.A2
                 <type> <x1> <y1> <x2> <y2> <x3> <y3> ...             > v2.A2
                 <type> <x1> <y1> ...                                 > v2.A2
        Example: !|z                                                  > v2.A2
Uses Draw Color: YES                                                  > v2.A2
Uses Back Color: YES                                                  > v2.A2
Uses Line Style: YES                                                  > v2.A2
Uses Fill Style: YES                                                  > v2.A2
Uses Write Mode: YES                                                  > v2.A2
Uses Font Style: NO                                                   > v2.A2
  Uses Viewport: YES                                                  > v2.A2
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

This command is identical to RIP_POLY_BEZIER, except that the         > v2.A2
interior of the poly-bezier is filled with the current fill color     > v2.A2
and fill pattern.  The actual outline of the poly-bezier is drawn     > v2.A2
using the current drawing color, line pattern and thickness.          > v2.A2

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

When borders are disabled, then the filled interior of the poly-      > v2.A3
bezier curve adheres to the resolution independent nature of filled   > v2.A3
regions.                                                              > v2.A3



┌─────────────────────────────────┐
│ 3.4.1.20 ■ RIP_FILLED_RECTANGLE │
└─────────────────────────────────┘

       Function: Draw filled rectangle with fill style/line style     > v2.A2
          Level: 0                                                    > v2.A2
        Command: K                                                    > v2.A2
      Arguments: x0:XY y0:XY x1:XY y1:XY                              > v2.A2
         Format: !|K <x0> <y0> <x1> <y1>                              > v2.A3
        Example: !|K00010A0E                                          > v2.A3
Uses Draw Color: YES                                                  > v2.A2
Uses Back Color: YES                                                  > v2.A2
Uses Line Style: YES                                                  > v2.A2
Uses Fill Style: YES                                                  > v2.A2
Uses Write Mode: YES                                                  > v2.A2
Uses Font Style: NO                                                   > v2.A2
  Uses Viewport: YES                                                  > v2.A2
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

This command draws a filled rectangle in the current drawing color,   > v2.A2
using the current line style, pattern and thickness, and the current  > v2.A2
fill style.  (x0,y0) and (x1,y1) are any two opposing corners of the  > v2.A2
rectangle.  If x0=x1 or y0=y1 then the command will draw a single     > v2.A2
vertical or horizontal line (or possibly a single pixel)  (if borders > v2.A3
are off, then this command draws nothing in this situation).          > v2.A3

This command operates similarly to the RIP_BAR command when borders   > v2.A3
are disabled, however the lower-left and lower-right edges of the     > v2.A3
filled rectangle obey the resolution independent method of performing > v2.A3
fills (see the section called "THE MATHEMATICS OF GRAPHICS AND        > v2.A3
COORDINATES" for details on how this works.                           > v2.A3

Before the rectangle is actually drawn, the (x0,y0) and (x1,y1)       > v2.A3
coordinates are "normalized".  This means that they are adjusted so   > v2.A3
that they specify the upper-left and lower-right coordinates          > v2.A3
respectively.  For example, if the parameters are received in the     > v2.A3
order of (50,25) and (25,75) - upper-right and lower-left             > v2.A3
respectively - they would be reorganized to be (25,25) and (50,75)    > v2.A3
before the rectangle is actually drawn.                               > v2.A3



┌────────────────────────────────────┐
│ 3.4.1.21 ■ RIP_FILLED_ROUNDED_RECT │
└────────────────────────────────────┘

       Function: Draw a filled rectangle with rounded corners         > v2.A3
          Level: 0                                                    > v2.A3
        Command: u                                                    > v2.A3
      Arguments: x0:XY y0:XY x1:XY y1:XY rad:2                        > v2.A3
        Example: !|u00010A0E09                                        > v2.A3
Uses Draw Color: YES                                                  > v2.A3
Uses Back Color: YES                                                  > v2.A3
Uses Line Style: YES                                                  > v2.A3
Uses Fill Style: YES                                                  > v2.A3
Uses Write Mode: YES                                                  > v2.A3
Uses Font Style: NO                                                   > v2.A3
  Uses Viewport: YES                                                  > v2.A3
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A3

This command draws a rounded corner rectangle which is filled in with > v2.A3
the current fill pattern and fill color.  The corners of the          > v2.A3
rectangle are not drawn at right angles like normal rectangles.  The  > v2.A3
rounded rectangle has circular arcs drawn at all four corners of the  > v2.A3
drawn object.  The radius of the arc that is used to fill-in the      > v2.A3
corners is specified in the <rad> parameter.  The <x0,y0> and <x1,y1> > v2.A3
parameters define the upper left and lower right corners of the       > v2.A3
rectangle as if the corners were actually specified as a normal       > v2.A3
rectangle.  The circular arcs drawn in the corners of the rounded     > v2.A3
rectangle are truly circular in nature and adhere to aspect ratios    > v2.A3
relating to the actual video configuration of the destination         > v2.A3
application program.                                                  > v2.A3

If borders are enabled, then the outer portion of the rounded         > v2.A3
rectangle are drawn in the current line style, foreground pen color   > v2.A3
and line style.  The border is drawn in "copy" mode - the border of   > v2.A3
this command (if any) is never drawn in any operation other than the  > v2.A3
COPY write mode.                                                      > v2.A3



┌───────────────────────────┐
│ 3.4.1.22 ■ RIP_FONT_STYLE │
└───────────────────────────┘

       Function: Select current vector/bitmap font style              > v2.A3
          Level: 0
        Command: Y
      Arguments: font:2 direction:2 size:2 flags:2                    > v2.A4
         Format: !|Y <font> <direction> <size> <flags>                > v2.A4
        Example: !|Y01000400
Uses Draw Color: NO
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO
Uses Font Style: YES
  Uses Viewport: NO                                                   > v1.54
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

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

     Font   Description of Font
     ─────────────────────────────────────────────
     00     Default 8x8 (*) font        Bit-Mapped                    > v2.A3
     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

     (*) Font 00 is an 8x8 font at 640x350.  Its actual cell-size     > v2.A3
         varies depending on the current resolution.  This is         > v2.A3
         equivalent to the 80x43 font of the text window.  See the    > v2.A3
         RIP_TEXT_WINDOW for a more detailed discussion of font       > v2.A3
         sizes and resolutions.                                       > v2.A3

For the Direction parameter, use 00 to indicate horizontal and 01 for
vertical.  Horizontal text appears from left to right.  Vertical      > v2.A3
text is drawn with the base-line to the right, and is read from       > v2.A3
bottom to the top.                                                    > v2.A3

For the Size parameter, use 01 for the normal default size, 02 for
level 2 magnification, 03 for level 3 magnification, and 0A for level > v2.A3
10 magnification.  For the bitmapped font (00), these magnification   > v2.A3
factors are actual scaling factors - size 2 is twice as large as size > v2.A3
1, size 3 is three times as large, etc.  The vector fonts (01-0A) are > v2.A3
not direct magnification factors - they are based on the following    > v2.A3
table:                                                                > v2.A3



     Mag Factor     Actual Scaling Factor                             > v2.A3
     ────────────────────────────────────                             > v2.A3
        01          3/5 of actual size                                > v2.A4
        02          2/3 of actual size                                > v2.A4
        03          3/4 of actual size                                > v2.A4
        04          1/1 of actual size                                > v2.A4
        05          4/3 of actual size                                > v2.A4
        06          5/3 of actual size                                > v2.A4
        07          2/1 of actual size                                > v2.A4
        08          5/2 of actual size                                > v2.A4
        09          3/1 of actual size                                > v2.A4
        0A (10)     4/1 of actual size                                > v2.A4

The physical pixel dimensions of any particular font cell at a given  > v2.A3
magnification level vary depending on resolution in such a way that   > v2.A3
they appear to be the same size on the screen.  For example, if a     > v2.A3
font at magnification level 4 is 35 pixels tall at 640x350            > v2.A3
resolution, at 640x480 resolution, the font would be the same width,  > v2.A3
but would be 48 pixels tall.  This makes sure that the fonts are      > v2.A3
resolution independent.                                               > v2.A3

The <flags> parameter allows you to alter the orientation and other   > v2.A4
special attributes of the subsequent text operations.  The possible   > v2.A4
flag values which may be combined are as follows (they must be OR'd   > v2.A4
together):                                                            > v2.A4

   Value   Description of Flag                                        > v2.A4
   ─────────────────────────────────────────────────────────────      > v2.A4
      1    Right justify text in relation to the base point           > v2.A4
      2    Center justify text horizontally around base point         > v2.A4
      4    Bottom justify the font (at the bottom of any              > v2.A4
           descenders.                                                > v2.A4
      8    Baseline justify the font (base point is at the base       > v2.A4
           line of the font).                                         > v2.A4
     16    Vertically center the text (base point is vertically       > v2.A4
           in the center of the font cell).                           > v2.A4
     32    Dropshadow the text using the current background           > v2.A4
           drawing color (set with RIP_BACK_COLOR).  The              > v2.A4
           foreground text is drawn using the current foreground      > v2.A4
           drawing color (set with RIP_COLOR).  The shadow is         > v2.A4
           drawn one pixel down and one pixel to the right of         > v2.A4
           the font for both vertical and horizontal text.            > v2.A4

Flag values 1 and 2 are mutually exclusive.  This means that either   > v2.A4
one of them may be specified, but not both!  If both are omitted,     > v2.A4
then the text is "left justified".  Flags 4, 8 and 16 are also        > v2.A4
mutually exclusive.  If either of them are omitted, then the text is  > v2.A4
drawn with "top" justification.  If both flags 1 and 2 are specified, > v2.A4
or more than one of the flags 4, 8 and 16 are specified then the      > v2.A4
command is considered an error and is completely ignored.             > v2.A4

Each form of justification uses the base point as a starting point.   > v2.A4
Where the text is drawn in relation to this base point is a matter    > v2.A4
of the justification.  Here is an example of horizontal text with     > v2.A4
all of the base point justifcation references pointed out:            > v2.A4



                               Center                                 > v2.A4
             Left ──┐            │             ┌── Right              > v2.A4
                    ▼            ▼             ▼                      > v2.A4
                   ┌──────────────┬──────────────┐                    > v2.A4
            Top ──►│██████████    │              │                    > v2.A4
                   │██        ██  │              │                    > v2.A4
                   │██        ██  │              │                    > v2.A4
                   │██████████    │██        ██  │                    > v2.A4
         Center ──►│██        ██  │██        ██  │                    > v2.A4
                   │██        ██  │██        ██  │                    > v2.A4
           Base ──►│██████████    │  ██████████  │                    > v2.A4
                   │              │          ██  │                    > v2.A4
         Bottom ──►│              │  ██████████  │                    > v2.A4
                   └──────────────┴──────────────┘                    > v2.A4


The significance of each justification can be thought of in the       > v2.A4
following diagrams of horizontal text:                                > v2.A4


  ┌──────────────┬──────────────┐    ┌──────────────┬──────────────┐  > v2.A4
  │░░████████    │              │    │██████████    │            ░░│  > v2.A4
  │██        ██  │              │    │██        ██  │              │  > v2.A4
  │██        ██  │              │    │██        ██  │              │  > v2.A4
  │██████████    │██        ██  │    │██████████    │██        ██  │  > v2.A4
  │██        ██  │██        ██  │    │██        ██  │██        ██  │  > v2.A4
  │██        ██  │██        ██  │    │██        ██  │██        ██  │  > v2.A4
  │██████████    │  ██████████  │    │██████████    │  ██████████  │  > v2.A4
  │              │          ██  │    │              │          ██  │  > v2.A4
  │              │  ██████████  │    │              │  ██████████  │  > v2.A4
  └──────────────┴──────────────┘    └──────────────┴──────────────┘  > v2.A4
         Top Justified                      Top Justified             > v2.A4
         Left Justified                    Right Justified            > v2.A4


  ┌──────────────┬──────────────┐    ┌──────────────┬──────────────┐  > v2.A4
  │██████████    │              │    │██████████    │              │  > v2.A4
  │██        ██  │              │    │██        ██  │              │  > v2.A4
  │██        ██  │              │    │██        ██  │              │  > v2.A4
  │██████████    │██        ██  │    │██████████    │██        ██  │  > v2.A4
  │░░        ██  │██        ██  │    │██        ██  │██        ██░░│  > v2.A4
  │██        ██  │██        ██  │    │██        ██  │██        ██  │  > v2.A4
  │██████████    │  ██████████  │    │██████████    │  ██████████  │  > v2.A4
  │              │          ██  │    │              │          ██  │  > v2.A4
  │              │  ██████████  │    │              │  ██████████  │  > v2.A4
  └──────────────┴──────────────┘    └──────────────┴──────────────┘  > v2.A4
      Vertically Centered                Vertically Centered          > v2.A4
         Left Justified                    Right Justified            > v2.A4


  ┌──────────────┬──────────────┐    ┌──────────────┬──────────────┐  > v2.A4
  │██████████    │              │    │██████████    │              │  > v2.A4
  │██        ██  │              │    │██        ██  │              │  > v2.A4
  │██        ██  │              │    │██        ██  │              │  > v2.A4
  │██████████    │██        ██  │    │██████████    │██        ██  │  > v2.A4
  │██        ██  │██        ██  │    │██        ██  │██        ██  │  > v2.A4
  │██        ██  │██        ██  │    │██        ██  │██        ██  │  > v2.A4
  │░░████████    │  ██████████  │    │██████████    │  ██████████░░│  > v2.A4
  │              │          ██  │    │              │          ██  │  > v2.A4
  │              │  ██████████  │    │              │  ██████████  │  > v2.A4
  └──────────────┴──────────────┘    └──────────────┴──────────────┘  > v2.A4


      Base Line Justified                Base Line Justified          > v2.A4
         Left Justified                    Right Justified            > v2.A4


  ┌──────────────┬──────────────┐    ┌──────────────┬──────────────┐  > v2.A4
  │██████████    │              │    │██████████    │              │  > v2.A4
  │██        ██  │              │    │██        ██  │              │  > v2.A4
  │██        ██  │              │    │██        ██  │              │  > v2.A4
  │██████████    │██        ██  │    │██████████    │██        ██  │  > v2.A4
  │██        ██  │██        ██  │    │██        ██  │██        ██  │  > v2.A4
  │██        ██  │██        ██  │    │██        ██  │██        ██  │  > v2.A4
  │██████████    │  ██████████  │    │██████████    │  ██████████  │  > v2.A4
  │              │          ██  │    │              │          ██  │  > v2.A4
  │░░            │  ██████████  │    │              │  ██████████░░│  > v2.A4
  └──────────────┴──────────────┘    └──────────────┴──────────────┘  > v2.A4
        Bottom Justified                  Bottom Justified            > v2.A4
         Left Justified                    Right Justified            > v2.A4


  ┌──────────────┬──────────────┐    ┌──────────────┬──────────────┐  > v2.A4
  │██████████  ░░│              │    │██████████    │              │  > v2.A4
  │██        ██  │              │    │██        ██  │              │  > v2.A4
  │██        ██  │              │    │██        ██  │              │  > v2.A4
  │██████████    │██        ██  │    │██████████    │██        ██  │  > v2.A4
  │██        ██  │██        ██  │    │██        ██░░│██        ██  │  > v2.A4
  │██        ██  │██        ██  │    │██        ██  │██        ██  │  > v2.A4
  │██████████    │  ██████████  │    │██████████    │  ██████████  │  > v2.A4
  │              │          ██  │    │              │          ██  │  > v2.A4
  │              │  ██████████  │    │              │  ██████████  │  > v2.A4
  └──────────────┴──────────────┘    └──────────────┴──────────────┘  > v2.A4
          Top Justified                     Vertically Centered       > v2.A4
      Horizontally Centered                Horizontally Centered      > v2.A4


  ┌──────────────┬──────────────┐    ┌──────────────┬──────────────┐  > v2.A4
  │██████████    │              │    │██████████    │              │  > v2.A4
  │██        ██  │              │    │██        ██  │              │  > v2.A4
  │██        ██  │              │    │██        ██  │              │  > v2.A4
  │██████████    │██        ██  │    │██████████    │██        ██  │  > v2.A4
  │██        ██  │██        ██  │    │██        ██  │██        ██  │  > v2.A4
  │██        ██  │██        ██  │    │██        ██  │██        ██  │  > v2.A4
  │██████████  ░░│  ██████████  │    │██████████    │  ██████████  │  > v2.A4
  │              │          ██  │    │              │          ██  │  > v2.A4
  │              │  ██████████  │    │            ░░│  ██████████  │  > v2.A4
  └──────────────┴──────────────┘    └──────────────┴──────────────┘  > v2.A4
        Base Line Justify                  Bottom Justification       > v2.A4
      Horizontally Centered                Horizontally Centered      > v2.A4



The significance of each justification can be thought of in the       > v2.A4
following diagrams of vertical text:                                  > v2.A4


 ┌──────────────────┐    ┌──────────────────┐    ┌──────────────────┐ > v2.A4
 │                  │    │                  │    │░░                │ > v2.A4
 │      ██████████  │    │      ██████████  │    │      ██████████  │ > v2.A4
 │            ██  ██│    │            ██  ██│    │            ██  ██│ > v2.A4
 │            ██  ██│    │            ██  ██│    │            ██  ██│ > v2.A4
 │            ██  ██│    │            ██  ██│    │            ██  ██│ > v2.A4
 │            ██  ██│    │            ██  ██│    │            ██  ██│ > v2.A4
 │            ██  ██│    │            ██  ██│    │            ██  ██│ > v2.A4
 │      ██████      │    │      ██████      │    │      ██████      │ > v2.A4
 ├──────────────────┤    ├──────────────────┤    ├──────────────────┤ > v2.A4
 │                  │    │░░                │    │                  │ > v2.A4
 │  ████  ████      │    │  ████  ████      │    │  ████  ████      │ > v2.A4
 │██    ██    ██    │    │██    ██    ██    │    │██    ██    ██    │ > v2.A4
 │██    ██    ██    │    │██    ██    ██    │    │██    ██    ██    │ > v2.A4
 │██    ██    ██    │    │██    ██    ██    │    │██    ██    ██    │ > v2.A4
 │██    ██    ██    │    │██    ██    ██    │    │██    ██    ██    │ > v2.A4
 │██    ██    ██    │    │██    ██    ██    │    │██    ██    ██    │ > v2.A4
 │░░████████████    │    │██████████████    │    │██████████████    │ > v2.A4
 └──────────────────┘    └──────────────────┘    └──────────────────┘ > v2.A4
    Left Justified       Horizontally Centered      Right Justified   > v2.A4
     Top Justified           Top Justified           Top Justified    > v2.A4


 ┌──────────────────┐    ┌──────────────────┐    ┌──────────────────┐ > v2.A4
 │                  │    │                  │    │      ░░          │ > v2.A4
 │      ██████████  │    │      ██████████  │    │      ██████████  │ > v2.A4
 │            ██  ██│    │            ██  ██│    │            ██  ██│ > v2.A4
 │            ██  ██│    │            ██  ██│    │            ██  ██│ > v2.A4
 │            ██  ██│    │            ██  ██│    │            ██  ██│ > v2.A4
 │            ██  ██│    │            ██  ██│    │            ██  ██│ > v2.A4
 │            ██  ██│    │            ██  ██│    │            ██  ██│ > v2.A4
 │      ██████      │    │      ██████      │    │      ██████      │ > v2.A4
 ├──────────────────┤    ├──────────────────┤    ├──────────────────┤ > v2.A4
 │                  │    │        ░░        │    │                  │ > v2.A4
 │  ████  ████      │    │  ████  ████      │    │  ████  ████      │ > v2.A4
 │██    ██    ██    │    │██    ██    ██    │    │██    ██    ██    │ > v2.A4
 │██    ██    ██    │    │██    ██    ██    │    │██    ██    ██    │ > v2.A4
 │██    ██    ██    │    │██    ██    ██    │    │██    ██    ██    │ > v2.A4
 │██    ██    ██    │    │██    ██    ██    │    │██    ██    ██    │ > v2.A4
 │██    ██    ██    │    │██    ██    ██    │    │██    ██    ██    │ > v2.A4
 │████████░░████    │    │████████████░░    │    │██████████████    │ > v2.A4
 └──────────────────┘    └──────────────────┘    └──────────────────┘ > v2.A4
    Left Justified       Horizontally Centered      Right Justified   > v2.A4
  Vertically Centered     Vertically Centered     Vertically Centered > v2.A4



 ┌──────────────────┐    ┌──────────────────┐    ┌──────────────────┐ > v2.A4
 │                  │    │                  │    │            ░░    │ > v2.A4
 │      ██████████  │    │      ██████████  │    │      ██████████  │ > v2.A4
 │            ██  ██│    │            ██  ██│    │            ██  ██│ > v2.A4
 │            ██  ██│    │            ██  ██│    │            ██  ██│ > v2.A4
 │            ██  ██│    │            ██  ██│    │            ██  ██│ > v2.A4
 │            ██  ██│    │            ██  ██│    │            ██  ██│ > v2.A4
 │            ██  ██│    │            ██  ██│    │            ██  ██│ > v2.A4
 │      ██████      │    │      ██████      │    │      ██████      │ > v2.A4
 ├──────────────────┤    ├──────────────────┤    ├──────────────────┤ > v2.A4
 │                  │    │            ░░    │    │                  │ > v2.A4
 │  ████  ████      │    │  ████  ████      │    │  ████  ████      │ > v2.A4
 │██    ██    ██    │    │██    ██    ██    │    │██    ██    ██    │ > v2.A4
 │██    ██    ██    │    │██    ██    ██    │    │██    ██    ██    │ > v2.A4
 │██    ██    ██    │    │██    ██    ██    │    │██    ██    ██    │ > v2.A4
 │██    ██    ██    │    │██    ██    ██    │    │██    ██    ██    │ > v2.A4
 │██    ██    ██    │    │██    ██    ██    │    │██    ██    ██    │ > v2.A4
 │████████████░░    │    │██████████████    │    │██████████████    │ > v2.A4
 └──────────────────┘    └──────────────────┘    └──────────────────┘ > v2.A4
    Left Justified       Horizontally Centered      Right Justified   > v2.A4
  Base Line Justify        Base Line Justify      Base Line Justified > v2.A4


 ┌──────────────────┐    ┌──────────────────┐    ┌──────────────────┐ > v2.A4
 │                  │    │                  │    │                ░░│ > v2.A4
 │      ██████████  │    │      ██████████  │    │      ██████████  │ > v2.A4
 │            ██  ██│    │            ██  ██│    │            ██  ██│ > v2.A4
 │            ██  ██│    │            ██  ██│    │            ██  ██│ > v2.A4
 │            ██  ██│    │            ██  ██│    │            ██  ██│ > v2.A4
 │            ██  ██│    │            ██  ██│    │            ██  ██│ > v2.A4
 │            ██  ██│    │            ██  ██│    │            ██  ██│ > v2.A4
 │      ██████      │    │      ██████      │    │      ██████      │ > v2.A4
 ├──────────────────┤    ├──────────────────┤    ├──────────────────┤ > v2.A4
 │                  │    │                ░░│    │                  │ > v2.A4
 │  ████  ████      │    │  ████  ████      │    │  ████  ████      │ > v2.A4
 │██    ██    ██    │    │██    ██    ██    │    │██    ██    ██    │ > v2.A4
 │██    ██    ██    │    │██    ██    ██    │    │██    ██    ██    │ > v2.A4
 │██    ██    ██    │    │██    ██    ██    │    │██    ██    ██    │ > v2.A4
 │██    ██    ██    │    │██    ██    ██    │    │██    ██    ██    │ > v2.A4
 │██    ██    ██    │    │██    ██    ██    │    │██    ██    ██    │ > v2.A4
 │██████████████  ░░│    │██████████████    │    │██████████████    │ > v2.A4
 └──────────────────┘    └──────────────────┘    └──────────────────┘ > v2.A4
    Left Justified       Horizontally Centered      Right Justified   > v2.A4
   Bottom Justified        Bottom Justified        Bottom Justified   > v2.A4


Here is how a font would look if it had dropshadowing enabled.  The   > v2.A4
solid squares (█) are the foreground text drawn with the color set by > v2.A4
the RIP_COLOR command, and the shaded squares (░) are the pixels      > v2.A4
drawn with the background drawing color set by the RIP_BACK_COLOR     > v2.A4
command.  Note that for dropshadowed text, the dropshadow is drawn    > v2.A4
first, then the foreground text is drawn after the dropshadow is      > v2.A4
drawn.                                                                > v2.A4



                ██████████                ████  ████                  > v2.A4
                ██░░░░░░░░██            ██  ░░██  ░░██                > v2.A4
                ██░░      ██░░          ██░░  ██░░  ██░░              > v2.A4
                ██████████  ░░          ██░░  ██░░  ██░░              > v2.A4
                ██░░░░░░░░██            ██░░  ██░░  ██░░              > v2.A4
                ██░░      ██░░          ██░░  ██░░  ██░░              > v2.A4
                ██████████  ░░          ██████████████░░              > v2.A4
                  ░░░░░░░░░░              ░░░░░░░░░░░░░░              > v2.A4

                Horizontal text          Vertical text                > v2.A4
               (with dropshadow)       (with dropshadow)              > v2.A4


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



┌───────────────────────┐
│ 3.4.1.23 ■ RIP_GOTOXY │
└───────────────────────┘

       Function: Move text cursor to row & column in Text Window
          Level: 0
        Command: g
      Arguments: x:2 y:2                                              > v2.A3
         Format: !|g <x> <y>
        Example: !|g0509
Uses Draw Color: NO
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO
Uses Font Style: NO
  Uses Viewport: NO                                                   > v1.54
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

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.



┌────────────────────────────┐
│ 3.4.1.24 ■ RIP_GROUP_BEGIN │
└────────────────────────────┘

       Function: Start a grouping of RIPscrip commands                > v2.A2
          Level: 0                                                    > v2.A2
        Command: (                                                    > v2.A2
      Arguments: <none>                                               > v2.A2
         Format: !|(                                                  > v2.A2
        Example: !|(                                                  > v2.A2
Uses Draw Color: NO                                                   > v2.A2
Uses Back Color: NO                                                   > v2.A2
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO                                                   > v2.A2
Uses Font Style: NO                                                   > v2.A2
  Uses Viewport: NO                                                   > v2.A2
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: N/A                                                  > v2.A2

This command has one special usage, that is to group blocks of        > v2.A2
commands together into logical groupings.  This has no functional use > v2.A2
to a terminal program, but to a paint program, it can be used to      > v2.A2
perform block moves of commands from one area in a scene to another.  > v2.A2
In order to accomodate this, a standardized method of doing group     > v2.A2
definitions is being created.                                         > v2.A2

To specify a command grouping, specify the commands like this:        > v2.A2

     !|(                                                              > v2.A2

       ...                                                            > v2.A2
       ... RIPscrip commands                                          > v2.A2
       ...                                                            > v2.A2

     !|)                                                              > v2.A2

When putting RIPscrip data files online on a host, you would          > v2.A2
typically want to remove groupings for efficiency, although this is   > v2.A2
not required.  A terminal program should just ignore RIP_GROUP_BEGIN  > v2.A2
and RIP_GROUP_END commands, at it has no conceivable use for the      > v2.A3
information at this time.                                             > v2.A3

Also note that a group may consist of several groups and commands.    > v2.A2
In other words, groups may be nested inside of each other for the     > v2.A2
purpose of bundling them together.                                    > v2.A2

NOTE:  Any currently active group definitions are "closed" when a     > v2.A3
       RIP_NO_MORE command is encountered in a paint program or       > v2.A3
       some kind of conversion utility that uses groups.              > v2.A3



┌──────────────────────────┐
│ 3.4.1.25 ■ RIP_GROUP_END │
└──────────────────────────┘

       Function: End a grouping of RIPscrip commands                  > v2.A2
          Level: 0                                                    > v2.A2
        Command: )                                                    > v2.A2
      Arguments: <none>                                               > v2.A2
         Format: !|)                                                  > v2.A2
        Example: !|)                                                  > v2.A2
Uses Draw Color: NO                                                   > v2.A2
Uses Back Color: NO                                                   > v2.A2
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO                                                   > v2.A2
Uses Font Style: NO                                                   > v2.A2
  Uses Viewport: NO                                                   > v2.A2
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: N/A                                                  > v2.A2

This command ends a group of RIPscrip commands.  See RIP_GROUP_BEGIN  > v2.A2
for a detailed explanation.                                           > v2.A2



┌───────────────────────┐
│ 3.4.1.26 ■ RIP_HEADER │
└───────────────────────┘

       Function: Header command for subsequent RIPscrip sequence      > v2.A1
          Level: 0                                                    > v2.A1
        Command: h                                                    > v2.A1
      Arguments: revision:2 flags:4 res:2                             > v2.A2
         Format: !|h <flags> <revision> <res>                         > v2.A1
        Example: !|h010A0100                                          > v2.A1
Uses Draw Color: NO                                                   > v2.A1
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO                                                   > v2.A1
Uses Font Style: NO                                                   > v2.A1
  Uses Viewport: NO                                                   > v2.A1
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Ultranums only                                       > v2.A2

This command was introduced in RIPscrip 2.0.  It is specifically      > v2.A1
designed with two purposes in mind.  First, it is defined to          > v2.A1
provide a consistent method for determining the revision of RIPscrip  > v2.A1
that is to follow in subsequent RIPscrip code (up to a RIP_NO_MORE    > v2.A3
command).  Second, it provides a way of performing many different     > v2.A3
kinds of reset operations (if any) in one command - much more         > v2.A1
flexible than the older RIP_RESET_WINDOWS command.  This command has  > v2.A1
the ability to set many states and situations for subsequent RIPscrip > v2.A1
code (whether MegaNums are to be used, or UltraNums, what gets reset  > v2.A1
and what doesn't, etc).                                               > v2.A1

The <revision> code of this command defines the revision of RIPscrip  > v2.A1
code that is to follow.  The valid defined revisions are as follows:  > v2.A1

             ╔══════════╤═══════════════════════╗                     > v2.A1
             ║ Revision │ Description           ║                     > v2.A1
             ╠══════════╪═══════════════════════╣                     > v2.A1
             ║    00    │ RIPscrip 1.54.00 code ║                     > v2.A1
             ║    01    │ RIPscrip 2.00.00 code ║                     > v2.A1
             ╚══════════╧═══════════════════════╝                     > v2.A1

The real heart of this command is the <flags> parameter.  This field  > v2.A1
defines all of the attributes of the header command other then the    > v2.A1
revision field.  The possible values which may be combined in this    > v2.A1
parameter (OR'ed together) are as follows:                            > v2.A1

      Value   Description                                             > v2.A1
     ═══════════════════════════════════════════════════════════════  > v2.A1
          0   Do nothing                                              > v2.A1
              ──────────────────────────────────────────────────────  > v2.A1
          1   Use MegaNums for subsequent RIPscrip code               > v2.A1
          2 * Use UltraNums for subsequent RIPscrip code              > v2.A1
              ──────────────────────────────────────────────────────  > v2.A1
          4 * Auto-set world coordinate frame                         > v2.A1
          8   Set world frame to 640x350 (backward compatible mode)   > v2.A1
              NOTE: This flag should be used in revision "00" code.   > v2.A3
              ──────────────────────────────────────────────────────  > v2.A1
         16   Perform a hard reset - this resets everything.  This    > v2.A1
              includes clearing all data backup area, even if entries > v2.A3
              are protected.  The entry is protected, then cleared.   > v2.A3


         32 * This performs a soft reset.  The screen is cleared,     > v2.A1
              all viewports are reset and viewport slot 0 is made     > v2.A1
              full screen, text windows are deleted and text          > v2.A1
              window 0 is made full screen.  All resident queries     > v2.A1
              are deleted, graphical style slots are erased as are    > v2.A1
              the button style slots.  This is identical in nature    > v2.A1
              to the RIP_RESET_WINDOWS.                               > v2.A1
              ──────────────────────────────────────────────────────  > v2.A1
         64   Clears port data table                                  > v2.A3
        128   Clears resident queries only                            > v2.A1
        256   Clears mouse/button definitions only                    > v2.A1
        512   Clears all data save slots and resets stack pointers    > v2.A3
       1024   Clears all base save areas                              > v2.A1
       2048   Clears and stops any playing sound/music                > v2.A1
       4096   Clears the screen to background color (usually black)   > v2.A1
       8192   Resets all viewports of all drawing ports to the full   > v2.A3
              size of their respective ports (no erasing performed).  > v2.A3
      16384   Clears all text window data table entries and makes     > v2.A1
              entry 0 full screen in default text (no window          > v2.A3
              clearing performed)                                     > v2.A3
      32768   Clears all graphical style data table entries           > v2.A3
      65536   Clears all button style data table entries              > v2.A3
     131072   Resets all palette data table entries to defaults       > v2.A3
              ──────────────────────────────────────────────────────  > v2.A1
     262144   All existing viewports are erased.  If combined with    > v2.A1
              flag 8192, then this is done first, then flag 8192 is   > v2.A1
              executed.                                               > v2.A1
     524288   All existing text windows are erased.  If combined      > v2.A1
              with flag 16384, then this is done first, then flag     > v2.A1
              16384 is executed.                                      > v2.A1
              ──────────────────────────────────────────────────────  > v2.A1
    1048576 * Disables all mouse/keyboard input (discards) until a    > v2.A1
              RIP_NO_MORE command is encountered thus signifying the  > v2.A1
              end of a RIPscrip sequence.  This prevents the user     > v2.A1
              from accidentally interrupting the data stream with     > v2.A1
              keyboard activity.  The mouse cursor should be changed  > v2.A1
              to something like an hourglass or disabled entirely.    > v2.A1
              If no RIP_NO_MORE is found and no RIPscrip or raw text  > v2.A1
              data is being received, then a RIP_NO_MORE should be    > v2.A1
              assumed after some suitable timeout (up to the          > v2.A1
              developer's discretion).                                > v2.A1

        NOTE: Items marked with a `*' are recommended defaults.       > v2.A2

As you can see, the <flags> parameter allows you to reset only        > v2.A1
segments of things that you want to reset giving you considerable     > v2.A1
flexibility in starting off RIPscrip scenes.                          > v2.A1

Most of the flag options are fairly self-explanatory.  Some mention   > v2.A1
should be made to several of them.  Note that the flags described     > v2.A1
above are grouped into logically related flag groups.  Flags 1 and 2  > v2.A1
are mutually exlusive meaning only "1" or "2" may be used, but not    > v2.A1
both.  Choosing either flag 1 or 2 resets coordinate sizes to 2       > v2.A1
bytes.                                                                > v2.A1

Flag 4 requires some explanation.  Auto-setting the world coordinate  > v2.A1
frame (WCF) will auto-set the world coordinate frame to a set of      > v2.A1
high-resolution world coordinates.  The exact choices of coordinates  > v2.A1
chosen depend on whether you specified UltraNums or MegaNums.  If you > v2.A1
specify flag 4, then you must specify either flag 1 or flag 2 to      > v2.A1
determine which base math to use.  MegaNums set the width of the      > v2.A1


world coordinate frame to 1280, and the WCF height to 960.            > v2.A4
This provides for a square world frame pixels.  If UltraNums are      > v2.A1
used, then the width of the world frame is set to 4096 and the height > v2.A1
is set to 3072.  Again, this provides for square world frame pixels.  > v2.A1
If you physically need a larger world frame then you either need to   > v2.A1
alter the base math setting explicitly or alter the X/Y coordinate    > v2.A1
parameter size (see the next few commands).                           > v2.A1

Most video displays have a 4:3 width to height pixel ratio.  For      > v2.A2
example, 640x480 is 4:3, 1024x768 is 4:3, etc. Note that 1280x1024    > v2.A2
is NOT a 4:3 ratio (the 4:3 ratio for 1280 would be 1280x960.)        > v2.A2

The Hard Reset option (flag 16) will perform a complete reset of the  > v2.A1
RIPscrip environment.  This is equivalent to choosing flags 64        > v2.A1
through 131072.  In effect, this clears everything including          > v2.A1
data save slots and the base save areas.                              > v2.A1

The Soft Reset option (flag 32) will perform a reset that is          > v2.A1
identical in nature to the RIP_RESET_WINDOWS reset.  This is          > v2.A1
equivalent to choosing flags 1, 8, 64, 128, and 2048 through 131072.  > v2.A1
This doesn't delete any data save slots or base save areas, doesn't   > v2.A1
intentionally affect the world frame except that it sets it to        > v2.A1
640x350, and chooses MegaNums as the numbers of choice.               > v2.A1

NOTE: This command ALWAYS sets the mouse cursor back to the default   > v2.A2
      arrow pointer unless the "disable mouse input" flag is used     > v2.A3
      whereas the mouse will be temporarily changed to an hourglass   > v2.A3
      or disabled entirely until a RIP_NO_MORE.  After this, then     > v2.A3
      the pointer will be reset back to an arrow.  See                > v2.A3
      RIP_SET_MOUSE_CURSOR for details.                               > v2.A2



┌─────────────────────┐
│ 3.4.1.27 ■ RIP_HOME │
└─────────────────────┘

       Function: Move cursor to upper-left corner of Text Window
          Level: 0
        Command: H
      Arguments: <none>
         Format: !|H
        Example: !|H
Uses Draw Color: NO
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO
Uses Font Style: NO
  Uses Viewport: NO                                                   > v1.54
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: N/A                                                  > v2.A2

This command positions the text cursor to the upper-left corner in
the TTY Text Window, if it is active.  This is equivalent to the ANSI > v2.A3
command "ESC[1;1H".                                                   > v2.A3



┌─────────────────────┐
│ 3.4.1.28 ■ RIP_LINE │
└─────────────────────┘

       Function: Draw a line in the current color/line style
          Level: 0
        Command: L
      Arguments: x0:XY y0:XY x1:XY y1:XY                              > v2.A2
         Format: !|L <x0> <y0> <x1> <y1>
        Example: !|L00010A0E
Uses Draw Color: YES
Uses Back Color: YES                                                  > v2.A1
Uses Line Style: YES                                                  > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: YES
Uses Font Style: NO
  Uses Viewport: YES                                                  > v1.54
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

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.



┌───────────────────────────┐
│ 3.4.1.29 ■ RIP_LINE_STYLE │
└───────────────────────────┘

       Function: Defines a line's pattern and thickness
          Level: 0
        Command: =
      Arguments: off_draw:1 style:1 user_pat:4 thick:2                > v2.A3
         Format: !|= <off_draw> <style> <user_pat> <thick>            > v2.A3
        Example: !|=01000001
Uses Draw Color: NO
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: YES                                                  > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO
Uses Font Style: NO
  Uses Viewport: NO                                                   > v1.54
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

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

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

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

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

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

In RIPscrip v2.0, the off spaces of a patterned line can now be       > v2.A3
something other than transparent (as in 1.x RIPscrip format).  If     > v2.A1
the <off_draw> parameter is set to a non-zero value, then the current > v2.A3
pen background color is used to draw the off pixels of a patterned    > v2.A3
line.  The values of the <off_draw> field are as follows:             > v2.A3

     Value   Description                                              > v2.A1
     ──────────────────────────────────────────────────               > v2.A1
       0     Draw off pixels as transparent pixels                    > v2.A3
       1     Draw off pixels using pen background color               > v2.A3

In earlier verions of RIPscrip (v1.54 and earlier), only two          > v2.A1
different line thickness options were allowed (1 pixel wide and 3     > v2.A1
pixels wide).  In 2.00 and later revisions, arbitrary thicknesses of  > v2.A1
lines are supported from 1 pixel on up.  If the thickness is an even  > v2.A1
number than it is up to the destination system's graphics engine to   > v2.A1


determine whether the even pixel is drawn to the left or right of the > v2.A1
center point in vertical orientations, or above/below for horizontal  > v2.A1
orientations.  In any event, the thickness value of lines is          > v2.A1
specified by the <thick> parameter.                                   > v2.A1

When a RIP_RESET_WINDOWS or a RIP_HEADER command is executed that     > v2.A3
resets the environment, the current line style is set to a single     > v2.A3
pixel wide solid line.  Off pixels are set to transparent mode.       > v2.A3



┌─────────────────────┐
│ 3.4.1.30 ■ RIP_MOVE │
└─────────────────────┘

       Function: Move the current drawing position to (X,Y)
          Level: 0
        Command: m
      Arguments: x:XY y:XY                                            > v2.A2
         Format: !|m <x> <y>
        Example: !|m0509
Uses Draw Color: NO
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO
Uses Font Style: NO
  Uses Viewport: YES                                                  > v1.54
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

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.



┌────────────────────────┐
│ 3.4.1.31 ■ RIP_NO_MORE │
└────────────────────────┘

       Function: End of RIPscrip Scene
          Level: 0
        Command: #
      Arguments: <none>
         Format: !|#
        Example: !|#
Uses Draw Color: NO
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO
Uses Font Style: NO
  Uses Viewport: NO                                                   > v1.54
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: N/A                                                  > v2.A2

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

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

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

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



┌────────────────────────────────────┐
│ 3.4.1.32 ■ RIP_ONE_DRAWING_PALETTE │
└────────────────────────────────────┘

       Function: Set Drawing Palette entries to RGB colors            > v2.A0
          Level: 0                                                    > v2.A0
        Command: d                                                    > v2.A0
      Arguments: entry:2 bits:1 rgb_color:4                           > v2.A3
         Format: !|d <entry> <bits> <rgb_color>                       > v2.A0
        Example: !|d018qR3P                                           > v2.A2
Uses Draw Color: YES                                                  > v2.A0
Uses Back Color: YES                                                  > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO                                                   > v2.A0
Uses Font Style: NO                                                   > v2.A0
  Uses Viewport: NO                                                   > v2.A0
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

This command will set a single entry in the Drawing Palette to an     > v2.A0
arbitrary RGB color.  This allows you to customize the Drawing        > v2.A0
Palette with extended color information beyond what you can normally  > v2.A3
do with the Desktop Palette.  This command is more flexible in nature > v2.A0
in that it allows you to access colors between 0-255 and gives you    > v2.A0
the added flexibility to store more than 2 bits of RGB data - thus    > v2.A3
allowing you to select colors out of a much larger master palette.    > v2.A3

The <entry> parameter specifies which Color Palette Entry number will > v2.A0
be set with the RGB color data.                                       > v2.A0

NOTE:  The four-digit color parameters are not MegaNums - they are    > v2.A0
       always ULTRA-NUMS regardless of the setting of the global      > v2.A0
       base-math value!  With four digits at base-64 math, you can    > v2.A0
       achieve 24-bits of precision in one four-digit number.         > v2.A0

If you break-down the four-digit UltraNum color values into their     > v2.A0
binary equivalents (three bytes), the MSB would contain the Red       > v2.A0
component, the LSB would contain the Blue component and the byte in   > v2.A0
between contains the Green component.  This command allows you to     > v2.A0
specify a number of <bits> for each component.  Under no              > v2.A0
circumstances are <bit> values above 8 allowed, since this would      > v2.A3
overflow a four-digit UltraNum parameter (beyond 24 bits).            > v2.A0

Color Entry number zero (0) is the screen's background color.  It is  > v2.A0
normally set to RGB color 0/0/0, or Black.  Changing this color will  > v2.A0
alter the background color of the entire screen/environment, so great > v2.A0
care should be taken if you alter color number 0.                     > v2.A0



┌────────────────────────────┐
│ 3.4.1.33 ■ RIP_ONE_PALETTE │
└────────────────────────────┘

       Function: Set RGB color of 16-color Desktop Palette            > v2.A3
          Level: 0
        Command: a
      Arguments: color:2 value:2
         Format: !|a <color> <value>
        Example: !|a051B
Uses Draw Color: YES
Uses Back Color: YES                                                  > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO
Uses Font Style: NO
  Uses Viewport: NO                                                   > v1.54
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

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

See the RIP_COLOR command for an exact description of the RGB values  > v2.A3
used in this command.                                                 > v2.A1

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



┌─────────────────────┐
│ 3.4.1.34 ■ RIP_OVAL │
└─────────────────────┘

       Function: Draw elliptical arc in current color/line style
          Level: 0
        Command: O
      Arguments: x:XY y:XY st_ang:2 end_ang:2 x_rad:XY y_rad:XY       > v2.A2
         Format: !|O <x> <y> <st_ang> <end_ang> <x_rad> <y_rad>
        Example: !|O1E1A18003G15                                      > v2.A2
Uses Draw Color: YES
Uses Back Color: YES                                                  > v2.A1
Uses Line Style: YES                                                  > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: YES                                                  > v2.A1
Uses Font Style: NO
  Uses Viewport: YES                                                  > v1.54
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

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.

NOTE:  This command is identical to the RIP_OVAL_ARC due to           > v2.A3
       historical reasons.  See RIP_OVAL_ARC for a discussion         > v2.A3
       of the starting angle and the ending angle parameters of       > v2.A3
       this command.                                                  > v2.A3



┌─────────────────────────┐
│ 3.4.1.35 ■ RIP_OVAL_ARC │
└─────────────────────────┘

       Function: Draw an elliptical arc
          Level: 0
        Command: V
      Arguments: x:XY y:XY st_ang:2 e_ang:2 radx:XY rady:XY           > v2.A2
         Format: !|V <x> <y> <st_ang> <e_ang> <radx> <rady>
        Example: !|V1E18003G151Q
Uses Draw Color: YES
Uses Back Color: YES                                                  > v2.A1
Uses Line Style: YES                                                  > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: YES                                                  > v2.A1
Uses Font Style: NO
  Uses Viewport: YES                                                  > v1.54
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

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

                          90°
                           │
                   180°────┼────0°
                           │
                          270°

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

Both angles can be greater than 360 degrees.  The starting angle      > v2.A3
must be greater or equal to the ending angle.                         > v2.A3



┌───────────────────────────────┐
│ 3.4.1.36 ■ RIP_OVAL_PIE_SLICE │
└───────────────────────────────┘

       Function: Draws an elliptical pie slice
          Level: 0
        Command: i
      Arguments: x:XY y:XY st_ang:2 e_ang:2 radx:XY rady:XY           > v2.A2
         Format: !|i <x> <y> <st_ang> <e_ang> <radx> <rady>
        Example: !|i1E18003G151Q
Uses Draw Color: YES
Uses Back Color: YES                                                  > v2.A1
Uses Line Style: YES                                                  > v2.A2
Uses Fill Style: YES                                                  > v2.A2
Uses Write Mode: YES                                                  > v2.A1
Uses Font Style: NO
  Uses Viewport: YES                                                  > v1.54
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

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.

Both angles can be greater than 360 degrees.  The starting angle      > v2.A3
must be greater or equal to the ending angle.                         > v2.A3

When borders are disabled, this command adheres to the resolution     > v2.A3
independent method of filling regions.                                > v2.A3



┌──────────────────────────┐
│ 3.4.1.37 ■ RIP_PIE_SLICE │
└──────────────────────────┘

       Function: Draws a circular pie slice
          Level: 0
        Command: I
      Arguments: x:XY y:XY start_ang:2 end_ang:2 radius:XY            > v2.A2
         Format: !|I <x> <y> <start_ang> <end_ang> <radius>
        Example: !|I1E18003G15
Uses Draw Color: YES
Uses Back Color: YES                                                  > v2.A1
Uses Line Style: YES                                                  > v2.A2
Uses Fill Style: YES                                                  > v2.A2
Uses Write Mode: YES                                                  > v2.A1
Uses Font Style: NO
  Uses Viewport: YES                                                  > v1.54
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

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.

Both angles can be greater than 360 degrees.  The starting angle      > v2.A3
must be greater or equal to the ending angle.                         > v2.A3

The radius is considered to be in the horizontal direction for the    > v2.A3
purpose of aspect ratio calculations.                                 > v2.A3

When borders are disabled, this command adheres to the resolution     > v2.A3
independent method of filling regions.                                > v2.A3



┌──────────────────────┐
│ 3.4.1.38 ■ RIP_PIXEL │
└──────────────────────┘

       Function: Draws one pixel using current drawing color
          Level: 0
        Command: X
      Arguments: x:XY y:XY                                            > v2.A2
         Format: !|X <x> <y>
        Example: !|X1122
Uses Draw Color: YES
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: YES                                                  > v2.A1
Uses Font Style: NO
  Uses Viewport: YES                                                  > v1.54
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

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 heavy use of it.



┌────────────────────────┐
│ 3.4.1.39 ■ RIP_POLYGON │
└────────────────────────┘

       Function: Draw polygon in current color/line-style
          Level: 0
        Command: P
      Arguments: npoints:2 x1:XY y1:XY ... xn:XY yn:XY                > v2.A2
         Format: !|P <npoints> <x1> <y1> ... <xn> <yn>
        Example: !|P03010105090905
Uses Draw Color: YES
Uses Back Color: YES                                                  > v2.A1
Uses Line Style: YES                                                  > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: YES
Uses Font Style: NO
  Uses Viewport: YES                                                  > v1.54
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

This command will draw a multi-sided closed polygon.  The polygon is
drawn using the current drawing color, line pattern, thickness and    > v2.A3
raster operation (write mode).  The <npoints> parameter is between    > v2.A3
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.



┌─────────────────────────┐
│ 3.4.1.40 ■ RIP_POLYLINE │
└─────────────────────────┘

       Function: Draw a Poly-Line (multi-faceted line)                > v1.54
          Level: 0                                                    > v1.54
        Command: l                                                    > v1.54
      Arguments: npoints:2 x1:XY y1:XY ... xn:XY yn:XY                > v2.A2
         Format: !|l <npoints> <x1> <y1> ... <xn> <yn>                > v1.54
        Example: !|l03010105090905                                    > v1.54
Uses Draw Color: YES                                                  > v1.54
Uses Back Color: YES                                                  > v2.A1
Uses Line Style: YES                                                  > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: YES                                                  > v1.54
Uses Font Style: NO                                                   > v1.54
  Uses Viewport: YES                                                  > v1.54
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

This command will draw a multi-faceted line.  It is identical in      > v1.54
nature to the RIP_POLYGON command above, except that the last point   > v1.54
is NOT connected to the first point.  Generally speaking, a Poly-     > v1.54
Line is not an "enclosed area".  The segments of the Poly-Line are    > v2.A3
drawn using the current drawing color, line pattern, thickness and    > v2.A3
Drawing Write Mode.                                                   > v1.54

The <npoints> parameter is between 2 and 512 and indicates how many   > v1.54
(x,y) coordinate pairs will follow, which is also the number of sides > v1.54
of the Poly-Line.                                                     > v1.54

An example of a five sided (6 vertices) Poly-Line might be:           > v1.54

       P1 o                                             o P6          > v1.54
           ▀▄                          o P4           ▄▀              > v1.54
             ▀▄                      ▄▀█            ▄▀                > v1.54
               ▀▄                  ▄▀  █          ▄▀                  > v1.54
                 ▀▄              ▄▀    █        ▄▀                    > v1.54
                   ▀▄          ▄▀      █      ▄▀                      > v1.54
                     ▀o▄▄▄▄▄▄o▀        █    ▄▀                        > v1.54
                    P2       P3        █  ▄▀                          > v1.54
                                     P5█▄▀                            > v1.54
                                       o                              > v1.54



┌────────────────────────────┐
│ 3.4.1.41 ■ RIP_POLY_BEZIER │
└────────────────────────────┘

       Function: Draw a poly-bezier curve (multi-segmented)           > v2.A1
          Level: 0                                                    > v2.A1
        Command: z                                                    > v2.A1
      Arguments: num:2 count:2 x_base:XY y_base:XY ...                > v2.A2
                 type:1 x1:XY y1:XY ...                               > v2.A2
                 type:1 x1:XY y1:XY x2:XY y2:XY x3:XY y3:XY ...       > v2.A2
         Format: !|z <num> <count> <x_base> <y_base> ...              > v2.A1
                 <type> <x1> <y1> ...                                 > v2.A2
                 <type> <x1> <y1> <x2> <y2> <x3> <y3> ...             > v2.A2
        Example: See below                                            > v2.A2
Uses Draw Color: YES                                                  > v2.A1
Uses Back Color: YES                                                  > v2.A1
Uses Line Style: YES                                                  > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: YES                                                  > v2.A1
Uses Font Style: NO                                                   > v2.A1
  Uses Viewport: YES                                                  > v2.A1
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

This command is a variation on the RIP_BEZIER command.  The typical   > v2.A1
RIP_BEZIER command creates one single bezier curve.  This command     > v2.A1
combines one or more bezier curves into a chain of connected bezier   > v2.A1
curves.  Each segment (curve) of the poly-bezier can be of different  > v2.A1
types.  It can be a bezier curve, or a simple straight line.  The     > v2.A1
combination of these facilities allows the construction of say, a     > v2.A1
text character representation of a font that has some straight line   > v2.A3
segments and some curved segments.  The curved portions (bezier       > v2.A1
curves) are actually comprised of many smaller straight line          > v2.A1
segments - when viewed on a monitor, they appear to be a continuous   > v2.A1
curve.  The actual number of segments comprising a particular curve   > v2.A1
in the poly-bezier is determined by the command's <count> parameter.  > v2.A1

This command is different than any other in RIPscrip in that its      > v2.A1
variable length portion of the command is made up of different blocks > v2.A1
of parameters which can be different byte lengths!  If you look at    > v2.A1
the definition, the beginning of the command includes a <num>,        > v2.A1
<count>, <x_base> and <y_base> parameter - the remainder of the       > v2.A3
command is variable length in nature.                                 > v2.A3

The <num> parameter defines how many parameter blocks are to be       > v2.A2
expected in this command.                                             > v2.A2

The <count> parameter defines how many "segments" are to be drawn for > v2.A2
each bezier curve segment of this poly-bezier curve.  This means that > v2.A2
all bezier curve segments in a poly-bezier will have the same number  > v2.A2
of segments for their respective curves.                              > v2.A2

The <x_base> and <y_base> parameters define the pixel beginning point > v2.A2
for the entire poly-bezier "curve".  To determine what type of        > v2.A2
parameter block follows, you need to look at the first byte of the    > v2.A2
segment; this is the <type> parameter.                                > v2.A3

The <type> parameter defines what type of parameter block is to be    > v2.A1
parsed.  The possible types are:                                      > v2.A1


     Type  Description                                                > v2.A1
     ───────────────────────────                                      > v2.A1
       0   Straight line segment                                      > v2.A1
       1   Smooth bezier curve segment                                > v2.A2
       2   Jointed bezier curve segment                               > v2.A2

A "smooth" segment is a bezier curve whose beginning curve is         > v2.A2
totally smooth with the ending curve of a previous bezier curve.      > v2.A1
In practice on a terminal system, this doesn't mean anything to a     > v2.A1
terminal program because it is going to display a bezier curve as a   > v2.A1
normal bezier curve.  The meaning of having a second bezier curve     > v2.A1
type comes into play when using paint program utilities that let you  > v2.A1
manipulate poly-bezier curves.  A paint system might use this         > v2.A1
information to control how end-points and control points can be moved > v2.A1
because they are "locked" with one or two points from the previous    > v2.A1
(or next) bezier curve.  See the notes at the end of this command's   > v2.A1
description about smooth bezier curve joints.                         > v2.A1

If the <type> parameter indicates that the segment is a straight-line > v2.A1
segment, then there are only two remaining parameters (not including  > v2.A1
the <type> parameter) in the block (the line's end-points) as in the  > v2.A1
following syntax definition:                                          > v2.A1

     type:1 x1:XY y1:XY                                               > v2.A2

The <type> parameter should be set to "0" for line segments.  The     > v2.A2
(x1,y1) parameters define the endpoints of the line segment.  The     > v2.A1
beginning point of the line is the end-point of the last segment (or  > v2.A1
the (x_base,y_base) parameters of the command header if this is the   > v2.A1
first parameter block).                                               > v2.A1

If the <type> indicates that the segment is a bezier curve, then the  > v2.A1
parameter block contains six parameters as in the following syntax    > v2.A1
definition (not including the <type> parameter):                      > v2.A1

     type:1 x1:XY y1:XY x2:XY y2:XY x3:XY y3:XY                       > v2.A1

The first byte is the <type> value for this block (be set to 1 or 2   > v2.A2
for a bezier curve segment).  The remaining six parameters define the > v2.A1
first two control points and the end-point for the bezier curve       > v2.A1
segment.  The beginning point of the curve segment is defined as the  > v2.A1
end-point of the previous block (or the (x_base,y_base) parameter in  > v2.A1
the header of the command if this is the first parameter block).      > v2.A1

Refer to the RIP_BEZIER command for a complete description of bezier  > v2.A1
curve beginning/end-points and how control points shape the curve to  > v2.A1
a desired result.                                                     > v2.A1



An example of a poly-bezier curve might be shown as follows:          > v2.A2

      Segment 1 ────────────┐   P2                                    > v2.A2
        (line)      P1      ▼ (50,10)        P3 (110,10)              > v2.A2
                 (10,10) ■▒▒▒▒■▒▒         X                           > v2.A2
                         ▒       ▒   ┌────────────── Segment 2        > v2.A2
                         ▒        ▒◄─┘                (bezier)        > v2.A2
                         ▒        ▒                                   > v2.A2
                         ▒        ▒       X P4 (110,70)               > v2.A2
         Segment 0 ─────►▒      ▒▒                                    > v2.A2
           (line)        ▒ P5 ■▒▒▒                                    > v2.A2
                         ▒(50,70) ▒          X P6 (120,70)            > v2.A2
                         ▒         ▒◄───────────────── Segment 3      > v2.A2
                         ▒         ▒                    (bezier)      > v2.A2
                         ▒(50,130) ▒                                  > v2.A2
              BASE       ▒    P8  ▒            P7 (120,130)           > v2.A2
              POINT ────►■▒▒▒▒■▒▒▒           X                        > v2.A2
                       P0/P9 ▲                                        > v2.A2
                    (10,130) └──────────────────────── Segment 4      > v2.A2
                                                        (line)        > v2.A2

The above diagram shows 5 different segments to the poly-bezier       > v2.A1
curve.  Segments 0, 1 and 4 are straight line segments, and semgents  > v2.A1
2 and 3 are actual bezier curves.  All X/Y points (beginning-points,  > v2.A1
end-points and control-points are depicted with X's and are labeled   > v2.A1
P0 through P9.  The parameters to represent this command might        > v2.A1
appear something like the following (in expanded decimal):            > v2.A1

         Decimal     MegaNum     Description                          > v2.A2
         ──────────────────────────────────────────────────           > v2.A2
     !|z 05 ........ 05 ........ 5 segments                           > v2.A2
         10 ........ 0A ........ 10 lines per bezier curve            > v2.A2
           10,130 ..   0A 3M ... Base point - P0                      > v2.A2
         0 ......... 0 ......... Segment 0 - Line                     > v2.A2
           10,10 ...   0A 0A ... Line endpoint - P1                   > v2.A2
         0 ......... 0 ......... Segment 1 - Line                     > v2.A2
           50,10 ...   1E 0A ... Line endpoint - P2                   > v2.A2
         1 ......... 1 ......... Segment 2 - Smooth Bezier            > v2.A2
           110,10 ..   32 0A ... Control point - P3                   > v2.A2
           110,70 ..   32 1Y ... Control point - P4                   > v2.A2
           50,70 ...   1E 1Y ... Curve end point - P5                 > v2.A2
         2 ......... 2 ......... Segment 3 - Jointed Bezier           > v2.A2
           120,70 ..   3C 1Y ... Control point - P6                   > v2.A2
           120,130 .   3C 3M ... Control point - P7                   > v2.A2
           50,130 ..   1E 3M ... Curve end point - P8                 > v2.A2
         0 ......... 0 ......... Segment 4 - Line                     > v2.A2
           10,130 ..   0A 3M ... Line endpoint - P9                   > v2.A2

Notice that in the preceding example we are not expressing numbers in > v2.A1
meganums as would normally be used in RIPscrip files.  This is for    > v2.A1
simple human readability for this example.                            > v2.A1

The completed command looks like this (base math setting = meganums): > v2.A2

     !|z050A0A3M00A0A01E0A1320A321Y1E1Y23C1Y3C3M1E3M00A3M             > v2.A2

This command is often used to combine several segments together       > v2.A1
into one larger "curve".  As previously mentioned, the end-point of   > v2.A1
one segment is the beginning point of the next segment (if any).      > v2.A1


When you are dealing with bezier curve segments, it is possible to    > v2.A1
make sure that the end of one curve has a perfectly smooth curve with > v2.A1
the beginning of the next curve.  If two adjacent bezier curve blocks > v2.A1
are to have a perfectly smooth "connecting joint", then you must make > v2.A1
sure that the last control point and the end-point of the first curve > v2.A1
are colinear with the first control point of the second curve.  This  > v2.A1
is not a requirement of this command - it is generic in that it can   > v2.A1
display any combination of line segments and bezier curve segments.   > v2.A1
We are simply noting this mathematical attribute of bezier curves for > v2.A1
the benefit of the RIPscrip programmer to generate smooth segmented   > v2.A1
curves in some sort of paint program.                                 > v2.A1

A bezier curve can also have a "smooth joint" with a line segment. If > v2.A1
the bezier curve is followed by a line segment, then to make sure     > v2.A1
that the joint has a smooth curve, you must make sure that the last   > v2.A1
control point and the end point of the bezier curve segment are       > v2.A1
colinear with the end-point of the following line segment.  The same  > v2.A1
holds true of the segments are reversed (line segment followed by a   > v2.A1
bezier curve segment) - the only difference is that the beginning     > v2.A1
point of a line segment is determined by the end-point of its         > v2.A1
preceding block (or the base point if the line segment is the first   > v2.A1
parameter block) and you would be making the starting point of the    > v2.A1
bezier curve and the 1ST control point colinear.                      > v2.A1

NOTE:  Poly-Bezier curves might exhibit pixel annomolies at the       > v2.A1
beginning and ending points of each segment if thick lines are used   > v2.A1
for the curve with XOR or other non-COPY write modes.  The reason for > v2.A1
this is because some graphics engines (Windows, Macintosh, MS-DOS,    > v2.A1
etc) might not handle things 100.0% perfectly for thick poly-lines in > v2.A1
XOR mode (poly-lines are used to represent this command after all     > v2.A1
segments are broken down).                                            > v2.A1



┌─────────────────────────────────┐
│ 3.4.1.42 ■ RIP_POLY_BEZIER_LINE │
└─────────────────────────────────┘

       Function: Draw a poly-bezier curve (open-ended)                > v2.A2
          Level: 0                                                    > v2.A2
        Command: t                                                    > v2.A2
      Arguments: num:2 count:2 x_base:XY y_base:XY ...                > v2.A2
                 type:1 x1:XY y1:XY ...                               > v2.A2
                 type:1 x1:XY y1:XY x2:XY y2:XY x3:XY y3:XY ...       > v2.A2
         Format: !|z <num> <count> <x_base> <y_base> ...              > v2.A2
                 <type> <x1> <y1> ...                                 > v2.A2
                 <type> <x1> <y1> <x2> <y2> <x3> <y3> ...             > v2.A2
        Example: See below                                            > v2.A2
Uses Draw Color: YES                                                  > v2.A2
Uses Back Color: YES                                                  > v2.A2
Uses Line Style: YES                                                  > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: YES                                                  > v2.A2
Uses Font Style: NO                                                   > v2.A2
  Uses Viewport: YES                                                  > v2.A2
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

This command is a variation on the RIP_POLY_BEZIER command.  The      > v2.A2
difference is that the RIP_POLY_BEZIER command is a closed object,    > v2.A2
meaning that the beginning and ending points are connected.  With     > v2.A2
RIP_POLY_BEZIER_LINE, the object does not have it's end points        > v2.A2
connected.  This is just like the difference between RIP_POLYGON and  > v2.A2
RIP_POLYLINE.                                                         > v2.A2

This command uses the same parameter order as RIP_POLY_BEZIER.        > v2.A2



┌──────────────────────────┐
│ 3.4.1.43 ■ RIP_RECTANGLE │
└──────────────────────────┘

       Function: Draw a rectangle in current color/line style
          Level: 0
        Command: R
      Arguments: x0:XY y0:XY x1:XY y1:XY                              > v2.A2
         Format: !|R <x0> <y0> <x1> <y1>
        Example: !|R00010A0E
Uses Draw Color: YES
Uses Back Color: YES                                                  > v2.A1
Uses Line Style: YES                                                  > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: YES
Uses Font Style: NO
  Uses Viewport: YES                                                  > v1.54
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

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.



┌──────────────────────────────┐
│ 3.4.1.44 ■ RIP_RESET_WINDOWS │
└──────────────────────────────┘

       Function: Clear Graphic/Text Windows & reset to full screen
          Level: 0
        Command: *
      Arguments: <none>
         Format: !|*
        Example: !|*
Uses Draw Color: NO
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO
Uses Font Style: NO
  Uses Viewport: NO                                                   > v1.54
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: N/A                                                  > v2.A2

A system might use this function before entering a text-only mode
that does not support RIP commands.

This command will:

     ■ Set the World Coordinate Frame to 640x350 (backwards compat.)  > v2.A1
     ■ Set the Text Window to a full screen                           > v2.A2
     ■ Set the Text Window to the user-selected default of the        > v2.A2
       five Text Window fonts (80x43, 91x43, 80x25, 91x25, and 40x25) > v2.A2
       and place the text cursor in the upper left corner.            > v2.A2
     ■ Restore the default RIP color palette (see RIP_SET_PALETTE and > v2.A2
       RIP_SET_DRAWING_PALETTE below).                                > v2.A2
     ■ Clear the entire screen to the current background color        > v2.A2
       (which is black because the color palette was just reset!)     > v2.A2
     ■ Delete all Mouse Fields and Mouse Buttons                      > v2.A2
     ■ Delete ports #1-35 (unprotected) - port #0 is made full screen > v2.A2
     ■ Reset all graphical style data tables and Text Window data     > v2.A0
       tables to suitable defaults.                                   > v2.A3
     ■ All "active data table entries" are set to entry #0            > v2.A3
       current slots are set to slot #0.                              > v2.A0
     ■ Reset all button style data tables                             > v2.A1
     ■ Set the mouse cursor back to the default arrow pointer.        > v2.A2
       See RIP_SET_MOUSE_CURSOR for details.                          > v2.A2
     ■ Set the current Base Math to Base-36 (meganums).               > v2.A0
     ■ Set the coordinate size to 2 byte MegaNums                     > v2.A1
     ■ Set the color palette to map mode (not Direct RGB encoding).   > v2.A1


     NOTE: The data backup areas are not cleared by this command.     > v2.A3



┌─────────────────────────────┐
│ 3.4.1.45 ■ RIP_ROUNDED_RECT │
└─────────────────────────────┘

       Function: Draw a rectangle with rounded corners                > v2.A3
          Level: 0                                                    > v2.A3
        Command: U                                                    > v2.A3
      Arguments: x0:XY y0:XY x1:XY y1:XY rad:2                        > v2.A3
        Example: !|U00010A0E09                                        > v2.A3
Uses Draw Color: YES                                                  > v2.A3
Uses Back Color: YES                                                  > v2.A3
Uses Line Style: YES                                                  > v2.A3
Uses Fill Style: NO                                                   > v2.A3
Uses Write Mode: YES                                                  > v2.A3
Uses Font Style: NO                                                   > v2.A3
  Uses Viewport: YES                                                  > v2.A3
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A3

This command draws a rounded corner rectangle.  The corners of the    > v2.A3
rectangle are not drawn at right angles like normal rectangles.  The  > v2.A3
rounded rectangle has circular arcs drawn at all four corners of the  > v2.A3
drawn object.  The radius of the arc that is used to fill-in the      > v2.A3
corners is specified in the <rad> parameter.  The <x0,y0> and <x1,y1> > v2.A3
parameters define the upper left and lower right corners of the       > v2.A3
rectangle as if the corners were actually specified as a normal       > v2.A3
rectangle.  The circular arcs drawn in the corners of the rounded     > v2.A3
rectangle are truly circular in nature and adhere to aspect ratios    > v2.A3
relating to the actual video configuration of the destination         > v2.A3
application program.                                                  > v2.A3



┌──────────────────────────────┐
│ 3.4.1.46 ■ RIP_SET_BASE_MATH │
└──────────────────────────────┘

       Function: Sets the base math for most RIPscrip parameters      > v2.A0
          Level: 0                                                    > v2.A0
        Command: b                                                    > v2.A0
      Arguments: base_math:2                                          > v2.A0
         Format: !|b <base_math>                                      > v2.A0
        Example: !|b1S                                                > v2.A2
Uses Draw Color: NO                                                   > v2.A0
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO                                                   > v2.A0
Uses Font Style: NO                                                   > v2.A0
  Uses Viewport: NO                                                   > v2.A0
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: MegaNums only                                        > v2.A2

This command sets the Base Math used extensively throughout the       > v2.A0
RIPscrip language.  By default, the RIPscrip language used Base-36    > v2.A0
math for all of its numeric parameters.  This number can be changed   > v2.A0
to accomodate larger values for numeric parameters.  For example, a   > v2.A0
two digit base-36 number can hold a number from 0-1295.  A two digit  > v2.A3
Base-64 number can hold a number from 0-4095 which is considerably    > v2.A0
larger.                                                               > v2.A0

This can be used when you set the World Coordinate Frame to larger    > v2.A0
coordinates, even larger than 1024x1024.  Altering the Base Math of   > v2.A0
the parameters gives you the ability to handle larger numbers without > v2.A0
expanding the size (byte-wise) of parameters throughout the language  > v2.A0
(see RIP_SET_COORDINATE_SIZE).                                        > v2.A3

NOTE:  This command ALWAYS uses base-36 (MegaNum) math for            > v2.A0
       its parameter.  The reason for this is that this is a          > v2.A0
       universal command, and the Base Math may not be known          > v2.A0
       at the moment the command is received.                         > v2.A0

When a RIP_RESET_WINDOWS command is received, the base math is reset  > v2.A0
to Base-36 (MegaNum) values.  If a scene is received after the Reset  > v2.A0
Windows command and it uses Base Math other than Base-36, then you    > v2.A0
MUST send a RIP_SET_BASE_MATH command immediately after the           > v2.A0
RIP_RESET_WINDOWS command.                                            > v2.A0

The valid settings at this time are:                                  > v2.A0

     Base-36 ("10" meganum)                                           > v2.A0
     Base-64 ("1S" meganum)                                           > v2.A0

If an illegal Set Base Math command is received (an illegal base math > v2.A0
setting), RIPscrip will default to MegaNums.                          > v2.A0



┌───────────────────────────┐
│ 3.4.1.47 ■ RIP_SET_BORDER │
└───────────────────────────┘

       Function: Enable or disable borders on filled objects          > v2.A3
          Level: 0                                                    > v2.A3
        Command: N                                                    > v2.A3
      Arguments: borders:2                                            > v2.A3
         Format: !|N <borders>                                        > v2.A3
        Example: !|N01                                                > v2.A3
Uses Draw Color: NO                                                   > v2.A3
Uses Back Color: NO                                                   > v2.A3
Uses Line Style: NO                                                   > v2.A3
Uses Fill Style: NO                                                   > v2.A3
Uses Write Mode: NO                                                   > v2.A3
Uses Font Style: NO                                                   > v2.A3
  Uses Viewport: NO                                                   > v2.A3
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: Current Setting                                      > v2.A3

This command specifies whether borders are drawn with filled objects  > v2.A3
(eg, RIP_FILLED_RECTANGLE, etc).  This command does not affect the    > v2.A3
command RIP_BAR.  When borders are enabled, the following commands    > v2.A3
will draw a border around the filled region:                          > v2.A3

          RIP_FILLED_RECTANGLE                                        > v2.A3
          RIP_FILLED_CIRCLE                                           > v2.A3
          RIP_FILLED_OVAL                                             > v2.A3
          RIP_PIE_SLICE                                               > v2.A3
          RIP_OVAL_PIE_SLICE                                          > v2.A3
          RIP_FILLED_POLYGON                                          > v2.A3
          RIP_FILLED_POLY_BEZIER                                      > v2.A3
          RIP_FILLED_ROUNDED_RECT                                     > v2.A3

Borders drawn around the filled regions are always drawn in the write > v2.A3
mode COPY (this is to avoid strange pixel interactions in XOR, OR,    > v2.A3
AND and NOT modes when they interact with the filled-pixels behind    > v2.A3
them.  The borders are drawn using the current line thickness.  The   > v2.A3
polygon related command also adheres to line patterns; all other      > v2.A3
commands only use the line thickness.  The filled regions are         > v2.A3
initially drawn using the resolution independent methods of filling.  > v2.A3
After that, the border is drawn based on standard methodologies.      > v2.A3
For more details, see the section entitled "THE MATHEMATICS OF        > v2.A3
GRAPHICS AND COORDINATES" for a more detailed explanation of these    > v2.A3
issues.                                                               > v2.A3

Setting the <border> parameter to "01" enables borders around filled  > v2.A3
objects.  A value of "00" indicates that borders are disabled.        > v2.A3

When a RIP_RESET_WINDOWS or a RIP_HEADER command is executed (where   > v2.A3
the environment is reset), borders are automatically enabled for      > v2.A3
backwards compatibility.                                              > v2.A3



┌───────────────────────────────┐
│ 3.4.1.48 ■ RIP_SET_COLOR_MODE │
└───────────────────────────────┘

       Function: Set the Color Drawing Mode (MAP or DIRECT RGB)       > v2.A0
          Level: 0                                                    > v2.A0
        Command: M                                                    > v2.A0
      Arguments: mode:1 bits:1                                        > v2.A0
         Format: !|M <mode> <bits>                                    > v2.A0
        Example: !|M18                                                > v2.A0
Uses Draw Color: NO                                                   > v2.A0
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO                                                   > v2.A0
Uses Font Style: NO                                                   > v2.A0
  Uses Viewport: NO                                                   > v2.A0
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

This command determines whether Color Mapping mode is in use, or if   > v2.A0
Direct RGB Colors are being used for color codes.  See the beginning  > v2.A0
of this specification for a detailed explanation of the differences   > v2.A0
between these modes.                                                  > v2.A0

The <mode> parameter may take on the following values:                > v2.A0

     Mode   Description                                               > v2.A0
     ─────────────────────────────────────────                        > v2.A0
       0    Color Mapping mode (default)                              > v2.A2
       1    Direct RGB Color mode                                     > v2.A0

The <bits> parameter is used to determine how many bits are to be     > v2.A0
parsed in the Direct RGB Color mode.  This parameter is ignored if    > v2.A0
the Color Mapping Mode is in effect.                                  > v2.A0

When in Direct RGB Color Mode, any Color Code parameter in the        > v2.A0
RIPscrip language that doesn't explicitly state that it uses only     > v2.A0
Color Map Mode will process a color value as a raw RGB value encoded  > v2.A0
in the same fashion as the RIP_SET_DRAWING_PALETTE command.  These    > v2.A0
parameters, when in Direct RGB Color Mode, will be in ULTRA-NUM       > v2.A3
format regardless of the global Base Math settings for compression.   > v2.A1
Color palette mode though uses the current base math settings for     > v2.A1
these color parameters.                                               > v2.A1

In Color Mapping Mode, these color parameters will typically not be   > v2.A0
the lengthy four-digit sequence used in Direct RGB Color Mode.  When  > v2.A0
in Color Mapping Mode, the color parameters used throughout RIPscrip  > v2.A0
will obey the global Base Math setting - it's only in Direct RGB      > v2.A0
Color Mode where UltraNums are forced ON for these parameters.        > v2.A0



┌────────────────────────────────────┐
│ 3.4.1.49 ■ RIP_SET_COORDINATE_SIZE │
└────────────────────────────────────┘

       Function: Sets the number of bytes used for XY coordinates     > v2.A1
          Level: 0                                                    > v2.A1
        Command: n                                                    > v2.A1
      Arguments: byte_size:1 res:3                                    > v2.A1
         Format: !|n <byte_size> <res>                                > v2.A1
        Example: !|n2000                                              > v2.A1
Uses Draw Color: NO                                                   > v2.A1
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO                                                   > v2.A1
Uses Font Style: NO                                                   > v2.A1
  Uses Viewport: NO                                                   > v2.A1
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

This command alters the number of bytes that will be expected for all > v2.A1
subsequent X or Y parameters in RIPscrip.  By default, all X or Y     > v2.A1
parameters are two bytes in length as denoted syntax-wise as x:XY or  > v2.A1
y:XY in the specification.  This command allows you to alter this     > v2.A1
size.  In 1.x versions of RIPscrip, the maximum size of a parameter   > v2.A1
was in the X direction and the maximum value was 639.  This could     > v2.A1
safely be represented in two meganum digits.  In 2.0 of RIPscrip and  > v2.A1
beyond, we introduce a world coordinate system into the specification > v2.A1
which allows you to use a much higher resolution for your drawing     > v2.A1
environment.  This facilitates resolution independence.  To provide   > v2.A1
for future expandability when ultra-high resolution devices might     > v2.A1
exist, the possibility of an X or Y coordinate exceeding 4095 might   > v2.A1
occur.  Since this is the largest value that can be accomodated in a  > v2.A1
2-byte UltraNum, we offer an option that provides for extensibility.  > v2.A3

Using this parameter to expand the byte size beyond 2 will make a     > v2.A1
RIPscrip file bigger.  This is because every X/Y coordinate will be   > v2.A1
expanded in size by a certain number of bytes, and since these are    > v2.A1
the fundamental values in any graphical environment, it will result   > v2.A1
in larger RIPscrip files.  In practice, this command should be used   > v2.A1
with caution.  When situations permit, do not use this command, or    > v2.A1
use it with a byte size of 2 (the default).  This will keep files     > v2.A1
from ever getting larger than they would be by default.               > v2.A1

Valid settings are from 2-5.  If any other values are specified,      > v2.A3
then a value of 2 will be assumed.                                    > v2.A3

A RIP_RESET_WINDOWS command will reset the coordinate size back to    > v2.A1
two byte wide parameters.                                             > v2.A1

NOTE:  The <res> parameter is reserved and should be set to "000"     > v2.A1
       for future expansion by TeleGrafix.                            > v2.A1



┌────────────────────────────────────┐
│ 3.4.1.50 ■ RIP_SET_DRAWING_PALETTE │
└────────────────────────────────────┘

       Function: Set Drawing Palette entries to RGB colors            > v2.A0
          Level: 0                                                    > v2.A0
        Command: D                                                    > v2.A0
      Arguments: num:2 start:2 bits:1 c1:4 ... cn:4                   > v2.A3
         Format: !|D <num> <bits> <start> <c1> ... <cn>               > v2.A2
        Example: !|D030180GhZPzr3aZr3                                 > v2.A2
Uses Draw Color: YES                                                  > v2.A0
Uses Back Color: YES                                                  > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO                                                   > v2.A0
Uses Font Style: NO                                                   > v2.A0
  Uses Viewport: NO                                                   > v2.A0
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

This command will set one or more colors in the 256-entry Drawing     > v2.A0
Palette to arbitrary RGB color mappings.  This allows you to          > v2.A0
customize the Drawing Palette with extended color information beyond  > v2.A0
what you can normally do with the Desktop Palette.  This command is   > v2.A3
more flexible in nature in that it allows you to access colors        > v2.A0
between 0-255 and gives you the added flexibility to store more than  > v2.A0
2 bits of red, green and blue information thus allowing you to select > v2.A3
colors out of a much larger master palette.                           > v2.A3

The <num> parameter specifies how many color entries are contained in > v2.A0
this given Palette command.  This is used in determining how many     > v2.A0
bytes long the command should be.                                     > v2.A0

 NOTE: The four-digit color parameters are not meganums - they are    > v2.A0
       always ULTRANUMS regardless of the setting of the global       > v2.A0
       base-math value!  With four digits at base-64 math, you can    > v2.A0
       achieve 24-bits of precision in one four-digit number.         > v2.A0

If you break-down the four-digit UltraNum color values into their     > v2.A0
binary equivalents (three bytes), the MSB would contain the Red       > v2.A0
component, the LSB would contain the Blue component and the byte in   > v2.A0
between contains the Green component.  The <bits> parameter lets you  > v2.A3
specify the number of bits for each component. Under no circumstances > v2.A0
are <bit> values above 8 allowed, since this would overflow a         > v2.A3
four-digit UltraNum parameter (beyond 24 bits).                       > v2.A0

The <start> parameter determines the starting Color Palette Entry     > v2.A0
number that the first color in the command will be assigned to.       > v2.A0
Every following parameter will correspond to the next highest Color   > v2.A0
Palette Entry number.                                                 > v2.A0

Color Entry number zero (0) is the screen's background color.  It is  > v2.A0
normally set to RGB color 0/0/0, or Black.  Changing this color will  > v2.A0
alter the background color of the entire screen/environment, so great > v2.A0
care should be taken if you alter color number 0.                     > v2.A0



┌────────────────────────────┐
│ 3.4.1.51 ■ RIP_SET_PALETTE │
└────────────────────────────┘

       Function: Set 16-color Desktop Palette from 64-clr palette     > v2.A0
          Level: 0
        Command: Q
      Arguments: c1:2 c2:2 ... c16:2
         Format: !|Q <c1> <c2> ... <c16>
        Example: !|Q000102030405060708090A0B0C0D0E0F
Uses Draw Color: YES
Uses Back Color: YES                                                  > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO
Uses Font Style: NO
  Uses Viewport: NO                                                   > v1.54
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

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

See the RIP_COLOR command for an exact description of the RGB valus   > v2.A3
used in this command.                                                 > v2.A3

Color 00 of the 16-color RIP palette is always the screen's           > v2.A3
background color (which is typically Black).



┌────────────────────────────────┐
│ 3.4.1.52 ■ RIP_SET_WORLD_FRAME │
└────────────────────────────────┘

       Function: Sets the coordinates for the World Frame             > v2.A0
          Level: 0                                                    > v2.A0
        Command: f                                                    > v2.A2
      Arguments: x_dim:XY y_dim:XY                                    > v2.A2
         Format: !|f <x_dim> <y_dim>                                  > v2.A0
        Example: !|fSGSG                                              > v2.A0
Uses Draw Color: NO                                                   > v2.A0
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO                                                   > v2.A0
Uses Font Style: NO                                                   > v2.A0
  Uses Viewport: NO                                                   > v2.A0
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

This command sets the dimensions of the World Coordinate Frame.  This > v2.A0
Frame is the Global Coordinate Space of the RIPscrip drawing screen.  > v2.A0
It is not the exact size of the Device Frame - that is a lower level  > v2.A0
coordinate system.  With this frame, you can "map" your scenes into   > v2.A0
something, say a 1024x1024 grid and let the terminal worry about      > v2.A0
mapping it into whatever device coordinates it is using (eg, 640x350, > v2.A0
800x600, etc).  Any coordinates used for setting viewports or other   > v2.A0
such things will be specified in World Frame Coordinates.  Actual     > v2.A0
drawing primitives will use the current Drawing Frame's coordinates - > v2.A0
another level of coordinate mapping.  This allows you to do things    > v2.A0
like draw full screen images inside a tinier window, leaving          > v2.A0
additional drawing space on the screen for other images.              > v2.A0

The actual Device Coordinate Frame is not specified in the RIPscrip   > v2.A0
language anywhere - it is handled entirely by the remote terminal,    > v2.A0
because only it knows the device coordinates of the environment that  > v2.A0
it is running under (although the host can query these values from    > v2.A3
the terminal).                                                        > v2.A3

The <x_dim> parameter is how wide the drawing area is in logical      > v2.A0
coordinates.  The <y_dim> parameter is how tall the drawing area is   > v2.A0
in logical coordinates.                                               > v2.A0

To translate from World Coordinates to Device Coordinates, you need   > v2.A0
to know four things:                                                  > v2.A0

     1/2) The World Frame's dimensions (ie, x_dim and y_dim)          > v2.A0
     3/4) The dimensions of the actual display device (x_max, y_max)  > v2.A0

After you have these four values, you can translate any X/Y           > v2.A0
coordinate pair in World Coordinates to Device Coordinates with the   > v2.A0
following equations:                                                  > v2.A0

  EQUATION 1 - TRANSLATE WORLD TO DEVICE COORDINATES                  > v2.A0
  ──────────────────────────────────────────────────                  > v2.A0

             ╔═══════════════════╤═══════════════════╗                > v2.A0
             ║       Xw * x_max  │       Yw * y_max  ║                > v2.A0
             ║  Xd = ──────────  │  Yd = ──────────  ║                > v2.A0
             ║         x_dim     │         y_dim     ║                > v2.A0
             ╚═══════════════════╧═══════════════════╝                > v2.A0


Where (Xw,Yw) is a point in World Coordinates.  We are solving for    > v2.A0
the point (Xd,Yd) which is in Device Coordinates.  The values         > v2.A0
x_max and y_max are the physical dimensions of the display device     > v2.A0
(eg, x_max=640, y_max=350).  The values x_dim and y_dim are the       > v2.A0
dimensions of the World Coordinate Frame (eg, x_dim=1000,             > v2.A0
y_dim=1000).                                                          > v2.A0

As an example, let's say we are drawing onto a 640x350 display device > v2.A0
and our World Coordinate Frame is 1000x1000 logical pixels in size.   > v2.A0
If we plot a pixel at coordinates right in the middle of the screen   > v2.A0
at (500,500), here is what we would have:                             > v2.A0

                       500 * 640   320,000                            > v2.A0
                  Xd = ───────── = ─────── = 320                      > v2.A0
                         1000       1000                              > v2.A0


                       500 * 350   175,000                            > v2.A0
                  Yd = ───────── = ─────── = 175                      > v2.A0
                         1000       1000                              > v2.A0

This gives us a final Device coordinate of (320,175) which is smack   > v2.A0
in the middle of the device screen as we wanted.                      > v2.A0

If we solve the above equations for Xw and Yw, we get the inverse     > v2.A0
equations - translations from Device Coordinates to World             > v2.A0
Coordinates:                                                          > v2.A0

  EQUATION 2 - TRANSLATE DEVICE TO WORLD COORDINATES                  > v2.A0
  ──────────────────────────────────────────────────                  > v2.A0

             ╔═══════════════════╤═══════════════════╗                > v2.A0
             ║       Xd * x_dim  │       Yd * y_dim  ║                > v2.A0
             ║  Xw = ──────────  │  Yw = ──────────  ║                > v2.A0
             ║         x_max     │         y_max     ║                > v2.A0
             ╚═══════════════════╧═══════════════════╝                > v2.A0

If the World Coordinates are larger than the Device Coordinates, then > v2.A0
when you translate World Coordinates to Device Coordinates, there     > v2.A0
will be pixel-perfect translation.  This means that translation will  > v2.A0
be unambiguous - they will convert to pixel coordinates without there > v2.A0
being any discrepency.  For example, if your Device Coordinates are   > v2.A0
640x350 and your World Coordinates are 1280x700, then a Point in      > v2.A0
World Coordinate space at (0,0) and (1,0) will both translate to the  > v2.A0
Device Coordinates (0,0) and (0,0) respectively.  This is because the > v2.A0
World Coordinate space is twice as large as the Device Coordinate     > v2.A0
space.  If on the other hand the Device Coordinates were 1280x700 and > v2.A0
the World Coordinate space were 640x350, then the World Points (0,0)  > v2.A0
and (1,0) would translate to (0,0) and (2,0) respectively.  Notice    > v2.A0
that in the World Coordinates, the pixels were adjacent.  But in the  > v2.A0
Device Coordinates, they are separated by a one pixel gap.            > v2.A0

In summary, World Coordinates should always be equal to or greather   > v2.A0
than the size of the Device Coordinate Frame, otherwise disparity     > v2.A0
will exist in the translations.  Since coordinate translation will    > v2.A0
almost ALWAYS be from World -> Device coordinates, everything will be > v2.A0
fine if the World Frame has a larger resolution than the Device       > v2.A0
Frame.  The same holds true for the inverse equations to translate    > v2.A0
from Device to World coordinates.  If the World Coordinate Frame is   > v2.A0
larger than the Device Coordinate Frame, then any point that is       > v2.A0
translated from Device -> World Coordinates (a Mouse X/Y location for > v2.A0


example), might not translate over precisely - skipping over pixel    > v2.A0
spaces in the World Frame - this is simply because of the precision   > v2.A0
of translation and cannot be overcome mathematically since a Mouse    > v2.A0
Pointer's location is pixel based - it doesn't have any finer         > v2.A0
locations than on pixel boundary locations (there's no such thing as  > v2.A0
a fractional pixel location in graphics hardware - only               > v2.A0
mathematically).                                                      > v2.A0

To maintain backward compatibility with previous versions of the      > v2.A0
RIPscrip specification, after a RIP_RESET_WINDOWS command is          > v2.A0
received, the World Coordinate Frame is defined as having the         > v2.A0
dimensions 640x350 until reset by a RIP_SET_WORLD_FRAME or RIP_HEADER > v2.A0
command.                                                              > v2.A0



┌─────────────────────┐
│ 3.4.1.53 ■ RIP_TEXT │
└─────────────────────┘

       Function: Draw text in current font at current XY location     > v2.A3
          Level: 0
        Command: T
      Arguments: text-string
         Format: !|T <text-string>
        Example: !|Thello world
Uses Draw Color: YES
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: YES
Uses Font Style: YES
  Uses Viewport: YES                                                  > v1.54
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: N/A                                                  > v2.A2

This command displays text at the current location in the graphics
window, as set with the RIP_MOVE command, or immediately after        > v2.A3
horizontal text drawn with RIP_TEXT_XY or a previous RIP_TEXT         > v2.A3
command.  Only horizontal text updates the current graphical cursor   > v2.A3
position used with the RIP_TEXT related commands.  Any form of screen > v2.A3
reset (RIP_RESET or RIP_HEADER with reset options) will reset this    > v2.A3
current position to (0,0).  A RIP_ERASE_VIEWPORT command does not     > v2.A3
reset this position.                                                  > v2.A3

The text is also affected by the most recent settings of these
commands:

  Command                  Description of Command
  ──────────────────────────────────────────────────────────────────
  RIP_FONT_STYLE           font style (vector font, direction, size)
  RIP_WRITE_MODE           drawing mode (normal or XOR)
  RIP_COLOR                drawing color (from the 16-color palette)
  RIP_EXTENDED_FONT_STYLE  extended font styles (True Type style)     > v2.A3

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
(even after subsequent graphical operations like circles, rectangles, > v2.A3
lines, etc).                                                          > v2.A3

IMPORTANT NOTE:  Note that this "current graphics cursor location"    > v2.A4
                 is only updated for horizontal text moving from      > v2.A4
                 left-to-right in "left justified" mode.  Any other   > v2.A4
                 orientation does not reset the location!             > v2.A4



┌────────────────────────────┐
│ 3.4.1.54 ■ RIP_TEXT_WINDOW │
└────────────────────────────┘

       Function: Define the size and location of the Text Window
          Level: 0
        Command: w
      Arguments: x0:XY y0:XY x1:XY y1:XY wrap:1 size:1                > v2.A2
         Format: !|w <x0> <y0> <x1> <y1> <wrap> <size>
        Example: !|w00001B0M10
Uses Draw Color: NO
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO
Uses Font Style: NO
  Uses Viewport: NO                                                   > v1.54
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

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 deactivated, ignoring all non-RIPscrip bytes,  > v2.A4
by setting all RIP_TEXT_WINDOW parameters to zero (0).  The X         > v2.A4
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   Columns  Rows       > v2.A3
        ───────────────────────────────────────────────────────       > v2.A3
         0     8x8             0-79     0-42        80      43        > v2.A3
         1     7x8             0-90     0-42        91      43        > v2.A3
         2     8x14            0-79     0-24        80      25        > v2.A3
         3     7x14            0-90     0-24        91      25        > v2.A3
         4     16x14           0-39     0-24        40      25        > v2.A3

        (*) Font sizes are based on a 640x350 device resolution       > v2.A3

The font sizes in the preceding table vary depending on the           > v2.A3
resolution that the terminal software is running under.  The actual   > v2.A3
cell sizes of each font are calculated based on the number of rows    > v2.A3
and columns required.  For example, at a resolution of 800x600, the   > v2.A3
cell sizes are calculated by dividing the horizontal resolution by    > v2.A3
the number of columns (800/80) which yields a cell width of 10.       > v2.A3
By doing the same thing for the same height we get 600/43 which       > v2.A3
equals 13.95348837.  You obviously cannot have a fractional cell size > v2.A3
so we round down.  This gives us a cell height of 13.  This gives a   > v2.A3
vertical region of 559 scan lines of text information yielding 41     > v2.A3


extra scan lines that don't get used.  This method can be used to     > v2.A3
determine the cell sizes for any arbitrary resolution.                > v2.A3


Now that we know what the font cell sizes are, or more acurately,     > v2.A3
how to calculate them, we need to establish a standardized way to     > v2.A3
determine screen placement for text characters.  RIPscrip 1.54 was    > v2.A3
based on 640x350 resolution and text placement was very               > v2.A3
straightforward.  If the text window was to be defined using font     > v2.A3
#2 (8x14 under 640x350) and was to be from (10,15) to (20,25) in      > v2.A3
text coordinates, then our actual upper-left corner of the text       > v2.A3
window would be located at pixel (10x8,15x14) or (80,210).  Now       > v2.A3
that we have the upper-left corner of the text window, calculating    > v2.A3
an arbitrary row/column in the text window is simple based on the     > v2.A3
cell size.                                                            > v2.A3

Under resolutions other than 640x350, we need to take very special    > v2.A3
care to make the text characters appear as close to the 640x350       > v2.A3
counterparts as possible.  In order to calculate the text window's    > v2.A3
orientation as closely as possible in other resolutions, calculate    > v2.A3
the upper-left corner of the text window at 640x350 coordinates       > v2.A3
and scale those coordinates up to the actual resolution used on the   > v2.A3
terminal.  This will insure that the text window is located as        > v2.A3
closely to the 640x350 counterpart as possible.  As previously        > v2.A3
described, the font cell sizes can leave some "slop space" due to     > v2.A3
fractional columns/rows.  This means that you cannot be pixel-for-    > v2.A3
pixel accurate with text window placement at varying resolutions.     > v2.A3
In this matter, the RIP_TEXT_WINDOW command is not truly resolution   > v2.A3
independent (see RIP_EXTENDED_TEXT_WINDOW for a truly resolution      > v2.A4
independent way of creating text windows).                            > v2.A3

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

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

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

NOTE:  A text window definition command is ignored if the current     > v2.A4
       text window data table entry is protected!                     > v2.A4



┌────────────────────────┐
│ 3.4.1.55 ■ RIP_TEXT_XY │
└────────────────────────┘

       Function: Draw text in current font/color at specific spot
          Level: 0
        Command: @
      Arguments: x:XY y:XY and text-string                            > v2.A2
         Format: !|@ <x> <y> <text-string>
        Example: !|@0011hello world
Uses Draw Color: YES
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: YES
Uses Font Style: YES
  Uses Viewport: YES                                                  > v1.54
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

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 that 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.
See the RIP_TEXT command for a more thorough discussion of this       > v2.A3
subject.                                                              > v2.A3



┌─────────────────────────┐
│ 3.4.1.56 ■ RIP_VIEWPORT │
└─────────────────────────┘

       Function: Define the size & location of the Graphics Window
          Level: 0
        Command: v
      Arguments: x0:XY y0:XY x1:XY y1:XY                              > v2.A2
         Format: !|v <x0> <y0> <x1> <y1>
        Example: !|v00002E1M
Uses Draw Color: NO
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO
Uses Font Style: NO
  Uses Viewport: NO                                                   > v1.54
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

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 current TTY window defined   > v2.A3
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 deactivated, so RIPscrip     > v2.A4
graphics commands are ignored, by setting all parameters to zero (0).

The viewport is physically bound to the current drawing port.  In     > v2.A3
other words when this command is executed, it will modify the         > v2.A3
viewport for the current drawing port.  This in effect, modifies the  > v2.A3
clipping rectangle for that port.  If any of the viewport coordinates > v2.A3
would extend beyond the boundaries of the drawing port, they will be  > v2.A3
adjusted to fit inside the port.                                      > v2.A3

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

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



To re-activate a viewport that was previously deactivated, either     > v2.A4
send a correctly configured RIP_SET_VIEWPORT command, or issue a      > v2.A4
query command with a $AVP$ text variable (Activate ViewPort).         > v2.A4



┌───────────────────────────┐
│ 3.4.1.57 ■ RIP_WRITE_MODE │
└───────────────────────────┘

       Function: Set drawing mode for graphics primitives
          Level: 0
        Command: W
      Arguments: mode:2
         Format: !|W <mode>
        Example: !|W00
Uses Draw Color: NO
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: YES
Uses Font Style: NO
  Uses Viewport: NO                                                   > v1.54
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

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

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

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

In the XOR mode, instead of changing each pixel to the current
drawing color, the pixel is merged with the destination pixel using   > v2.A1
the logical operation XOR.  This is a bitwise manipulation of the     > v2.A1
destination and source pixel values.  In a monochrome environment,    > v2.A1
the following bit combinations would yield the following:             > v2.A1

        ╔═══╤═══╦═════════╗
        ║ A │ B ║ A XOR B ║                                          > v2.A1
        ╠═══╪═══╬═════════╣                                          > v2.A1
        ║ 0 │ 0 ║    0    ║                                          > v2.A1
        ║ 0 │ 1 ║    1    ║                                          > v2.A1
        ║ 1 │ 0 ║    1    ║                                          > v2.A1
        ║ 1 │ 1 ║    0    ║                                          > v2.A1
        ╚═══╧═══╩═════════╝

In the OR mode, instead of changing each pixel to the current drawing > v2.A1
color, the pixel is merged with the destination pixel using the       > v2.A1
logical operation OR.  The bits in the source pixel are OR'ed with    > v2.A1
the bits in the destination pixel to achieve the final result.  In a  > v2.A1
monochrome environment, the following bit combinations would yield    > v2.A1
the following:                                                        > v2.A1



        ╔═══╤════╦════════╗
        ║ A │ B  ║ A OR B ║                                           > v2.A1
        ╠═══╪════╬════════╣                                           > v2.A1
        ║ 0 │ 0  ║   0    ║                                           > v2.A1
        ║ 0 │ 1  ║   1    ║                                           > v2.A1
        ║ 1 │ 0  ║   1    ║                                           > v2.A1
        ║ 1 │ 1  ║   1    ║                                           > v2.A1
        ╚═══╧════╩════════╝

In the AND mode, instead of changing each pixel to the current        > v2.A1
drawing color, the pixel is merged with the destination pixel using   > v2.A1
the logical operation AND.  The bits in the source pixel are AND'ed   > v2.A1
with the bits in the destination pixel to achieve the final result.   > v2.A1
In a monochrome environment, the following bit combinations would     > v2.A1
yield the following:                                                  > v2.A1

        ╔═══╤════╦═════════╗
        ║ A │ B  ║ A AND B ║                                          > v2.A1
        ╠═══╪════╬═════════╣                                          > v2.A1
        ║ 0 │ 0  ║    0    ║                                          > v2.A1
        ║ 0 │ 1  ║    0    ║                                          > v2.A1
        ║ 1 │ 0  ║    0    ║                                          > v2.A1
        ║ 1 │ 1  ║    1    ║                                          > v2.A1
        ╚═══╧════╩═════════╝

In the NOT mode, the color of the source pixel is completely ignored. > v2.A1
The bits in the destination pixel's color are inverted (0's become    > v2.A1
1's and 1's become 0's).  In other words, black becomes white, light  > v2.A1
gray becomes dark gray, etc (this is assuming that the color palette  > v2.A3
is a 16 color palette with default settings - 256 color palettes may  > v2.A3
react differently depending on the colors defined.                    > v2.A3

This command affects all line drawing operations (line, rectangle,    > v2.A1
circle, oval, pie slice, pixel, etc).  It also affects any fill-based > v2.A1
operations (filled bar, internal parts of a pie slice, filled circle, > v2.A1
etc).  It only affects level-0 drawing primitives.  It also affects   > v2.A1
fonts that are drawn to the screen (including the default font).      > v2.A1

The effects of OR, AND, XOR and NOT can cause distinctly different    > v2.A3
resultant colors in 16 color modes as compared to 256 color modes.    > v2.A3
For example, if you have a color of 7 (0111 binary) in a 16 color     > v2.A3
mode, and you NOT that color, you get 8 (1000 binary).  Under a       > v2.A3
standard 16 color palette, color 7 is light gray and color 8 is dark  > v2.A3
gray.  Under a 256 color palette though, color 7 (00000111 binary)    > v2.A3
will convert to 248 (11111000 binary).  This color is definitely not  > v2.A3
dark gray - it is by default, an RGB of (63,54,0) which is a shade of > v2.A3
brownish yellow.                                                      > v2.A3



╔═══════════════════════════════════╗
║ 3.4.2 ■ LEVEL-1 RIPscrip COMMANDS ║
╚═══════════════════════════════════╝

Level-1 commands are basic user-interface commands, and higher level  > v2.A4
graphical constructs like images, formatted text regions, and other   > v2.A4
such higher level concepts that aren't covered in the level-0 command > v2.A4
set.



┌──────────────────────────┐
│ 3.4.2.1 ■ RIP_BEGIN_TEXT │
└──────────────────────────┘

       Function: Define a rectangular text region
          Level: 1
        Command: T
      Arguments: x1:XY y1:XY x2:XY y2:XY res:2                        > v2.A2
         Format: !|1T <x1> <y1> <x2> <y2> <res>
        Example: !|1T00110011
Uses Draw Color: NO
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO
Uses Font Style: NO
  Uses Viewport: YES                                                  > v1.54
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

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 in the current font type, style and     > v2.A3
size.                                                                 > v2.A3

NOTE:  The "res" parameter is two bytes wide and is RESERVED for
       future use and should be set to "00".



┌──────────────────────┐
│ 3.4.2.2 ■ RIP_BUTTON │
└──────────────────────┘

       Function: Define a Mouse Button
          Level: 1
        Command: U
      Arguments: x0:XY y0:XY x1:XY y1:XY hotkey:2 flags:1 res:1       > v2.A4
                 text
         Format: !|1U <x0> <y0> <x1> <y1> <hotkey> <flags>
                 <res> <text>                                         > v2.A4
        Example: !|1U010100003200iconfile<>Label<>HostCmd^m           > v2.A4
Uses Draw Color: NO
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO
Uses Font Style: YES
  Uses Viewport: YES                                                  > v1.54
      Uses Port: YES (only for "non-mouse" type buttons)              > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

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

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

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

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

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

     [BEGIN REWORD]

       <<< Discuss resolution independence & scaling of the above >>>

     [END REWORD]

The <hotkey> parameter is only used with Mouse Buttons.  It is the
ASCII code for the keystroke that will activate this Button.  It is
represented as a two-digit MegaNum.  If this character exists in the
text label, and the Underline flag or hilight hotkey flag is enabled  > v1.54
in the RIP_BUTTON_STYLE, then the character will be underlined in the


label.  Control codes are allowable, and a value of 255 (decimal)
corresponds to "any" key.

The <flags> parameter provides several different functions for each
button.  The possible "combinatorial" flags for this parameter are
listed in the following table.  Note that these values may be
combined together (by adding their values) to arrive at the final
flag parameter's value.

        Value  Description
        ──────────────────────────────────────────────────
          1    Draw button as already selected
          2    Button is "default" when <ENTER> is pressed

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

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

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

The actual syntax of this text parameter is as follows:

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

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

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

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

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



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

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

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

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

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

Under RIPscrip 1.54 and earlier versions, button icon filenames ended > v2.A3
with .ICN for normal icons, and .HIC for "Hot IcoN".  Under 2.0,      > v2.A3
these file extensions are different.  For normal button icons, the    > v2.A3
extension .BMP is used for a standard bitmap, and .BMH is used for    > v2.A3
a "hot bitmap".                                                       > v2.A3

When a button is displayed that uses an icon/bitmap, special care     > v2.A3
must be taken when dealing with hot bitmaps.  If the flag is present  > v2.A3
in the button style indicating to use hot icons, then when the button > v2.A3
is displayed as selected then the hot bitmap (.BMH) file's image is   > v2.A3
used to display the button.  If that file doesn't exist, then the     > v2.A3
normal bitmap button is displayed in an inverted state.  If neither   > v2.A3
of these files are present, then the RIP_BUTTON command is ignored.   > v2.A3

If the host command string of the button cannot be parsed properly,   > v2.A3
then the button is completely ignored.                                > v2.A3

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



┌────────────────────────────┐
│ 3.4.2.3 ■ RIP_BUTTON_STYLE │
└────────────────────────────┘

       Function: Button style definition
          Level: 1
        Command: B
      Arguments: wid:XY hgt:XY orient:2 flags:4 size:2                > v2.A2
                 dfore:2 dback:2 bright:2 dark:2 surface:2
                 grp_no:2 flags2:2 uline_col:2 corner_col:2
                 other_port:1 res:5                                   > v2.A4
         Format: !|1B <wid> <hgt> <orient> <flags>
                 <bevsize> <dfore> <dback> <bright> <dark>
                 <surface> <grp_no> <flags2> <uline_col>
                 <corner_col> <other_port> <res>                      > v2.A4
        Example: !|1B0A0A010274030F080F080700010E07010A00
Uses Draw Color: NO
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO
Uses Font Style: NO
  Uses Viewport: NO                                                   > v1.54
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

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

There are 36 separate button style slots that can be defined          > v2.A4
simultaneously.  This command allows you to alter the current button  > v2.A4
style slot.  This button style slot is used by the RIP_BUTTON command > v2.A4
to define buttons of particular types.  Button style slots can be     > v2.A4
used to avoid retransmitting button styles over and over again.       > v2.A4

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

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

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



There are three basic "types" of Buttons.  There are Icon buttons,    > v1.54
Clipboard buttons and Plain buttons.  Each of these differ in the     > v1.54
way that they create the button's image.  A description of each type  > v1.54
is as follows:                                                        > v1.54

     ICON BUTTON (flag 128) - An Icon Button means that the           > v1.54
     actual image of the button will be created by loading a          > v1.54
     bitmap icon image from the disk and load it at the given         > v1.54
     locatino.  Any special effects (see below) can be applied        > v1.54
     to the Icon to further enhance the image.  The filename          > v1.54
     for the Icon is supplied with the RIP_BUTTON command, as         > v1.54
     is the Icon's upper left X/Y coordinate.  Icon Buttons           > v1.54
     are always stamped in COPY mode.                                 > v1.54

     CLIPBOARD BUTTON (flag 1) - A clipboard button uses the          > v2.A3
     clipboard port contents for the base image of                    > v2.A3
     the button.  If no <other_port> is defined (ie, port #0),        > v2.A3
     then the specific port that is used for the source image is      > v2.A3
     determined by the clipboard pointer.  If the clipboard pointer   > v2.A3
     isn't defined, then the RIP_BUTTON commandsd that follow are     > v2.A3
     ignored.  If the <other_port> is from 1-35, then this            > v2.A3
     specifies a previously defined port.  This port will be the      > v2.A3
     source of the bitmap image of the button.  The entire contents   > v2.A3
     of the port's viewport will be the image used for any            > v2.A3
     subsequent RIP_BUTTON commands.  If the given port doesn't       > v2.A3
     exist, then it the RIP_BUTTON command(s) are ignored.  Any       > v2.A3
     special effects can be applied to this image to further          > v2.A3
     enhance the overall button's image.                              > v2.A3

     PLAIN BUTTON (flag 256) - A plain button is exactly that,        > v1.54
     plain.  No special graphics are used to create the button.       > v1.54
     The entire button region is simply filled-in with a solid        > v1.54
     colored rectangle using the <surface> color.  Any                > v1.54
     special effects can be further applied to enhance the            > v1.54
     button's appearance.                                             > v1.54

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

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

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

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


NOTE: There are seven (7) color parameters in this command.           > v2.A0
      These parameters are ALWAYS used in Color Map mode.             > v2.A0
      Direct RGB Color Mode cannot be used for these                  > v2.A0
      parameters.  With Color Map mode, you have up to 256            > v2.A0
      separate color combinations possible for each color,            > v2.A0
      providing you with a great deal of flexibility.  The            > v2.A0
      color parameters always use the Base Math set by the            > v2.A0
      global Base Math setting.                                       > v2.A0

The <bright>, <dark> and <surface> parameters are used with Plain
Buttons and with the Special Effects styles (see <flags> below).
These colors represent the highlighted color, the shadowed color, and
the regular surface color that is used in Special Effects.  Typical
color combinations for these colors might be White, Dark-Gray and
Light-Gray respectively for a "chiseled steel" appearance.  Each of
these values can contain a two-digit value representing any valid
color code that may be used in the RIP_COLOR command.

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

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

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

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


Value Description of Flags Field #1       Icn  Clp  Pln  Mse  NoMse
───────────────────────────────────────────────────────────────────
    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 into Clipboard slot Y    Y    Y    Y     Y     > v2.A2
  128 Button is an "Icon Button"           Y    N    N    Y     Y
  256 Button is a "Plain Button"           N    N    Y    Y     Y
  512 Display Bevel special effect         Y    Y    Y    Y     Y
 1024 Button is a Mouse Button             Y    Y    Y    Y     N


 2048 Underline hot-key in label           Y    Y    Y    Y     N
 4096 Make Icon Button use Hot Icons       Y    N    N    Y     N
 8192 Adj. vertical centering of label     Y    Y    Y    Y     Y
16384 Button belongs to a Radio Group      Y    Y    Y    Y     N
32768 Display Sunken special effect        Y    Y    Y    Y     Y

The Icon Button, Clipboard button and Plain flags have already been   > v1.54
discussed.  Following, will be more discussion of the various flags   > v1.54
used in the preceding table:                                          > v1.54

     BUTTON IS INVERTABLE (flag 2) - This means that the button       > v1.54
     will be inverted when clicked.  This flag is only useful         > v1.54
     when combined with the "Button is a Mouse Button - flag          > v1.54
     1024) flag.  Even if the button has special effects, those       > v1.54
     will be inverted as well as they are considered part of          > v1.54
     the button - all except for the Recessed effect.  The            > v1.54
     recessed effect is NEVER considered part of the actual           > v1.54
     button image, and will never be part of the mouse field,         > v1.54
     button's image or anything - it is just extra graphics.          > v1.54

     RESET SCREEN AFTER BUTTON CLICK (flag 4) - This flag is          > v1.54
     used when the button is considered a Mouse Button (flag          > v1.54
     1024).  What this means is that when the user clicks on          > v1.54
     the button, the screen will be reset exactly the same            > v1.54
     as a RIP_RESET_WINDOWS command will do.  The reset is            > v1.54
     performed before the host command is processed (if any).         > v1.54

     DISPLAY CHISEL SPECIAL EFFECT (flag 8) - This displays           > v1.54
     a special effect on-top of the button image that gives           > v1.54
     the visual impression of an indented gutter just to the          > v1.54
     inside of the button's border.  The amount of indentation        > v1.54
     varies depending on the size of the button.  See below           > v1.54
     for a table of indentation values for the Chisel effect.         > v1.54

     DISPLAY RECESSED SPECIAL EFFECT (flag 16) - This places          > v1.54
     a recessed one-pixel bevel around the exterior of the            > v1.54
     button.  It is never considered part of the button's             > v1.54
     image.  Its purpose is to give the button a more 3D look         > v1.54
     by making it appear that the button is "poking through"          > v1.54
     a hole in a dialog box.  This effect is accomplished by          > v1.54
     placing a black outline (one pixel wide) around the              > v1.54
     exterior of the button's image (including bevel, etc),           > v1.54
     then placing a one-pixel wide inverted bevel around the          > v1.54
     black outline.                                                   > v1.54

     DROPSHADOW THE LABEL IF ANY (flag 32) - This flag will           > v1.54
     instruct RIPscrip to place a dropshadowed version of the         > v1.54
     text label one pixel to the right and one pixel lower            > v1.54
     than the original label.  This is accomplished by drawing        > v1.54
     the label first in the <dback> color, then drawing the           > v1.54
     label offset up-left in the <dfore>.                             > v1.54

     AUTO-STAMP IMAGE INTO CLIPBOARD SLOT (flag 64) - This option     > v2.A2
     is also known as "Auto-Clip".  What this means is right          > v1.54
     after the first button's image is rendered (including any        > v1.54
     special effects), it is automatically copied into another        > v2.A3
     port specified by the <other_port> parameter.  If that port      > v2.A3
     is defined as port #0, then this mode is treated like a          > v2.A3
     RIP_GET_IMAGE command, copying the image onto some clipboard     > v2.A3
     port, by determining the clipboard pointer and establishing      > v2.A3
     an offscreen bitmap port located at the first unused port        > v2.A3


     number.  If the <other_port> parameter is set to a value from    > v2.A3
     1-35, then a specific port number is used; that port is          > v2.A3
     deleted (if it's in use) then re-defined.  If the                > v2.A3
     <other_port> parameter specifies the same port as the            > v2.A3
     currently active drawing port, or if the clipboard pointer       > v2.A3
     points to the current drawing port, then auto-clip mode is       > v2.A3
     ignored.  The Recessed special effect is not considered          > v2.A3
     part of the button image for this flag and is not made           > v1.54
     part of the clipboard image.  After the image is copied          > v1.54
     into a clipboard port, the label is drawn (this is so that       > v2.A3
     the label is not placed into a clipboard port), then a           > v2.A3
     number of flags in the current Button Style definition           > v1.54
     are altered.  Specifically, the Icon and Plain flags are         > v1.54
     disabled, and Clipboard button enabled (thus making any          > v1.54
     subsequent buttons use the resultant Clipboard button            > v1.54
     image for their button's representation).  In addition,          > v1.54
     the chisel, bevel, auto-clip and sunken flags are                > v1.54
     disabled.  The final result is a Clipboard button with           > v1.54
     no special effects other than the Recessed effect (if            > v1.54
     any).  This is most often used with Icon Buttons where           > v1.54
     every subsequent button uses the same Icon over and over         > v1.54
     again - the net result of this is less "disk usage"              > v2.A3
     whenever a button is created; in addition, buttons will          > v1.54
     draw faster too.  If this option is used, then the               > v2.A0
     parameter <other_port> is used to determine which                > v2.A3
     clipboard port to use for the stored image.                      > v2.A3

     BUTTON IS AN ICON BUTTON (flag 128) - See previous               > v1.54
     discussions on button types above.                               > v1.54

     BUTTON IS A PLAIN BUTTON (flag 256) - See previous               > v1.54
     discussions on button types above.                               > v1.54

     DISPLAY BEVEL SPECIAL EFFECT (flag 512) - When this flag         > v1.54
     is active, a bevel will be drawn <size> pixels thick on          > v1.54
     the outside of the base image of the button.  This makes         > v1.54
     the button that many pixels wider and taller in each             > v1.54
     direction.  See the RIP_BUTTON for a more detailed               > v1.54
     description of the affects of the button's final size.           > v1.54

     BUTTON IS A MOUSE BUTTON (flag 1024) - When this flag is         > v1.54
     enabled, the button becomes a clickable mouse region.            > v1.54
     When this option is in use, the Invert flag and several          > v1.54
     others are available (see the preceding chart).  When            > v1.54
     a button is a non-mouse button, then it is only used to          > v1.54
     draw a dialog box or an elaborate "static graphic" image         > v1.54
     of something that "looks" like a button.                         > v1.54

     UNDERLINE HOT-KEYS IN LABEL (flag 2048) - When this              > v1.54
     flag is active, the first occurence of the hot-key               > v1.54
     character in the button's label will be underlined using         > v1.54
     the <uline_col> color.  Special care must be taken when          > v1.54
     underlining the character, taking into consideration if          > v1.54
     the character has a segment that goes below the "baseline"       > v1.54
     of the font.  Consult the following section to determine         > v1.54
     what ASCII characters have these "descenders".  Characters       > v1.54
     with descenders have the underline drawn slightly lower          > v1.54
     than for characters without them.                                > v1.54



     MAKE ICON BUTTON USE HOT ICONS (flag 4096) - A Hot Icon          > v1.54
     is a button that has an alternative image when the button        > v1.54
     is "depressed".  Normally, when a button is an Icon              > v1.54
     button, some form of Icon File is used to create the image       > v1.54
     of the button (eg, EMAIL.BMP).  When the Hot Icon flag is        > v2.A1
     in use, whenever that button is depressed, rather than           > v1.54
     using the normal Icon File for the button's image, a             > v1.54
     different Icon File is used for the button's image.  The         > v1.54
     filename would be the same filename as the original Icon,        > v1.54
     but with an extension of .BMH instead of .BMP.  When Hot         > v2.A2
     Icon is in use, the alternative Icon is stamped in COPY          > v1.54
     mode.  If the file does not exist, then the original             > v1.54
     Icon's image is used, but pasted in NOT mode for the             > v1.54
     duration of the depression.                                      > v1.54

     ADJ. VERTICAL CENTERING OF LABEL (flag 8192) - Some Labels       > v1.54
     may appear non-centered vertically when drawn using some         > v1.54
     fonts that are rather large.  With this in mind, you have        > v1.54
     the option to adjust the vertical centering.  What this          > v1.54
     does is take into consideration the height of any                > v1.54
     descenders of the label and calculate those into the             > v1.54
     overall height of the label before centering.  If this           > v1.54
     flag is not used, then the descenders are not taken into         > v1.54
     consideration when the vertical centering is calculated.         > v1.54
     See the Font Metric tables below for more detailed               > v1.54
     information on font sizes and their associated metrics.          > v1.54
     This command has no effect if the Label orientation is           > v1.54
     LEFT or RIGHT of the button.  It only applies to an              > v1.54
     orientation of TOP, BOTTOM or CENTER.                            > v1.54

     BUTTON BELONGS TO A RADIO GROUP (flag 16384) - When this         > v1.54
     flag is used, then any buttons defined in this button            > v1.54
     <group_no> are considered to be radio buttons where only         > v1.54
     one of the buttons can be clicked (selected) at any              > v1.54
     particular time.  If a button is not a radio button or           > v1.54
     a checkbox button, then the "selected" flag of the               > v1.54
     RIP_BUTTON command is ignored.  When a Radio Button is           > v1.54
     clicked, any other radio button in that button group that        > v1.54
     is selected is automatically de-selected and the current         > v1.54
     one selected.  Any host command is processed at the time         > v1.54
     of the button click.  If a Radio Button is drawn initally        > v1.54
     as selected, then that host command is processed at the          > v1.54
     time of its initial drawing.  See the section near the           > v1.54
     end of this document discussing TEMPLATES for a more             > v1.54
     complete description of Radio Buttons and how they               > v1.54
     interact with their Button Group and with each other.            > v1.54

     DISPLAY SUNKEN SPECIAL EFFECT (flag 32768) - When this           > v1.54
     option is enabled, a one-pixel inverted bevel is drawn           > v1.54
     exactly one pixel to the inside of the base image of the         > v1.54
     button.  This and the chisel effect are the only two             > v1.54
     special effects which physically "overwrite" portions of         > v1.54
     the base button image.                                           > v1.54

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



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

NOTE:  The low_char[] table is only truly useful under ENG            > v2.A3
       configurations for the text window.  Other languages may       > v2.A3
       have descenders for other characters.                          > v2.A3

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

The METRIC structure can be described visually as follows:

      0 ──╔══════════╤══════════╗   Notice that the topmost scanline
          ║          │          ║   of a font cell is not necessarily
     TOP──╫─█────────┼──────────╢   the top of the character.  The
          ║ █        │          ║   "top" field of the structure
          ║ █        │          ║   contains the vertical offset
          ║ █        │          ║   from the top of the cell for all
     BOW──╫─█────────┼──────────╢   fonts in that set.
          ║ █ ███    │   ███ █  ║
          ║ ██   █   │  █   ██  ║
          ║ █     █  │ █     █  ║
          ║ █     █  │ █     █  ║
          ║ █     █  │ █     █  ║
          ║ █     █  │  █   ██  ║
    BASE──╫─█─────█──┼───███─█──╢
          ║          │       █  ║
          ║          │       █  ║
          ║          │       █  ║
          ║          │  █   █   ║
    DROP──╫──────────┼───███────╢
          ║          │          ║
    END ──╚══════════╧══════════╝



╔════════════════════════════════╗   ╔════════════════════════════════╗
║     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 │  68 │ 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 │  18  │  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  ║  44 │  72 │ 128  │ 156  ║
╚══════╩═════╧═════╧══════╧══════╝   ╚══════╩═════╧═════╧══════╧══════╝


╔════════════════════════════════╗   ╔════════════════════════════════╗
║      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  │  81  ║
║   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  ║  64 │ 112 │ 148  │ 196  ║
╚══════╩═════╧═════╧══════╧══════╝   ╚══════╩═════╧═════╧══════╧══════╝



╔════════════════════════════════╗   ╔════════════════════════════════╗
║     Simplex Font (Font 6)      ║   ║  Triplex Script Font (Font 7)  ║
╟──────╥─────┬─────┬──────┬──────╢   ╟──────╥─────┬─────┬──────┬──────╢
║ Size ║ Top │ Bow │ Base │ Drop ║   ║ Size ║ Top │ Bow │ Base │ Drop ║
╠══════╬═════╪═════╪══════╪══════╣   ╠══════╬═════╪═════╪══════╪══════╣
║   1  ║   8 │  13 │  21  │  25  ║   ║   1  ║   6 │  10 │  18  │  22  ║
║   2  ║   9 │  14 │  23  │  27  ║   ║   2  ║   6 │  11 │  20  │  24  ║
║   3  ║  10 │  16 │  26  │  31  ║   ║   3  ║   8 │  13 │  23  │  28  ║
║   4  ║  13 │  21 │  35  │  42  ║   ║   4  ║  10 │  17 │  31  │  38  ║
║   5  ║  17 │  28 │  46  │  55  ║   ║   5  ║  13 │  23 │  41  │  50  ║
║   6  ║  22 │  35 │  58  │  69  ║   ║   6  ║  16 │  28 │  51  │  62  ║
║   7  ║  26 │  42 │  70  │  84  ║   ║   7  ║  20 │  34 │  62  │  76  ║
║   8  ║  32 │  52 │  87  │ 104  ║   ║   8  ║  25 │  42 │  77  │  94  ║
║   9  ║  39 │  63 │ 105  │ 126  ║   ║   9  ║  30 │  51 │  93  │ 114  ║
║  10  ║  52 │  84 │ 140  │ 168  ║   ║  10  ║  40 │  68 │ 124  │ 152  ║
╚══════╩═════╧═════╧══════╧══════╝   ╚══════╩═════╧═════╧══════╧══════╝


╔════════════════════════════════╗   ╔════════════════════════════════╗
║     Complex Font (Font 8)      ║   ║     European Font (Font 9)     ║
╟──────╥─────┬─────┬──────┬──────╢   ╟──────╥─────┬─────┬──────┬──────╢
║ Size ║ Top │ Bow │ Base │ Drop ║   ║ Size ║ Top │ Bow │ Base │ Drop ║
╠══════╬═════╪═════╪══════╪══════╣   ╠══════╬═════╪═════╪══════╪══════╣
║   1  ║   9 │  13 │  21  │  25  ║   ║   1  ║   8 │  15 │  33  │  39  ║
║   2  ║   9 │  14 │  23  │  27  ║   ║   2  ║   8 │  16 │  36  │  42  ║
║   3  ║  11 │  16 │  26  │  31  ║   ║   3  ║  10 │  19 │  41  │  48  ║
║   4  ║  14 │  21 │  35  │  42  ║   ║   4  ║  13 │  25 │  55  │  65  ║
║   5  ║  18 │  28 │  46  │  55  ║   ║   5  ║  16 │  33 │  73  │  86  ║
║   6  ║  23 │  35 │  58  │  69  ║   ║   6  ║  21 │  41 │  91  │ 107  ║
║   7  ║  28 │  42 │  70  │  84  ║   ║   7  ║  26 │  50 │ 110  │ 130  ║
║   8  ║  35 │  52 │  87  │ 104  ║   ║   8  ║  32 │  62 │ 137  │ 162  ║
║   9  ║  42 │  63 │ 105  │ 126  ║   ║   9  ║  39 │  75 │ 165  │ 195  ║
║  10  ║  56 │  84 │ 140  │ 168  ║   ║  10  ║  52 │ 100 │ 220  │ 260  ║
╚══════╩═════╧═════╧══════╧══════╝   ╚══════╩═════╧═════╧══════╧══════╝


╔════════════════════════════════╗
║      Bold Font (Font 10)       ║
╟──────╥─────┬─────┬──────┬──────╢
║ Size ║ Top │ Bow │ Base │ Drop ║
╠══════╬═════╪═════╪══════╪══════╣
║   1  ║  12 │  18 │  36  │  40  ║
║   2  ║  14 │  20 │  40  │  44  ║
║   3  ║  15 │  23 │  45  │  50  ║
║   4  ║  20 │  30 │  60  │  67  ║
║   5  ║  27 │  40 │  80  │  89  ║
║   6  ║  34 │  50 │ 100  │ 111  ║
║   7  ║  40 │  60 │ 120  │ 134  ║
║   8  ║  50 │  75 │ 150  │ 167  ║
║   9  ║  60 │  90 │ 180  │ 201  ║
║  10  ║  80 │ 120 │ 240  │ 268  ║
╚══════╩═════╧═════╧══════╧══════╝

NOTE:  The above metric tables are based on 640x350 resolutions.  For > v2.A3
       information on font scaling at other resolutions for the       > v2.A3
       "system fonts" defined via the RIP_FONT_STYLE command, see     > v2.A3
       the preceding section for the RIP_FONT_STYLE command.  This    > v2.A3
       section defines the magnification factors for each font and    > v2.A3
       how they relate to other resolutions.                          > v2.A3


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

   [BEGIN REWORD]

     <<< Think about resolution independence of chisel indent. >>>
     <<< Talk about bevel sizes too, along with recesses.      >>>

   [END REWORD]

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

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

Following is a more complete description of the flags described in    > v1.54
the <flags2> parameter:                                               > v1.54

     BUTTON IS IN A CHECK BOX GROUP (flag 1) - When this flag is      > v1.54
     selected, then the button <group_no> is considered a Check-      > v1.54
     box group.  When in this mode, the Radio Group flag is not       > v1.54
     accessible - A Button Group can be a Radio Button, a Check-      > v1.54
     box button or neither, but not more than one at the same         > v1.54
     time.  A Check-box button group is a group of buttons where      > v1.54
     each button in the group can be either ON or OFF in any          > v1.54
     combination.  In this way, more than one button in the           > v1.54
     group can be clicked at the same time.  See the TEMPLATES        > v1.54
     section later on in this document for a complete discussion      > v1.54
     of how the Host Commands are processed for Check-Box buttons.    > v1.54
     If a check-box button is drawn as "pre-selected", then the       > v1.54
     Host Command is processed immediately upon inital drawing of     > v1.54
     the button (when it is received).                                > v1.54

     HIGHLIGHT HOTKEY CHARACTER (flag 2) - When this flag is          > v1.54
     active, then the first occurence of the hotkey character         > v1.54
     in the label will be hilighted using the <uline_col> color.      > v1.54
     This gives the user a visual impression of what keystroke        > v1.54
     they need to type in order to activate the button without        > v1.54
     the mouse.                                                       > v1.54


     EXPLODE (ZOOM OUT WHEN CLICKED) (flag 4) - This optional         > v1.54
     flag is designed to "zoom out" from the button when the          > v1.54
     user clicks on it.  What is generally done is a dotted           > v1.54
     rectangle is drawn initially around the button and it is         > v1.54
     repeatedly redrawn over itself in XOR mode, constantly           > v1.54
     getting larger and larger until it hits the full size of         > v1.54
     the screen.  This gives the visual impression that the           > v1.54
     button is zooming out to another screen.  Each time another      > v1.54
     frame of the zooming rectangle is drawn, the previous            > v1.54
     rectangle on the inside of the new one is erased by XOR          > v1.54
     drawing the same rectangle over itself again.  This option       > v1.54
     does not need to be supported in order to be considered          > v1.54
     a RIPscrip terminal, although it would be nice.  In              > v1.54
     other words, this is not a "make or break" feature.              > v1.54

     LEFT JUSTIFY LABEL (TOP/CTR/BTM) (flag 8) - If this option       > v1.54
     is enabled, then any TOP, CENTER or BOTTOM label orientations    > v1.54
     will be left justified to the left edge of the button.  The      > v1.54
     exact indentation of the label from the interior of the          > v1.54
     button's base image depends on whether the chisel effect         > v1.54
     is active.  If chisel is OFF, then the indentation is 10         > v1.54
     pixel.  If chisel is ON, then the indentation is 20 pixels.      > v1.54
     This option can be combined with the Adjust Vertical Centering   > v1.54
     flag only if the label orientation is CENTER.                    > v1.54

     RIGHT JUSTIFY LABEL (TOP/CTR/BTM) (flag 16) - If this option     > v1.54
     is enabled, then any TOP, CENTER or BOTTOM label orientations    > v1.54
     will be right justified to the right edge of the button.  The    > v1.54
     exact indentation of the label from the interior of the          > v1.54
     button's base image depends on whether the chisel effect         > v1.54
     is active.  If chisel is OFF, then the indentation is 10         > v1.54
     pixel.  If chisel is ON, then the indentation is 20 pixels.      > v1.54
     This option can be combined with the Adjust Vertical Centering   > v1.54
     flag only if the label orientation is CENTER.                    > v1.54

     DON'T FILL-IN BUTTON INTERIOR - If this option is enabled and    > v2.A0
     the button is a Plain Button, then the interior of the Button    > v2.A0
     will not be filled in with the surface color.  By default,       > v2.A0
     any plain button will have its interior filled in with the       > v2.A0
     surface color.  Use this option if you don't want the button     > v2.A0
     face to be drawn.                                                > v2.A0

     FILL-IN INTERIOR IN FILL PATTERN - If this option is enabled     > v2.A0
     in conjunction with a plain button, then the interior of the     > v2.A0
     button that would normally be filled in with the surface         > v2.A0
     color will instead, use the current Fill Color and Fill          > v2.A0
     Pattern to fill in the interior.  This allows for patterned      > v2.A0
     button faces.                                                    > v2.A0



┌─────────────────────────┐
│ 3.4.2.4 ■ RIP_COPY_BLIT │
└─────────────────────────┘

       Function: Copy a screen area to a new location (bit blit)      > v2.A1
          Level: 1                                                    > v2.A1
        Command: g                                                    > v2.A1
      Arguments: x0:2 y0:2 x1:2 y1:2 dx0:2 dy0:2 mode:1 res:1         > v2.A1
         Format: !|1g <x0> <y0> <x1> <y1> <dx0> <dy0> <mode> <res>    > v2.A1
        Example: !|1g080G140M112230                                   > v2.A1
Uses Draw Color: YES                                                  > v2.A1
Uses Back Color: YES                                                  > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: YES                                                  > v2.A2
Uses Write Mode: NO                                                   > v2.A1
Uses Font Style: NO                                                   > v2.A1
  Uses Viewport: NO                                                   > v2.A1
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

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

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

     Mode  Description                                                > v2.A1
     ─────────────────────────────────────────────────────────────    > v2.A1
       0   Do nothing - leave the old graphics on the screen          > v2.A1
       1   Fill the old graphical area with the current drawing       > v2.A1
           color (solid fill in COPY mode).                           > v2.A1
       2   Fill the old graphical area with the current background    > v2.A1
           drawing color (solid fill in COPY mode).                   > v2.A1
       3   Fill the area with the current fill color (solid fill in   > v2.A1
           COPY mode).  Fill pattern/styles are not used for this.    > v2.A1
       4   Fill the old graphical area with the current fill          > v2.A1
           style/pattern in the current fill color.                   > v2.A1
       5   Erase the affected area entirely to black.                 > v2.A1



┌──────────────────────┐
│ 3.4.2.5 ■ RIP_DEFINE │
└──────────────────────┘

       Function: Define a text variable
          Level: 1
        Command: D
      Arguments: flags:3 res:2 text
         Format: !|1D <flags> <res> <text>
        Example: !|1D00700text_var,60:?question?default data
Uses Draw Color: NO
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO
Uses Font Style: NO
  Uses Viewport: NO                                                   > v1.54
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

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

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

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

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

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

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


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

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

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

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

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

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

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

                    ?this is a question?

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

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

       THIS COMMAND IS NOW OBSOLETE.  USE THE SPECIALLY ENHANCED      > v2.A1
       TEXT VARIABLE SYSTEM WITHIN QUERIES OR HOST COMMANDS TO        > v2.A1
       PRODUCE THE SAME RESULTS AS THIS COMMAND AND MUCH MORE!        > v2.A1



┌────────────────────────┐
│ 3.4.2.6 ■ RIP_END_TEXT │
└────────────────────────┘

       Function: End a rectangular text region
          Level: 1
        Command: E
      Arguments: <none>
         Format: !|1E
        Example: !|1E
Uses Draw Color: NO
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO
Uses Font Style: NO
  Uses Viewport: YES                                                  > v1.54
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: N/A                                                  > v2.A2

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



┌──────────────────────────┐
│ 3.4.2.7 ■ RIP_FILE_QUERY │
└──────────────────────────┘

       Function: Query existing information on a particular file
          Level: 1
        Command: F
      Arguments: mode:2 res:4 filename...
         Format: !|1F <mode> <res> <filename>
        Example: !|1F010000testfile.icn
Uses Draw Color: NO
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO
Uses Font Style: NO
  Uses Viewport: NO                                                   > v1.54
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

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.



┌─────────────────────────┐
│ 3.4.2.8 ■ RIP_GET_IMAGE │
└─────────────────────────┘

       Function: Copy rectangular image to the clipboard port         > v2.A3
          Level: 1
        Command: C
      Arguments: x0:XY y0:XY x1:XY y1:XY res:1                        > v2.A3
         Format: !|1C <x0> <y0> <x1> <y1> <res>                       > v2.A3
        Example: !|1C001122330
Uses Draw Color: NO
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO
Uses Font Style: NO
  Uses Viewport: YES                                                  > v1.54
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

This command instructs the terminal program to copy a rectangular     > v2.A3
region defined by (x0,y0) to (x1,y1) in the currently active          > v2.A3
drawing port to the first offscreen port found after port #0 (the     > v2.A3
screen port).  If no offscreen port is actually found, then the       > v2.A3
first empty port slot is used; the slot is defined as an offscreen    > v2.A3
bitmap port and is initialized to the dimensions of the source        > v2.A3
rectangle used in this command.  If an offscreen bitmap port is       > v2.A3
found, then it is deleted and re-initialized based on the dimensions  > v2.A3
of this command.  Once the offscreen bitmap port is initialized, the  > v2.A3
contents of the source rectangle are copied to the port, occupying    > v2.A3
the entire contents of the port.  If the port number that is found    > v2.A3
corresponds to the source port, then this command does nothing.       > v2.A3

In older versions of RIPscrip (v1.54 and earlier), there was only     > v2.A3
the screen and one offscreen bitmap port (the clipboard).  Under 2.0, > v2.A3
you may have multiple offscreen bitmap ports (or clipboards).  There  > v2.A3
are three commands from RIPscrip 1.54 that pertain directly to the    > v2.A3
concept of a clipboard (RIP_GET_IMAGE, RIP_PUT_IMAGE and              > v2.A3
RIP_WRITE_ICON).  To facilitate the integration of these commands in  > v2.A3
the architecture of RIPscrip 2.0, a clipboard pointer is used.  The   > v2.A3
clipboard pointer is created with the RIP_GET_IMAGE command is used.  > v2.A3
When this command is executed, the software will scan from port #1    > v2.A3
to port #35 (port #0 is skipped because it's the screen).  It         > v2.A3
searches for the first open (unused) port.  Once found, the           > v2.A3
clipboard pointer is set to point to this port.  This allows the      > v2.A3
RIP_PUT_IMAGE and RIP_WRITE_ICON command to know which port number    > v2.A3
is associated with the clipboard.                                     > v2.A3

When a RIP_RESET_WINDOWS command is executed, the contents of the     > v2.A3
port table are cleared and the clipboard pointer is cleared (ie,      > v2.A3
no clipboard exists after the operation is complete).                 > v2.A3

If the offscreen port cannot be defined for whatever reason, then     > v2.A3
this command is not processed.  The only thing that will be           > v2.A3
accomplished in this case is that the clipboard pointer will be       > v2.A3
cleared and no clipboard data will exist.                             > v2.A3

See the RIP_DEFINE_PORT command for more details about offscreen      > v2.A3
ports and the size limitations of them.                               > v2.A3



┌─────────────────────┐
│ 3.4.2.9 ■ RIP_IMAGE │
└─────────────────────┘

       Function: Display a scalable photo type image                  > v2.A0
          Level: 1                                                    > v2.A1
        Command: p                                                    > v2.A1
      Arguments: res:4 filename                                       > v2.A0
         Format: !|1p <res> <filename>                                > v2.A1
        Example: !|1p0000filename.jpg                                 > v2.A1
Uses Draw Color: NO                                                   > v2.A0
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: YES                                                  > v2.A3
Uses Font Style: NO                                                   > v2.A0
  Uses Viewport: YES                                                  > v2.A0
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

This command will physically take a JPEG image file that is           > v2.A1
located on the remote terminal's hard disk (like Icon files) and      > v2.A0
display it in the image area set by a RIP_IMAGE_STYLE command.        > v2.A0
See the RIP_IMAGE_STYLE command for more details on the options       > v2.A0
available to set for image viewing and manipulation.                  > v2.A0



┌────────────────────────────┐
│ 3.4.2.10 ■ RIP_IMAGE_STYLE │
└────────────────────────────┘

       Function: Alter subsequent displayed image settings            > v2.A0
          Level: 1                                                    > v2.A1
        Command: i                                                    > v2.A0
      Arguments: x0:XY y0:XY x1:XY y1:XY flags:4 res:12               > v2.A2
         Format: !|1i <x0> <y0> <x1> <y1> <flags> <res>               > v2.A1
        Example: !|1i00008G5B0002000000000000                         > v2.A1
Uses Draw Color: NO                                                   > v2.A0
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO                                                   > v2.A0
Uses Font Style: NO                                                   > v2.A0
  Uses Viewport: YES                                                  > v2.A0
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

This command alters the settings for subsequently received (or        > v2.A0
displayed) image files.  RIPscrip supports the display of JPEG (Joint > v2.A0
Photographic Experts Group) files.  These files can be transmitted to > v2.A1
the remote terminal and viewed. The <x0>, <y0>, <x1> and <y1>         > v2.A1
parameters determine the size of the image area in the current        > v2.A1
viewport.                                                             > v2.A1

If the <x0>, <y0>, <x1> and <y1> parameters are all set to zero (0),  > v2.A0
then Image Viewing is disabled.  Any explicitly viewed images, or any > v2.A0
images received with RIP_ENTER_BLOCK_MODE will be ignored (however    > v2.A0
they will be deleted if flag 4 or 8 are active - see below).          > v2.A0

If the image view area is larger than the current viewport size, then > v2.A0
the image area size will be adjusted according to the viewport's      > v2.A0
current size to fit.                                                  > v2.A3

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

There is a <flags> parameter which alters some of the aspects of the  > v2.A0
image being displayed.  These flags can be OR'd together to create a  > v2.A0
combination of various flag values.  The possible flags are:          > v2.A0

  Value  Description                                                  > v2.A0
  ────────────────────────────────────────────────────────────────    > v2.A0
      1  Maintain image aspect ratio - This will keep the image       > v2.A0
         maintained in size no matter what the size of the display    > v2.A0
         region is.  If the region isn't perfectly proportioned       > v2.A0
         in relation to the actual bitmap, then areas of the          > v2.A0
         display region above and below the image will be blacked     > v2.A0
         out (a margin), or possibly left and right depending on      > v2.A1
         proportions of the bitmap.  This will yield a visually       > v2.A1
         accurate representation of the image.                        > v2.A1

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


      4  Do not clear the image area to the current background        > v2.A3
         color before viewing the image.                              > v2.A3

      8  Commit the color palette of the image (if any) to the        > v2.A4
         actual video hardware/color lookup table.  This is typically > v2.A4
         only of use when using the image style with GIF files.  This > v2.A4
         flag is ignored with JPEGs.  When active, any color palette  > v2.A4
         in the image file to be displayed is used to alter the       > v2.A4
         current video color system to make the image show up as      > v2.A4
         close to the original image as possible.                     > v2.A4

If no RIP_IMAGE_STYLE command is processed before a JPEG image is to  > v2.A3
be displayed, then the image area is defined to be the full size of   > v2.A3
the viewport in whatever port is currently active.  When a            > v2.A3
RIP_RESET_WINDOWS or a RIP_HEADER command is received (ie, the        > v2.A3
environment is reset), then the image area is also reset to the       > v2.A3
maximum size of the current viewport.                                 > v2.A3



┌───────────────────────────────────────────┐
│ 3.4.2.11 ■ RIP_KILL_ENCLOSED_MOUSE_FIELDS │
└───────────────────────────────────────────┘

       Function: Destroys any Mouse Fields inside a region            > v2.A0
          Level: 1                                                    > v2.A0
        Command: k                                                    > v2.A0
      Arguments: x0:XY y0:XY x1:XY y1:XY flags:4                      > v2.A2
         Format: !|1k <x0> <y0> <x1> <y1> <flags>                     > v2.A3
        Example: !|1k00003G2H                                         > v2.A0
Uses Draw Color: NO                                                   > v2.A0
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: YES (see below)                                      > v2.A2
Uses Write Mode: NO                                                   > v2.A0
Uses Font Style: NO                                                   > v2.A0
  Uses Viewport: NO                                                   > v2.A0
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

This command will destroy any Mouse Fields or Mouse Active Buttons    > v2.A0
that are contained inside the given rectangle or that intersect the   > v2.A0
rectangle.  The exact operation of this function is dependent on the  > v2.A0
setting of the <flags> parameter.  The <flags> parameter can combine  > v2.A0
any of the following flags to determine the exact mode of operation:  > v2.A0

  FLAGS   DESCRIPTION                                                 > v2.A0
  ════════════════════════════════════════════════════════════════    > v2.A0
          Region Specific Flags                                       > v2.A0
          ────────────────────────────────────────────────────────    > v2.A0
      1   Kill only fields completely contained (non-intersecting)    > v2.A4
      2   Kill only fields that intersect bounding rectangle          > v2.A4
      4   Kill fields entirely outside bounding rectangle             > v2.A4

           > If 1, 2 and 4 are not present, then NO fields            > v2.A4
           > are deleted.  One of these flags must be supplied        > v2.A4
           > for any mouse fields to be deleted.                      > v2.A0

          What Types of Fields not to Destroy                         > v2.A4
          ──────────────────────────────────────────────────          > v2.A0
      8   Don't destroy simple Mouse Fields                           > v2.A4
     16   Don't destroy active Mouse Button fields                    > v2.A4

           > If 8 and 16 are not present, then all types              > v2.A4
           > of mouse fields are destroyed.                           > v2.A0

          What to do With the Affected Region(s)                      > v2.A0
          ──────────────────────────────────────────────────          > v2.A0
     32   Clear the affected field(s) to black (color 0)              > v2.A0
     64   Fill the affected field(s) with current fill color          > v2.A0
          and fill pattern (64 overides 32 in the case that           > v2.A4
          both of 32 and 64 are present).                             > v2.A4

    128   Perform the 32/64 operations on the whole bounding          > v2.A0
          rectangle (based on Region Specific Flags).                 > v2.A0

           > If 128 is omitted but 32 or 64 are used,                 > v2.A4
           > then the mouse field's affected are                      > v2.A4
           > cleared with the appropriate method.                     > v2.A0
           > If 128 is present as well, then instead                  > v2.A0
           > of clearing the individual mouse fields                  > v2.A0


           > with the given method, the entire region                 > v2.A0
           > specified by the Region Specific Flags                   > v2.A0
           > is affected (ie, the entire interior                     > v2.A4
           > of the bounding rectangle is cleared,                    > v2.A0
           > etc).  If 32, 64 and 128 are omitted, then               > v2.A4
           > the affected region/fields are left on                   > v2.A0
           > the screen visually, but their mouse                     > v2.A0
           > field definitions are destroyed internally.              > v2.A0
           > If 128 is used, but 32 and 64 are omitted then           > v2.A4
           > nothing is done visually either.                         > v2.A4



┌──────────────────────────────────┐
│ 3.4.2.12 ■ RIP_KILL_MOUSE_FIELDS │
└──────────────────────────────────┘

       Function: Destroys all previously defined hot mouse regions
          Level: 1
        Command: K
      Arguments: <none>
         Format: !|1K
        Example: !|1K
Uses Draw Color: NO
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO
Uses Font Style: NO
  Uses Viewport: NO                                                   > v1.54
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: N/A                                                  > v2.A2

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.



┌────────────────────────────┐
│ 3.4.2.13 ■ RIP_LOAD_BITMAP │
└────────────────────────────┘

       Function: Loads and displays a disk-based bitmap to screen     > v2.A1
          Level: 1                                                    > v2.A1
        Command: b                                                    > v2.A1
      Arguments: x0:XY y0:XY x1:XY y1:XY duplicate_port:1 mode:1      > v2.A3
                 flags:2 trans_color:2 res:4 filename                 > v2.A4
         Format: !|1b <x0> <y0> <x1> <y1> <duplicate_port> <mode>     > v2.A4
                 <flags> <trans_color> <res> <filename>               > v2.A4
        Example: !|1b001122330100000000button                         > v2.A4
Uses Draw Color: NO                                                   > v2.A1
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO                                                   > v2.A1
Uses Font Style: NO                                                   > v2.A1
  Uses Viewport: YES                                                  > v2.A1
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

This command is nearly identical in nature to the RIP_LOAD_ICON       > v2.A1
command but it is more flexible in that it supports arbitrary scaling > v2.A3
of the bitmap to the destination screen and it supports dithering     > v2.A1
methods.  It can be made to exactly match the RIP_LOAD_ICON command.  > v2.A1

This command instructs the terminal to read a bitmap from disk and    > v2.A3
display it at the given upper-left (x0,y0) location.  If the (x1,y1)  > v2.A1
values are non-zero, then it specifies the lower-right corner on the  > v2.A1
screen for the bitmap's display region.  If the bitmap differs in     > v2.A3
size than the destination rectangle, then it is scaled (stretched) to > v2.A3
fit into the proper region.  If the values of X1 and Y1 are zero,     > v2.A3
then the bitmap is shown verbatim in whatever resolution of the       > v2.A1
disk based file (this is more like the RIP_LOAD_ICON command above).  > v2.A1

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

If the width or height of the Icon would make it go off the right or  > v2.A1
bottom edge of the viewport, the bitmap will be clipped.  The <mode>  > v2.A1
parameter defines the modes in which the Icon will be displayed on    > v2.A1
the screen.  The modes are identical to the RIP_PUT_IMAGE and the     > v2.A3
RIP_LOAD_ICON commands, and are as follows:                           > v2.A3

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

The <flags> parameter contains important bit-field values that can be
OR'd together to produce a number of desired operations.  The
possible flag values are:



  Value   Description                                                 > v2.A4
  ─────────────────────────────────────────────────────────────────── > v2.A4
     1   Load the image onto the port and make a copy to another      > v2.A4
         port.  This is used to make a carbon copy of the image once  > v2.A4
         it is placed onto the active drawing port.  This means that  > v2.A4
         after any color palette manipulation, dithering and viewport > v2.A4
         clipping, the final image is copied to some other drawing    > v2.A4
         port as a type of backup copy.  This is often used to make   > v2.A4
         high-speed copies of the same image without having to        > v2.A4
         continually access the disk in order to load the image over  > v2.A4
         and over again.  If this flag is specified, then the         > v2.A4
         <duplicate_port> parameter determines which port number will > v2.A4
         receive the loaded image.  If you specify a value of 0 for   > v2.A4
         the duplicate port number, then it will act like the         > v2.A4
         RIP_LOAD_ICON command's clipboard mode - it loads the image  > v2.A4
         onto the clipboard port specified by the clipboard pointer,  > v2.A4
         or if the pointer hasn't been used yet, then it places the   > v2.A4
         image on a newly created offscreen bitmap port located in    > v2.A4
         the first unused port number.  The offscreen port will be    > v2.A4
         redefined with the new bitmap's dimensions.  If the          > v2.A4
         <duplicate_port> parameter specifies a value from 1-35, then > v2.A4
         it indicates a specific port number.  That port, if it       > v2.A4
         doesn't exist, will be defined as an offscreen bitmap port   > v2.A4
         with the exact same dimensions as the final bitmap.  If it   > v2.A4
         does exist, then the port is deleted (even if it's a         > v2.A4
         screen-port) and redefined as an offscreen bitmap port with  > v2.A4
         the new bitmap's dimensions.  After the duplicate port is    > v2.A4
         defined, the image is copied to it.  If the current drawing  > v2.A4
         port happens to be the same port used for the duplicate      > v2.A4
         port, then this flag is ignored.  If this flag is omitted,   > v2.A4
         then no duplicate copy is made of the image and the          > v2.A4
         <duplicate_port> parameter of this command is ignored.       > v2.A4

     2   This flag indicates to take the color palette in the bitmap  > v2.A4
         file and activate it in the current color lookup table.      > v2.A4
         This means that the color palette in the bitmap is copied    > v2.A4
         into the video device's color palette (and into RIPscrip's). > v2.A4
         This means that if any graphics are already on the screen    > v2.A4
         when this happens, they might change in color as soon as     > v2.A4
         the bitmap is loaded (this is due to the fact that the       > v2.A4
         color palette is changed).  If the number of colors in the   > v2.A4
         bitmap exceeds the number of colors in the active display    > v2.A4
         device, then the actual color palette in use is used for the > v2.A4
         bitmap instead of the internal bitmap palette.  If the       > v2.A4
         number of colors in the bitmap is equal or less than the     > v2.A4
         number of colors for the active video mode then the image    > v2.A4
         will be displayed exactly as it was intended.  If this is    > v2.A4
         the case, then no dithering is necessary on the image so     > v2.A4
         the dither flag (see below) parameter is ignored.  If the    > v2.A4
         terminal is running in a mode that doesn't allow for a color > v2.A4
         palette in the video hardware, then dithering is ignored and > v2.A4
         the color palette inside the bitmap file is ignored - this   > v2.A4
         is because the system is already running in a 32K, 64K or    > v2.A4
         24-bit color mode and there are more than plenty colors to   > v2.A4
         represent the bitmap perfectly.                              > v2.A4

         If this flag is omitted, then the bitmap will use the        > v2.A4
         current screen's color palette.  Typically this will be the  > v2.A4
         default color palette for use with RIPscrip but it might be  > v2.A4
         different.  This means that any pixel of the bitmap that is  > v2.A4
         drawn to the screen is shown in whatever actual color is the > v2.A4


         absolute closest to the color palette number corresponding   > v2.A4
         to that pixel in the bitmap (dithering may still apply -     > v2.A4
         see below).                                                  > v2.A4

         If the bitmap has no color palette (eg, 24-bit bitmaps),     > v2.A4
         then this flag is ignored.                                   > v2.A4

     4   This flag enables auto-dithering mode.  This is an           > v2.A4
         intelligent way of determining if dithering should be        > v2.A4
         performed or not.  If there are more colors in the bitmap    > v2.A4
         than in the video device or if the bitmap's color palette    > v2.A4
         is not used to set the video device, then dithering is used  > v2.A4
         to get the image as close to the original color scheme as    > v2.A4
         possible.  If the bitmap's palette is committed to the video > v2.A4
         device then no dithering is necessary because the color      > v2.A4
         palette in use has all (or more) of the necessary colors to  > v2.A4
         display the image.  24-bit images will always enable         > v2.A4
         dithering if this mode is used unless the terminal is        > v2.A4
         running in 24-bit mode.  Dithering slows down image drawing  > v2.A4
         so it should only be used for images that really need it.    > v2.A4

         If this flag is omitted, then no dither is performed at all. > v2.A4
         If the number of colors in the bitmap is higher than the     > v2.A4
         number of colors in the display device then this will yield  > v2.A4
         a lower quality image.  But if there are more colors in the  > v2.A4
         display device than the bitmap then the quality of the image > v2.A4
         will be close to the actual bitmap (or exact).               > v2.A4

     8   Place the bitmap image onto the screen with one of its       > v2.A4
         colors "transparent".  This means that the color index       > v2.A4
         specified in the <trans_color> parameter will be treated as  > v2.A4
         a transparent color.  This color will "show through" to      > v2.A4
         whatever graphics were behind the bitmap.  This applies to   > v2.A4
         all forms of bitmaps (monochrome through 24-bit).  With      > v2.A4
         bitmaps that have no palette, then only colors in the 24-bit > v2.A4
         range that "map" to this particular transparent color will   > v2.A4
         actually appear as transparent.  When used in combination    > v2.A4
         with dithering (when dithering is performed), transparent    > v2.A4
         regions could be "grainy" in appearance due to the dithering > v2.A4
         process.                                                     > v2.A4

If the bitmap is placed onto a duplicate port, then it is done in a   > v2.A3
specific order.  The image is shown on the current drawing port (with > v2.A4
possible transparency) then the resulting image (after color palette  > v2.A4
translation and dithering are performed) is placed onto the duplicate > v2.A3
port.  This is done so that the image in the duplicate port will      > v2.A3
already have its processing done on it so that subsequent duplicate   > v2.A3
operations will not require any color translation or dithering (a     > v2.A3
speed consideration).  If transparency mode is used, then the image   > v2.A4
duplicated includes any graphics "behind" the image that show through > v2.A4
in the transparent locations.                                         > v2.A4

The <filename> parameter must not contain any sub-directory or path   > v2.A1
information and must specify a valid bitmap file name.  If the bitmap > v2.A3
cannot be located or an error occurs on the disk, then a box should   > v2.A1
be displayed on screen indicating that the given bitmap could not be  > v2.A3
loaded.  This visual prompt indicates that something is amiss to the  > v2.A3
end-user.  The size of the box will be as big as the destination      > v2.A3
bitmap image on screen.  If the X1 and Y1 are zero, then some         > v2.A3
suitable box should be drawn.                                         > v2.A3


NOTE:  The 4-byte <res> parameter is RESERVED FOR THE FUTURE          > v2.A4
       and should be set to "0000".                                   > v2.A4



┌──────────────────────────┐
│ 3.4.2.14 ■ RIP_LOAD_ICON │
└──────────────────────────┘

       Function: Loads and displays a disk-based icon to current port > v2.A3
          Level: 1
        Command: I
      Arguments: x:XY y:XY mode:2 clipboard:1 scale:1 res:1 filename  > v2.A2
         Format: !|1I <x> <y> <mode> <clipboard> <scale> <res>        > v2.A3
                 <filename>                                           > v2.A3
        Example: !|1I001101010button                                  > v2.A2
Uses Draw Color: NO
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO
Uses Font Style: NO
  Uses Viewport: YES                                                  > v1.54
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

This command instructs the terminal to read an icon from disk and
display it at the given upper-left (x,y) location in the current
drawing port.  If the width or height of the Icon would make it go    > v2.A3
off the right or left edge of the port's viewport, it will be         > v2.A3
truncated to fit inside the viewport.                                 > v2.A3

The <mode> parameter defines the modes in which the Icon will be
displayed on the current drawing port.  The modes are identical to    > v2.A3
the RIP_PUT_IMAGE command, and are as follows:

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

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

The <clipboard> parameter can be one of two values:                   > v2.A2

  Value  Description                                                  > v2.A0
  ──────────────────────────────────────────────────────────────      > v2.A0
    0    Load the image onto the port verbatim                        > v2.A3
    1    Load the image onto the port and put it onto clipboard port  > v2.A3

If the <clipboard> parameter specifies to put the icon's image onto   > v2.A3
a clipboard port, the order of operation is the following:            > v2.A3

     1.  The image is loaded onto the current drawing port,           > v2.A3
         truncated to the viewport if necessary.                      > v2.A3

     2.  A RIP_GET_IMAGE command is performed transparently           > v2.A3
         to copy the resultant image in the current drawing           > v2.A3
         port onto the clipboard port (it will be defined if          > v2.A3
         necessary, otherwise it will be re-defined).  If             > v2.A3
         the clipboard port is the same port as the current           > v2.A3


         drawing port, then this phase is omitted.  The               > v2.A3
         rectangle copied to the clipboard port is based on           > v2.A3
         the resultant, possibly truncated image.                     > v2.A3

The <scale> parameter indicates whether the icon should be scaled to  > v2.A2
the device coordinates when it is loaded.  A `1' indicates that it    > v2.A2
should be scaled, and a `0' indicates that it not should be scaled.   > v2.A2
This is important when dealing with older RIPscrip 1.54 icons.  Icons > v2.A3
that are loaded with RIPscrip 1.54 need to be resolution independent. > v2.A3
This is performed when this command has a 1 in the scale parameter's  > v2.A3
position.  All scaling is performed in this command as if the icon    > v2.A3
were created in a 640x350 environment.  So, if an icon is loaded that > v2.A3
is 35 pixels tall, and it is displayed in a 640x480 environment, it   > v2.A3
will be stretched vertically to make it 48 pixels tall.  This makes   > v2.A3
sure that icons loaded in this mode are displayed at the correct size > v2.A3
so that they are resolution independent.                              > v2.A3

    NOTE: By default this value must be set to `1' (scaled)!          > v2.A2

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.  If this happens, then no clipboard operations are         > v2.A3
performed - except that the clipboard is cleared and the clipboard    > v2.A3
pointer is cleared as well.  This visual prompt indicates that        > v2.A3
something is amiss to the end-user.

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



┌──────────────────────┐
│ 3.4.2.15 ■ RIP_MOUSE │
└──────────────────────┘

       Function: Defines a rectangular hot mouse field
          Level: 1
        Command: M
      Arguments: num:2 x0:XY y0:XY x1:XY y1:XY clk:1 clr:1 res:5 text > v2.A2
         Format: !|1M <num> <x0><y0><x1><y1> <clk><clr><res><text>
        Example: !|1M00001122331100000host command^M
Uses Draw Color: NO
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO
Uses Font Style: NO
  Uses Viewport: YES                                                  > v1.54
      Uses Port: NO (screen ports only)                               > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

This command ties together three things:

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

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

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

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

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

The <text> parameter is a Host command that gets sent when the field
is clicked.  You may use a caret (^) or a backquote (`) to represent  > v2.A3
control characters, (e.g., ^M for carriage return, `G, ^C, etc.).     > v2.A3
Mouse fields may use Data text variables, active text variables, pick > v2.A3
lists, control characters and local file playback directives.  At     > v2.A3
no time are templates permitted in simple mouse fields.  See the      > v2.A3
section on host commands for more details about these types of        > v2.A3
features of RIPscrip.                                                 > v2.A3

Mouse fields are always created relative to port #0 (the screen       > v2.A3
port).  Under no circumstances are mouse fields allowed in offscreen  > v2.A3
drawing ports - you can't have a clickable mouse area in a region     > v2.A3
that cannot be clicked (ie, off the screen).  If the current drawing  > v2.A3
port is an offscreen port, or even a port other than port #0, then    > v2.A3
the mouse field is defined relative to screen port #0 for the         > v2.A3
purposes of defining its position.  The same applies to mouse-based   > v2.A3


buttons (see the RIP_BUTTON command).                                 > v2.A3

Mouse fields that extend partially outside of a viewport are          > v2.A3
truncated to fit inside the viewport.                                 > v2.A3

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

NOTE: All Mouse Fields are scanned in "last in, first out" order.     > v1.54
      This means that the last-most received Mouse Field will be      > v1.54
      the first one scanned for a mouse click.  You are limited to    > v1.54
      a maximum of 128 Mouse Regions or Mouse Buttons (128 total).    > v1.54



┌───────────────────────────┐
│ 3.4.2.16 ■ RIP_PLAY_AUDIO │
└───────────────────────────┘

       Function: Play a local digitized audio file on the terminal    > v2.A3
          Level: 1                                                    > v2.A3
        Command: w                                                    > v2.A3
      Arguments: res:4 filename                                       > v2.A3
         Format: !|1w <res> <filename>                                > v2.A3
        Example: !|1w0000filename.wav                                 > v2.A3
Uses Draw Color: NO                                                   > v2.A3
Uses Back Color: NO                                                   > v2.A3
Uses Line Style: NO                                                   > v2.A3
Uses Fill Style: NO                                                   > v2.A3
Uses Write Mode: NO                                                   > v2.A3
Uses Font Style: NO                                                   > v2.A3
  Uses Viewport: NO                                                   > v2.A3
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: NO                                                   > v2.A3

This command will physically start a local .WAV file to play back on  > v2.A3
the user's remote terminal.  The audio file must already exist in the > v2.A3
user's hard disk in the same location as their bitmapped icons.  If   > v2.A3
the file doesn't exist, then this command does nothing.  If you       > v2.A3
specify the <filename> parameter as $OFF$ then you will in effect be  > v2.A3
shutting off any currnetly running sound file.  If a sound is already > v2.A3
playing when this command is received, the older file that was        > v2.A3
playing will be terminated in place for the new file.  You may use    > v2.A3
RIP_ENTER_BLOCK_MODE to transfer audio files to the user's computer   > v2.A3
for subsequent playback.                                              > v2.A3

     NOTE:  The <res> parameter is for future expansion.  For         > v2.A3
            compatibility with future relases of RIPscrip, it         > v2.A3
            should be set to "0000".                                  > v2.A3



┌──────────────────────────┐
│ 3.4.2.17 ■ RIP_PUT_IMAGE │
└──────────────────────────┘

       Function: Pastes the clipboard port's contents to another port > v2.A3
          Level: 1
        Command: P
      Arguments: x:XY y:XY mode:2 res:1                               > v2.A3
         Format: !|1P <x> <y> <mode> <res>                            > v2.A3
        Example: !|1P0011010
Uses Draw Color: NO
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO
Uses Font Style: NO
  Uses Viewport: YES                                                  > v1.54
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

This command takes the contents of the port identified by the         > v2.A3
clipboard pointer (see the RIP_GET_IMAGE command above) and copies    > v2.A3
it to a position (x,y) in the currently active drawing port.  If the  > v2.A3
two ports refer to the same port number, then this command is         > v2.A3
ignored.  If the clipboard pointer is clear (ie, no clipboard port    > v2.A3
is in use), then this command is also ignored.                        > v2.A3

The area in the active drawing port that is overwritten with the      > v2.A3
graphics data is determined by the dimensions of the clipboard port   > v2.A3
previously established with a RIP_GET_IMAGE function.                 > v2.A3

The position on the active drawing port that is to receive the        > v2.A3
image is specified by the (x,y) parameters.  These define the upper   > v2.A3
left corner that will be the rectangle to receive the image data.     > v2.A3
If any part of the image would go off the edge of the viewport (or    > v2.A3
the screen) then it is truncated appropriately.                       > v2.A3

The image that is retrieved from the clipboard port does so based on  > v2.A3
the port's viewport (the entire contents of the viewport are copied   > v2.A3
to the active drawing port).  If the clipboard port is only used with > v2.A3
the RIP_GET_IMAGE command, then the viewport will be the full size of > v2.A3
the port.  If however, some port related commands are used on this    > v2.A3
clipboard port, then it is possible to alter the viewport inside this > v2.A3
port.  This gives you the ability to paste sub-areas of the port's    > v2.A3
actual image onto the destination drawing port.                       > v2.A3

The <mode> parameter defines "how" the image will be pasted on the
active drawing port:                                                  > v2.A3

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

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



┌──────────────────────┐
│ 3.4.2.18 ■ RIP_QUERY │
└──────────────────────┘

       Function: Query the contents of a text variable
          Level: 1
        Command: Σ
      Arguments: mode:1 window_num:1 res:2 query_text                 > v2.A0
         Format: !|1<escape> <mode> <window_num> <res> <query_text>
        Example: !|1<escape>2Q00this is a query $COMMAND$^m
Uses Draw Color: NO
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO
Uses Font Style: NO
  Uses Viewport: NO                                                   > v1.54
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

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

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

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

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

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

    Mode     Description
    ────────────────────────────────────────────────────────────────
     0    Process the query command NOW (upon receipt)
     1    Process when mouse clicked in the current Graphics          > v2.A0
          Viewport                                                    > v2.A0
     2    Process when mouse clicked in the current Text Window (any  > v2.A0
          text variables that return X or Y mouse coordinates return  > v2.A0
          TEXT coordinates, not graphics coordinates in this mode.    > v2.A0
          These coordinates are two-digit values instead of the       > v2.A0
          graphical values that are four digits).                     > v2.A0


     3    Process when mouse clicked in the Graphics Viewport         > v2.A0
          specified in the <window_num> parameter.  If that viewport  > v2.A0
          doesn't exist (hasn't been defined yet), then this query    > v2.A0
          command is ignored.                                         > v2.A0

     4    Process when mouse clicked in the Text Window specified     > v2.A0
          in the <window_num> parameter.  Any text variables that     > v2.A0
          return X or Y mouse coordinates return TEXT coordinates     > v2.A0
          based on that window's MicroANSI text font sizes, not       > v2.A0
          graphics coordinates in this mode.  These coordinates are   > v2.A0
          two-digit values instead of the graphical values that are   > v2.A0
          four digits).                                               > v2.A0

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

If more than one query command can be acted uon (ie, multiple         > v2.A4
viewport queries and/or text window queries are found that the mouse  > v2.A4
was clicked inside of), then processing of queries happens in a very  > v2.A4
specific order.  Note that all affected queries are processed - none  > v2.A4
are skipped.  The order in which queries are acted upon are as        > v2.A4
follows:                                                              > v2.A4

     1) The port/viewport table is scanned from 0-35.  If a query     > v2.A4
        is found for a port that isn't deactivated, and the mouse     > v2.A4
        was clicked inside that region (for screen ports only), then  > v2.A4
        the query is processed and the next port/viewport is checked. > v2.A4

     2) The text window table is scanned from 0-35.  If a query       > v2.A4
        is found for a text window that isn't deactivated, and the    > v2.A4
        mouse was clicked inside that window's display area, then     > v2.A4
        the query is processed and the next text window is checked.   > v2.A4

     3) If a "current viewport" query, otherwise known as a floating  > v2.A4
        viewport query, is found and the mouse was clicked inside the > v2.A4
        current viewport, then the floating viewport query is         > v2.A4
        processed.                                                    > v2.A4

     4) If a "current text window" query, otherwise known as a        > v2.A4
        floating text window query, is found and the mouse was        > v2.A4
        clicked inside the text window's display area, then the       > v2.A4
        floating text window query is processed.                      > v2.A4

When the user clicks the mouse down, then all queries are checked.    > v2.A4
The point where the mouse was originally clicked is the one that is   > v2.A4
checked for with the queries.  After all queries are processed, then  > v2.A4
the mouse click is ignored until the user releases the mouse button.  > v2.A4


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

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

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

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

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

       It should be mentioned that text window queries are performed  > v2.A1
       before any viewport queries when resident queries are          > v2.A1
       concerned.                                                     > v2.A1



┌───────────────────────────┐
│ 3.4.2.19 ■ RIP_READ_SCENE │
└───────────────────────────┘

       Function: Playback local .RIP file
          Level: 1
        Command: R
      Arguments: res:8 filename...
         Format: !|1R <res> <filename>
        Example: !|1R00000000testfile.rip
Uses Draw Color: YES
Uses Back Color: YES                                                  > v2.A1
Uses Line Style: YES                                                  > v2.A2
Uses Fill Style: YES                                                  > v2.A2
Uses Write Mode: YES
Uses Font Style: YES
  Uses Viewport: NO                                                   > v1.54
      Uses Port: YES (dependent on the contents of the source file)   > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

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.



┌────────────────────────────┐
│ 3.4.2.20 ■ RIP_REGION_TEXT │
└────────────────────────────┘

       Function: Display a line of text in rectangular text region
          Level: 1
        Command: t
      Arguments: justify:1 and text-string
         Format: !|1t <justify> <text-string>
        Example: !|1t1This is a text line to be justified
Uses Draw Color: YES
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: YES
Uses Font Style: YES
  Uses Viewport: YES                                                  > v1.54
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

A number of these commands may come sandwiched between the
RIP_BEGIN_TEXT and RIP_END_TEXT commands.  The <text-string> should   > v2.A3
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 four possible settings for the <justify> parameter:         > v2.A3

  Justify   Description
  ─────────────────────────────────────────────
     0      Left justify this line
     1      Right/left "full" justify this line

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

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



┌─────────────────────────────────────────────────────────────────────────────
│ 3.4.2.21 ■ RIP_SCROLL (this command was formerly RIP_COPY_REGION)
└─────────────────────────────────────────────────────────────────────────────

       Function: Copy (scroll) screen region up/down                  > v2.A1
          Level: 1
        Command: G
      Arguments: x0:XY y0:XY x1:XY y1:XY mode:1 res:1 dest_line:2     > v2.A2
         Format: !|1G <x0> <y0> <x1> <y1> <mode> <res> <dest_line>    > v2.A1
        Example: !|1G080G140M0005
Uses Draw Color: NO
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO
Uses Font Style: NO
  Uses Viewport: NO                                                   > v1.54
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

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.

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

The <mode> parameter instructs the terminal what to do with the       > v2.A1
part of the source rectangle that isn't covered up by the scrolled    > v2.A1
data.  You may specify several things to happen as defined by the     > v2.A1
mode values below:                                                    > v2.A1

     Mode  Description                                                > v2.A1
     ─────────────────────────────────────────────────────────────    > v2.A1
       0   Do nothing - leave the old graphics on the screen          > v2.A1
       1   Fill the old graphical area with the current drawing       > v2.A1
           color (solid fill in COPY mode).                           > v2.A1
       2   Fill the old graphical area with the current background    > v2.A1
           drawing color (solid fill in COPY mode).                   > v2.A1
       3   Fill the area with the current fill color (solid fill in   > v2.A1
           COPY mode).  Fill pattern/styles are not used for this.    > v2.A1
       4   Fill the old graphical area with the current fill          > v2.A1
           style/pattern in the current fill color.                   > v2.A1
       5   Erase the affected area entirely to black.                 > v2.A1
       6   Fill the affected area with the color of a pixel from      > v2.A1
           one of the corners of the affected rectangle.  If the      > v2.A1
           image area was scrolled up, then the color is taken        > v2.A1
           from the lower-right most pixel from the old graphical     > v2.A1
           rectangle (left exposed).  If the data is scrolled         > v2.A1
           down, then the rectangle is filled in with the color       > v2.A1
           of the pixel in the upper-left most pixel.  This is        > v2.A1
           mode is used so that if the area is a multi-colored        > v2.A1
           graphic, that a suitable fill color is used.               > v2.A1


┌─────────────────────────────────┐
│ 3.4.2.22 ■ RIP_SET_MOUSE_CURSOR │
└─────────────────────────────────┘

       Function: Sets the mouse cursor (pointer) to various shapes    > v2.A1
          Level: 1                                                    > v2.A1
        Command: c                                                    > v2.A1
      Arguments: cursor_style:2 res:4                                 > v2.A1
         Format: !|1c <cursor_style> <res>                            > v2.A1
        Example: !|1c030000                                           > v2.A1
Uses Draw Color: NO                                                   > v2.A1
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO                                                   > v2.A1
Uses Font Style: NO                                                   > v2.A1
  Uses Viewport: NO                                                   > v2.A1
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

This command allows you to alter the current mouse cursor shape that  > v2.A1
is shown on the screen.  This feature lets you change the cursor to   > v2.A1
another shape to give the user of the terminal an idea that something > v2.A1
is going on.  For example, changing the cursor to the shape of an     > v2.A1
hourglass or a watch could give the idea that they should wait for a  > v2.A1
moment because something is going on.                                 > v2.A1

The <cursor_style> parameter is an ID number that specifies which     > v2.A1
cursor style should be activated.  The possible values for this       > v2.A1
parameter are:                                                        > v2.A1

     Style     Description                                            > v2.A4
     ──────────────────────────────────────────────────────────       > v2.A4
       00      Standard "left-leaning" arrow cursor (default)         > v2.A4
       01      Wrist watch cursor                                     > v2.A4
       02      Cross-hair cursor                                      > v2.A4
       03      I-bar cursor (for text editing)                        > v2.A4
       04      Pointing finger cursor                                 > v2.A4
       05      Hand held up cursor                                    > v2.A4
       06      Hourglass cursor                                       > v2.A4

When a RIP_RESET_WINDOWS or a RIP_HEADER command is executed, the     > v2.A1
mouse cursor is automatically reset to the default, standard pointer  > v2.A1
cursor.                                                               > v2.A1



┌───────────────────────────┐
│ 3.4.2.23 ■ RIP_WRITE_ICON │
└───────────────────────────┘

       Function: Write contents of the clipboard port to disk         > v2.A2
          Level: 1
        Command: W
      Arguments: res:1 filename                                       > v2.A3
         Format: !|1W <res> <filename>                                > v2.A3
        Example: !|1W0filename.icn
Uses Draw Color: NO
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO
Uses Font Style: NO
  Uses Viewport: NO                                                   > v1.54
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

This command takes the contents of the clipboard port and writes it   > v2.A3
to disk as a BMP type bitmap file.  The image written to disk is the  > v2.A3
image contained inside the viewport of the clipboard port (see the    > v2.A3
RIP_PUT_IMAGE command for more details about viewports and the        > v2.A3
clipboard port).  If the clipboard pointer indicates that there is    > v2.A3
no clipboard in use, then this command does nothing.                  > v2.A3

Once the file is written to disk, you may subsequently use the        > v2.A3
RIP_LOAD_ICON or RIP_LOAD_BITMAP commands to load the icon back onto  > v2.A3
a drawing port.                                                       > v2.A3

Path or sub-directory information is not allowed in the filename      > v2.A3
portion of the command.  If an Icon by the same name already exists   > v2.A3
on disk, it is overwritten.                                           > v2.A3

NOTE:  The <res> parameter is reserved for future use by TeleGrafix.  > v2.A3
       For future compatibility, it should be set to "0".             > v2.A3



╔═══════════════════════════════════╗
║ 3.4.3 ■ LEVEL-2 RIPscrip COMMANDS ║
╚═══════════════════════════════════╝

Level-2 commands are "context" related commands.  They are used when  > v2.A4
switching from one data table to another, or are actually commands    > v2.A4
for manipulating actual data tables, or their entries.                > v2.A4



┌───────────────────────────┐
│ 3.4.3.1 ■ RIP_DEFINE_PORT │
└───────────────────────────┘

       Function: Define a drawing port                                > v2.A3
          Level: 2                                                    > v2.A3
        Command: P                                                    > v2.A3
      Arguments: port-num:1 x0:XY y0:XY x1:XY y1:XY                   > v2.A3
                 flags:4 res:4                                        > v2.A3
         Format: !|2P <port-num> <x0> <y0> <x1> <y1> <flags> <res>    > v2.A3
        Example: !|2P300002F2F00010000                                > v2.A3
Uses Draw Color: NO                                                   > v2.A3
Uses Back Color: NO                                                   > v2.A3
Uses Line Style: NO                                                   > v2.A3
Uses Fill Style: NO                                                   > v2.A3
Uses Write Mode: NO                                                   > v2.A3
Uses Font Style: NO                                                   > v2.A3
  Uses Viewport: YES                                                  > v2.A3
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A3

This command physically defines a new graphical drawing port.  The    > v2.A3
port can be either onscreen (a video port) or an offscreen bitmap     > v2.A3
port (a Clipboard Port).  When defined, the newly created port        > v2.A3
becomes the current graphical drawing port (if the <flags> say to -   > v2.A3
see below).                                                           > v2.A3

If the <port-num> that you are trying to define is already defined,   > v2.A3
and the port isn't protected, it is redefined (ie, deleted then       > v2.A3
re-created using the new parameters).  If the port is defined and     > v2.A3
protected, then the port definition operation will fail and the port  > v2.A3
will be switched back to the screen port (#0) as previously           > v2.A3
described.                                                            > v2.A3

The <port-num> parameter determines which entry in the master Port    > v2.A3
Table you wish to define.  When working with ports, you need to be    > v2.A3
concerned about the port number you're working with - that's the      > v2.A3
location of the port, and that's how you access it when you need to   > v2.A3
switch ports - by port number.  You are allows up to 36 separate      > v2.A3
grpahical ports (0-35 in decimal).  Port #0 cannot be re-defined      > v2.A3
because it is always defined as the Screen Port.  You can however,    > v2.A3
alter the viewport for Port #0 to make a sub-area on the screen to    > v2.A3
draw in (and clip).  The viewport for Port #0 may also be deactivated > v2.A4
as can the viewport on any other graphical Port.                      > v2.A4

To create a port, you need to specify the upper-left coordinate       > v2.A3
corner of the port and the lower-right coordinate of the rectangle    > v2.A3
bounding the port.  The configuration of coordinates is different     > v2.A3
depending on the type of graphical port as declared by the <flags>    > v2.A3
parameter (see below).  For Video Ports (onscreen ports), the <x0>    > v2.A3
and <y0> parameters define the upper-left corner of the port on the   > v2.A3
video screen, and the <x1> and <y1> values define the lower-right     > v2.A3
corner of the port.  Together, they define the pixel width and height > v2.A3
of the port (this adheres to global world coordinate systems).  For   > v2.A3
Clipboard Ports (offscreen bitmap ports), you cannot have an          > v2.A3
upper-left corner - so the <x0> and <y0> parameters must be set to    > v2.A3
zero.                                                                 > v2.A3



Once defined, the viewport for the given port is defined as the size  > v2.A3
of the port itself (you may change it with a RIP_VIEWPORT command     > v2.A3
later if you wish).  This makes it so that the entire port may be     > v2.A3
drawn into.  If you need to define a sub-area of the port as a        > v2.A3
clipping boundary, modify the viewport for that graphical port.       > v2.A3

The <flags> parameter for this command allows you to make some        > v2.A3
important distinctions to the port.  The possible port flags are OR'd > v2.A3
together to create one final number where each bit represents some    > v2.A3
flag value.  The possible flag values and what they mean are          > v2.A3
described as follows:                                                 > v2.A3

     Value     Description                                            > v2.A3
     ─────────────────────────────────────────────────────────────    > v2.A3
       1       Port is an offscreen (Clipboard) port.  When this      > v2.A3
               flag is specified, the <x0> and <y0> parameter are     > v2.A3
               assumed to be zero (even if they aren't set to 0,      > v2.A3
               they are treated as if they were).  When a port        > v2.A3
               is declared as a Clipboard Port, all graphical         > v2.A3
               operations are performed to an offscreen bitmap        > v2.A3
               port and do not appear on the screen (without you      > v2.A3
               specifically using a port copy operation).  If this    > v2.A3
               flag is omitted, then the port is treated as a         > v2.A3
               Video Port and any graphics drawn to the port will     > v2.A3
               show up on the screen immediately (providing the       > v2.A3
               viewport for this port isn't deactivated).             > v2.A4

       2       Port is made the active drawing port immediately       > v2.A3
               upon completion of this command.  This has the         > v2.A3
               net effect of creating the port and immediately        > v2.A3
               switching to it.  Without this flag, you would have    > v2.A3
               to use a RIP_SWITCH_PORT command to draw directly      > v2.A3
               into this port.                                        > v2.A3

       4       Deactivate this port's viewport immediately upon       > v2.A4
               creation.  This has the net effect of creating the     > v2.A3
               port and setting the viewport to a deactivated status. > v2.A4

       8       The newly defined port is immediately protected.       > v2.A3
               This means that the port cannot be deleted without     > v2.A3
               explicitly unprotecting the port.                      > v2.A3

  NOTE: The <res> parameter is reserved for future use and should     > v2.A3
        be set to "0000" for future compatibility with later          > v2.A3
        RIPscrip revisions.                                           > v2.A3



┌───────────────────────────┐
│ 3.4.3.2 ■ RIP_DELETE_PORT │
└───────────────────────────┘

       Function: Deletes a specific port definition                   > v2.A3
          Level: 2                                                    > v2.A3
        Command: p                                                    > v2.A3
      Arguments: port_num:1 dest_port:1 res:2                         > v2.A3
         Format: !|2s <port_num> <dest_port> <res>                    > v2.A3
        Example: !|2s500000                                           > v2.A3
Uses Draw Color: NO                                                   > v2.A3
Uses Back Color: NO                                                   > v2.A3
Uses Line Style: NO                                                   > v2.A3
Uses Fill Style: NO                                                   > v2.A3
Uses Write Mode: NO                                                   > v2.A3
Uses Font Style: NO                                                   > v2.A3
  Uses Viewport: NO                                                   > v2.A3
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A3

This command physically deletes one or more graphical ports.  The     > v2.A3
exact port depends on the <port_num> parameter.  If the port number   > v2.A3
specified is between 1-35, then the given port is deleted (providing  > v2.A3
of course that it is unprotected).  If you attempt to deleted a       > v2.A3
protected port, then this command will fail.  If you attempt to       > v2.A3
delete port #0 (the screen port), then you will be activating a       > v2.A3
special case of this command - all unprotected ports from 1-35 are    > v2.A3
automatically deleted.  This is a good garbage collection command     > v2.A3
mode when you want to start with a new slate of ports without the     > v2.A3
overhead of sending many delete port commands.                        > v2.A3

The <dest_port> parameter defines the port number that will be        > v2.A3
switched to after the delete operation is finished.  Typically, this  > v2.A3
will be set to port #0 (switch to screen port), but it need not be.   > v2.A3
If the destination port is undefined, then it will automatically      > v2.A3
switch to port #0.  If you instruct this command to delete all ports, > v2.A3
then the destination port may or may not be set to the screen port -  > v2.A3
it all depends on whether or not the destination port both exists,    > v2.A3
and is protected - remember, a protected port cannot be deleted with  > v2.A3
this command without first being unprotected.  So, if you delete all  > v2.A3
ports and switch to another port that isn't port #0, and that port is > v2.A3
protected, then that protected port is selected as the new active     > v2.A3
port.  If however, that port doesn't exist (ie, it did exist at the   > v2.A3
beginning of this command, but wasn't protected), then the screen     > v2.A3
port #0 will be selected.                                             > v2.A3

  NOTE: The <res> parameter is reserved for future use and should     > v2.A3
        be set to "00" for future compatibility with later            > v2.A3
        RIPscrip revisions.                                           > v2.A3



┌─────────────────────────┐
│ 3.4.3.3 ■ RIP_PORT_COPY │
└─────────────────────────┘

       Function: Copies graphics data from one port to another        > v2.A3
          Level: 2                                                    > v2.A3
        Command: C                                                    > v2.A3
      Arguments: source_port:1 sx0:XY sy0:XY sx1:XY sy1:XY            > v2.A3
                 dest-port:1 dx0:XY dy0:XY dx1:XY dy1:XY              > v2.A3
                 write-mode:1 res:5                                   > v2.A3
         Format: !|2C <source_port> <sx0> <sy0> <sx1> <sy1>           > v2.A3
                 <dest_port> <dx0> <dy0> <dx1> <dy1> <write_mode>     > v2.A3
                 <res>                                                > v2.A3
        Example: !|2C300002020500002020100000                         > v2.A3
Uses Draw Color: NO                                                   > v2.A3
Uses Back Color: NO                                                   > v2.A3
Uses Line Style: NO                                                   > v2.A3
Uses Fill Style: NO                                                   > v2.A3
Uses Write Mode: NO                                                   > v2.A3
Uses Font Style: NO                                                   > v2.A3
  Uses Viewport: YES                                                  > v2.A3
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A3

This command copies graphics data from one port to another (or        > v2.A3
possibly even the same port).  The area copied is a rectangular area  > v2.A3
based on the (sx0,sy0)..(sx1,sy1) parameters in the <source_port> and > v2.A3
the (dx0,dy0)..(dx1,dy1) parameters in the <dest_port>.  The          > v2.A3
<source_port> and <dest_port> parameters specify which port numbers   > v2.A3
are to be used for the source and destination respectively.  They may > v2.A3
be set to the same port number which signifies that a bit-blit        > v2.A3
operation is to occur from one location of the current port to        > v2.A3
another.  Both the source and destination ports are specified as port > v2.A3
numbers from 0-35.  If either port doesn't exist (or is deactivated)  > v2.A4
then this command will do nothing.                                    > v2.A3

The source port parameters (sx0,sy0)..(sx1,sy1) define the upper-left > v2.A3
and lower-right corners of the rectangle in the source port that is   > v2.A3
to be the source image data.  If all four parameters are set to zero, > v2.A3
then the entire source port's viewport is used as the image.  These   > v2.A3
parameters determine the portion of the source port that is to be     > v2.A3
used to copy to the destination port.  The image data is taken from   > v2.A3
within the port's currently defined viewport.  If the (sx1,sy1)       > v2.A3
parameters takes the image out of the bounds of the source port's     > v2.A3
viewport, then the values are adjusted to make it fit inside the      > v2.A3
viewport.                                                             > v2.A3

The destination port parameters (dx0,dy0)..(dx1,dy1) define the       > v2.A3
destination rectangle in the destination port that will receive the   > v2.A3
graphical data.  The (dx0,dy0) parameters define the upper-left       > v2.A3
corner of the destination location of the bitmap data.  If the        > v2.A3
(dx1,dy1) parameters are set to zero, then the image is copied from   > v2.A3
the source port verbatim - with the exact same pixel dimensions as    > v2.A3
the source image rectangle.  If these two values are not set to zero, > v2.A3
then scaling of the source image may be performed.  Whether or not    > v2.A3
scaling is performed or not depends on one fact - does the physical   > v2.A3
pixel size (height and width) of the source image rectangle exactly   > v2.A3
match the pixel size (height and width) of the destination port       > v2.A3
rectangle?  If the pixel dimensions match exactly, then no scaling is > v2.A3
performed on the rectangle.  However, if the pixel size in either the > v2.A3
vertical or horizontal directions are different, then the image is    > v2.A3


scaled to fit in the desired rectangle.  When we talk about "pixel    > v2.A3

size", we are referring to the low-level device pixel size of the     > v2.A3
image.  This means that we take into account world coordinate         > v2.A3
translation and viewport coordinate translations first, then compare  > v2.A3
the raw pixel sizes of the source and destination rectangles.  If     > v2.A3
they differ, then we perform scaling of the bitmap.  Otherwise we     > v2.A3
copy it over verbatim.  If the destination rectangle coordinates are  > v2.A3
set all to zeros, then the image is placed at (0,0) in the            > v2.A3
destination port's viewport and the image will fill the entire port's > v2.A3
viewport.                                                             > v2.A3

The <write_mode> parameter determines the Raster Transfer mode that   > v2.A3
is used to write the image data to the destination rectangle.  The    > v2.A3
possible value and their various effects on the destination image are > v2.A3
as follows:                                                           > v2.A3

  Mode  Description                                           Logical > v2.A3
  ─────────────────────────────────────────────────────────────────── > v2.A3
    0   Copy the image to the port verbatim                    COPY   > v2.A3
    1   Exclusive-OR  image with the one already on the port   XOR    > v2.A3
    2   Logically OR  image with the one already on the port   OR     > v2.A3
    3   Logically AND image with the one already on the port   AND    > v2.A3
    4   Copy the inverse of the image onto the port            NOT    > v2.A3

Working with a port copy operation, the source rectangle for the      > v2.A3
image is contained in the source port number.  The destination        > v2.A3
rectangle is based in the destination port.  If either of these       > v2.A3
rectangles extend outside of the respective ports' viewports, then    > v2.A3
they are adjusted accordingly - possibly scaling the image when it    > v2.A3
wasn't intended.                                                      > v2.A3

  NOTE: The <res> parameter is reserved for future use and should     > v2.A3
        be set to "00000" for future compatibility with later         > v2.A3
        RIPscrip revisions.                                           > v2.A3



┌──────────────────────────┐
│ 3.4.3.4 ■ RIP_PORT_WRITE │
└──────────────────────────┘

       Function: Writes port image to a disk-based bitmap file        > v2.A3
          Level: 2                                                    > v2.A3
        Command: W                                                    > v2.A3
      Arguments: port_num:1 x0:XY y0:XY x1:XY y1:XY res:4 filename    > v2.A3
         Format: !|2W <port_num> <x0> <y0> <x1> <y1> <res> <filename> > v2.A3
        Example: !|2W5000020200000FILENAME.BMP                        > v2.A3
Uses Draw Color: NO                                                   > v2.A3
Uses Back Color: NO                                                   > v2.A3
Uses Line Style: NO                                                   > v2.A3
Uses Fill Style: NO                                                   > v2.A3
Uses Write Mode: NO                                                   > v2.A3
Uses Font Style: NO                                                   > v2.A3
  Uses Viewport: YES                                                  > v2.A3
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A3

This command physically takes the contents of the specific graphics   > v2.A3
port and writes it to a disk-based bitmap file (eg, a .BMP file).     > v2.A3
The specific area of the given port that is written to the disk is    > v2.A3
based on the (x0,y0)..(x1,y1) parameters.  If all of these parameters > v2.A3
are set to zeros, then the entire port's viewport is written to the   > v2.A3
desired bitmap file.  If the (x1,y1) paraemters are set to zero, then > v2.A3
the lower-right corner of the image is taken to be the lower-right    > v2.A3
corner of the port's viewport.  The (x0,y0) parameters determine the  > v2.A3
upper-left corner of the image's location in the given graphics port. > v2.A3
You could use any of the following three variations:                  > v2.A3

     X0   Y0   X1   Y1   Description                                  > v2.A3
     ───────────────────────────────────────────────────────────────  > v2.A3
     0    0    0    0    Grab the entire port's viewport for the      > v2.A3
                         image to be saved.                           > v2.A3
     25   25   0    0    Grab the image area from (25,25) to the      > v2.A3
                         lower-right of the port's viewport as the    > v2.A3
                         image data to be saved.                      > v2.A3
     25   25   100  100  Save the image data from (25,25) to          > v2.A3
                         (100,100) in the given graphics port to the  > v2.A3
                         destination bitmap file.                     > v2.A3

The <port_num> parameter determines which graphics port is to be the  > v2.A3
source of the image data.  If that port is undefined, or the X/Y      > v2.A3
parameters place the graphics data off the port's viewport, then this > v2.A3
command is ignored.  If the (x0,y0) parameters fall inside the port's > v2.A3
viewport, but the (x1,y1) parameters do not, then the lower-left      > v2.A3
corner is adjusted appropriately (as if the user specified (0,0) as   > v2.A3
the lower-left corner - see above).                                   > v2.A3

  NOTE: The <res> parameter is reserved for future use and should     > v2.A3
        be set to "0000" for future compatibility with later          > v2.A3
        RIPscrip revisions.                                           > v2.A3



┌───────────────────────────┐
│ 3.4.3.5 ■ RIP_SET_REFRESH │
└───────────────────────────┘

       Function: Sets a sequence to send host to refresh display      > v2.A1
          Level: 2                                                    > v2.A1
        Command: R                                                    > v2.A1
      Arguments: res:4 refresh_string                                 > v2.A1
         Format: !|2R <res> <refresh_string>                          > v2.A1
        Example: !|2R0000^m                                           > v2.A1
Uses Draw Color: NO                                                   > v2.A1
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO                                                   > v2.A1
Uses Font Style: NO                                                   > v2.A1
  Uses Viewport: NO                                                   > v2.A1
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

This command sets a host command sequence in the terminal that can be > v2.A1
sent to the host to refresh the current display screen.  This refresh > v2.A1
option would be chosen by the user to redisplay the screen in case    > v2.A1
line noise or some kind of corruption caused the screen to become     > v2.A1
distorted or corrupted.  This can only be altered (or cleared) by a   > v2.A1
RIP_SET_REFRESH command or via a reset.  To completely clear a        > v2.A4
refresh state, call this command with a $OFF$ text variable as its    > v2.A4
host command or use the text variable $NOREFRESH$.                    > v2.A1

The host command portion of this sequence can contain any kind of     > v2.A1
host command information including control characters, pick lists,    > v2.A1
text variables or many other things (but not templates).              > v2.A4



┌───────────────────────────────────┐
│ 3.4.3.6 ■ RIP_SWITCH_BUTTON_STYLE │
└───────────────────────────────────┘

       Function: Switches to a new button style                       > v2.A4
          Level: 2                                                    > v2.A4
        Command: B                                                    > v2.A4
      Arguments: bstyle_num:2                                         > v2.A4
         Format: !|2B <bstyle_num>                                    > v2.A4
        Example: !|2B04                                               > v2.A4
Uses Draw Color: NO                                                   > v2.A4
Uses Back Color: NO                                                   > v2.A4
Uses Line Style: NO                                                   > v2.A4
Uses Fill Style: NO                                                   > v2.A4
Uses Write Mode: NO                                                   > v2.A4
Uses Font Style: NO                                                   > v2.A4
  Uses Viewport: NO                                                   > v2.A4
      Uses Port: NO                                                   > v2.A4
 Uses Base Math: Current setting                                      > v2.A4

This command physically switches the currently active button style.   > v2.A4
Any subsequent button operations will use this new button style.      > v2.A4

You are allowed up to 36 separate button styles to switch between.    > v2.A4
Possible button style slot numbers are from 0-35 (0-Z).               > v2.A4

When a RIP_RESET_WINDOWS or a proper RIP_HEADER command is executed,  > v2.A4
then all unprotected button style slots are reset to the default      > v2.A4
button style.  Also, the current button style is reset to button      > v2.A4
style number 0.                                                       > v2.A4



┌──────────────────────────────────┐
│ 3.4.3.7 ■ RIP_SWITCH_ENVIRONMENT │
└──────────────────────────────────┘

       Function: Switches to a new environment                        > v2.A4
          Level: 2                                                    > v2.A4
        Command: E                                                    > v2.A4
      Arguments: env_num:2                                            > v2.A4
         Format: !|2E <env_num>                                       > v2.A4
        Example: !|2E04                                               > v2.A4
Uses Draw Color: NO                                                   > v2.A4
Uses Back Color: NO                                                   > v2.A4
Uses Line Style: NO                                                   > v2.A4
Uses Fill Style: NO                                                   > v2.A4
Uses Write Mode: NO                                                   > v2.A4
Uses Font Style: NO                                                   > v2.A4
  Uses Viewport: NO                                                   > v2.A4
      Uses Port: NO                                                   > v2.A4
 Uses Base Math: Current setting                                      > v2.A4

This command physically switches the currently active environment.    > v2.A4
Any subsequent RIPscrip operations will use this environment.         > v2.A4

You are allowed up to 36 separate environments to switch between.     > v2.A4
Possible environment slot numbers are from 0-35 (0-Z).                > v2.A4

When a RIP_RESET_WINDOWS or a proper RIP_HEADER command is executed,  > v2.A4
then all unprotected environment slots are reset to the default       > v2.A4
environment settings.  Also, the current environment is reset to      > v2.A4
environment number 0.                                                 > v2.A4



┌──────────────────────────────┐
│ 3.4.3.8 ■ RIP_SWITCH_PALETTE │
└──────────────────────────────┘

       Function: Switches to a new color palette                      > v2.A3
          Level: 2                                                    > v2.A3
        Command: A                                                    > v2.A3
      Arguments: palette_num:2                                        > v2.A3
         Format: !|2A <palette_num>                                   > v2.A3
        Example: !|2A04                                               > v2.A3
Uses Draw Color: NO                                                   > v2.A3
Uses Back Color: NO                                                   > v2.A3
Uses Line Style: NO                                                   > v2.A3
Uses Fill Style: NO                                                   > v2.A3
Uses Write Mode: NO                                                   > v2.A3
Uses Font Style: NO                                                   > v2.A3
  Uses Viewport: NO                                                   > v2.A3
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: Current setting                                      > v2.A3

This command physically switches the currently active drawing color   > v2.A3
palette.  When this happens, any graphics currently on-screen will    > v2.A3
immediately change colors based on the new palette (providing the     > v2.A3
terminal is running in a hardware mode that allows for color          > v2.A3
palettes).  If the terminal is running in a mode that doesn't allow   > v2.A3
for color palettes (ie, 24-bit mode, etc), then only the internal     > v2.A3
color lookup table is changed for subsequent color palette mapping    > v2.A3
mode operations.                                                      > v2.A3

You are allowed up to 36 separate color palettes to switch between.   > v2.A3
Possible palette slot numbers are from 0-35 (0-Z).                    > v2.A3

When a RIP_RESET_WINDOWS or a proper RIP_HEADER command is executed,  > v2.A3
then all unprotected color palette slots are reset to the default     > v2.A3
color palette.  Also, the current active color palette is reset to    > v2.A3
palette number 0.                                                     > v2.A3



┌───────────────────────────┐
│ 3.4.3.9 ■ RIP_SWITCH_PORT │
└───────────────────────────┘

       Function: Switches to a new port                               > v2.A3
          Level: 2                                                    > v2.A3
        Command: s                                                    > v2.A3
      Arguments: port-num:1 flags:2 res:3                             > v2.A3
         Format: !|2s <port-num> <flags> <res>                        > v2.A3
        Example: !|2s500000                                           > v2.A3
Uses Draw Color: NO                                                   > v2.A3
Uses Back Color: NO                                                   > v2.A3
Uses Line Style: NO                                                   > v2.A3
Uses Fill Style: NO                                                   > v2.A3
Uses Write Mode: NO                                                   > v2.A3
Uses Font Style: NO                                                   > v2.A3
  Uses Viewport: NO                                                   > v2.A3
      Uses Port: YES                                                  > v2.A3
 Uses Base Math: Current setting                                      > v2.A3

This command physically changes whichever port is currently active.   > v2.A3
You may specify a port number from 0-35 (36 ports total).  If the     > v2.A3
designated port doesn't exist, then the port is automatically         > v2.A3
switched to port #0 (the screen's port).  This has the side-effect    > v2.A3
that when the operation fails (ie, the destination port doesn't       > v2.A3
exist), all subsequent graphics operations would be sent to the       > v2.A3
screen which would give you a visual impression that something is     > v2.A3
very wrong.                                                           > v2.A3

When the new port is activated, all subsequent drawing operations are > v2.A3
performed on it instead of the previously defined port.               > v2.A3

The <flags> parameter for this command allows you to specify one or   > v2.A3
more things that can alter the switching operation.  The allowable    > v2.A3
flag values and their meanings are described as follows:              > v2.A3

     Value     Description                                            > v2.A3
     ─────────────────────────────────────────────────────────────    > v2.A3
       1       The destination port is immediately protected.         > v2.A3
       2       The destination port is immediately un-protected       > v2.A3
       4       The port being switched from is immediately            > v2.A3
               protected.                                             > v2.A3
       8       The port being switched from is immediately            > v2.A3
               un-protected.                                          > v2.A3

If you try to switch to the same port that is already in use, nothing > v2.A3
happens except for possibly the activation of one or more flag        > v2.A3
values.  This allows you to protect or unprotect a port without       > v2.A3
switching ports.  Port #0 cannot be either protected nor unprotected. > v2.A3

  NOTE: The <res> parameter is reserved for future use and should     > v2.A3
        be set to "000" for future compatibility with later           > v2.A3
        RIPscrip revisions.                                           > v2.A3



┌───────────────────────────────────┐
│ 3.4.3.10 ■ RIP_SWITCH_TEXT_WINDOW │
└───────────────────────────────────┘

       Function: Switch to another Text Window (activate)             > v2.A0
          Level: 2                                                    > v2.A0
        Command: T                                                    > v2.A3
      Arguments: window_num:1 res:1                                   > v2.A0
         Format: !|2T <window_num> <res>                              > v2.A0
        Example: !|2T30                                               > v2.A0
Uses Draw Color: NO                                                   > v2.A0
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO                                                   > v2.A0
Uses Font Style: NO                                                   > v2.A0
  Uses Viewport: NO                                                   > v2.A0
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

In RIPscrip, you are allowed to have up to 36 separate text windows   > v2.A0
on screen simultaneously (0-9, A-Z).  These windows maintain their    > v2.A0
own "current ANSI attributes", cursor position, text window           > v2.A0
dimensions/location, cursor ON/OFF status and whether the window is   > v2.A0
actived or deactivated.                                               > v2.A4

When you switch to another window, if that window hasn't been defined > v2.A0
yet, then the current window definition is copied to the new window   > v2.A0
slot.  When you switch to another window, the cursor is hidden in the > v2.A0
previous window and re-drawn in the new window (if it was visible the > v2.A0
last time the window was used).                                       > v2.A0

If you switch to a window that is "deactivated", it will hide the     > v2.A4
cursor from whatever window was previously active and then execute    > v2.A4
the proper deactivate text window sequence for the newly selected     > v2.A4
text window slot.                                                     > v2.A4

When a RIP_RESET_WINDOWS command is acted upon, any previously        > v2.A0
defined text window slots are erased and Window #0 is set to full     > v2.A0
screen mode (using the User's selected MicroANSI font), and the       > v2.A0
current window number is set to window #0.                            > v2.A0



┌─────────────────────────────┐
│ 3.4.3.11 ■ RIP_SWITCH_STYLE │
└─────────────────────────────┘

       Function: Switches to a new Drawing Style Context              > v2.A0
          Level: 2                                                    > v2.A0
        Command: Y                                                    > v2.A0
      Arguments: style_num:1 res:1                                    > v2.A0
         Format: !|2Y <style_num> <res>                               > v2.A0
        Example: !|2YG0                                               > v2.A0
Uses Draw Color: YES                                                  > v2.A0
Uses Back Color: YES                                                  > v2.A1
Uses Line Style: YES                                                  > v2.A2
Uses Fill Style: YES                                                  > v2.A2
Uses Write Mode: YES                                                  > v2.A0
Uses Font Style: YES                                                  > v2.A0
  Uses Viewport: YES                                                  > v2.A0
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

This command switches to a particular "drawing style".  A drawing     > v2.A0
style is a combination of the following graphical settings:           > v2.A0

     ■ Current drawing color                                          > v2.A1
     ■ Current background drawing color                               > v2.A1
     ■ Current fill pattern number (or user-defined fill pattern)     > v2.A1
     ■ Current fill color                                             > v2.A1
     ■ Current line pattern number (or user-defined line pattern)     > v2.A1
     ■ Line pattern odd drawing rule (see RIP_LINE_STYLE)             > v2.A1
     ■ Current mouse cursor style number                              > v2.A1
     ■ Current font number (or font name for extended fonts)          > v2.A1
     ■ Current font size, orientation and horizontal/vertical         > v2.A1
       alignment                                                      > v2.A1
     ■ Current write mode (raster/transfer operation)                 > v2.A1
     ■ Current color mode (palette or direct RGB)                     > v2.A1
     ■ Current X/Y location (used with RIP_TEXT commands)             > v2.A1
     ■ Current image mode settings (see RIP_IMAGE_STYLE)              > v2.A1

By default, all commands that alter the above modes will change the   > v2.A0
settings of Style #0.  By switching Style Contexts, you are given the > v2.A0
ability to alter which Style Context is being manipulated.  After a   > v2.A0
given Style has been defined, you can quickly switch from one Style   > v2.A0
to another without having to re-transmit each and every mode command  > v2.A0
to recreate the environment.                                          > v2.A0

The first time you switch to a new Style Context, the contents of the > v2.A0
current Style are copied into the newly selected Style.  You are      > v2.A0
allowed up to 36 separate Styles (0-9, A-Z).                          > v2.A0

Whenever a RIP_RESET_WINDOWS function is executed, the contents of    > v2.A0
all Styles are reset to a default status which is the Status of the   > v2.A0
drawing environment after Resetting is complete.                      > v2.A0



╔═══════════════════════════════════╗
║ 3.4.4 ■ LEVEL-3 RIPscrip COMMANDS ║
╚═══════════════════════════════════╝

Level-3 commands are time-based and affect operations of RIPscrip.    > v2.A4



┌──────────────────────────────┐
│ 3.4.4.1 ■ RIP_BAUD_EMULATION │
└──────────────────────────────┘

       Function: Set Baud Rate Emulation for Local RIP Playback       > v2.A0
          Level: 3                                                    > v2.A1
        Command: e                                                    > v2.A1
      Arguments: rate_val:4                                           > v2.A3
         Format: !|3e <rate_val>                                      > v2.A3
        Example: !|3e01UN                                             > v2.A3
Uses Draw Color: NO                                                   > v2.A0
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO                                                   > v2.A0
Uses Font Style: NO                                                   > v2.A0
  Uses Viewport: NO                                                   > v2.A0
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

This command will set the rate at which local RIP file playback is    > v2.A0
performed.  By default, local RIP playback is done at full speed      > v2.A0
which is dependent on your CPU, hard disk speed and many other        > v2.A0
factors.  With this command, you can set the speed at which the       > v2.A0
playback is performed so that it can approximate a particular baud    > v2.A0
rate.  This setting will remain in effect even after a                > v2.A0
RIP_RESET_WINDOWS command so that a Reset command inside a local RIP  > v2.A0
file will not alter the playback speed in mid-stride.  The setting    > v2.A0
remains in effect until changed explicitly by the user (if possible   > v2.A0
under the terminal software), or by the Host via another              > v2.A0
RIP_BAUD_EMULATION command.                                           > v2.A0

Typical settins for <rate_val> might be 300, 2400, 4800, 19200, etc.  > v2.A3
A value of 0 indicates that local playback should be performed at     > v2.A3
maximum speed (no baud rate emulation).                               > v2.A3



┌─────────────────────┐
│ 3.4.4.2 ■ RIP_DELAY │
└─────────────────────┘

       Function: Causes the Client Terminal to Pause                  > v2.A0
          Level: 3                                                    > v2.A1
        Command: D                                                    > v2.A0
      Arguments: delay_period:4                                       > v2.A0
         Format: !|3D <delay_period>                                  > v2.A1
        Example: !|3D002D                                             > v2.A1
Uses Draw Color: NO                                                   > v2.A0
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO                                                   > v2.A0
Uses Font Style: NO                                                   > v2.A0
  Uses Viewport: NO                                                   > v2.A0
      Uses Port: NO                                                   > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

This command will cause the remote terminal to Pause for              > v2.A0
<delay_period> number of "timer ticks".  A Timer Tick is defined as   > v2.A0
being 1/60th of a second.  So, a delay period of 60 would be equal to > v2.A1
one full second of delay.                                             > v2.A0

During the time period of the delay, the remote terminal should be    > v2.A0
queueing up any incoming RIPscrip code or raw text (if any) into some > v2.A0
form of internal buffer to prevent character loss.  After the delay   > v2.A0
period is complete, the data in that buffer (if any) should be        > v2.A0
processed immediately and the terminal should resume processing the   > v2.A0
incoming stream of data.                                              > v2.A0



╔═══════════════════════════════════╗
║ 3.4.5 ■ LEVEL-9 RIPscrip COMMANDS ║
╚═══════════════════════════════════╝

Level-9 commands deal with communication to the host system in some   > v2.A4
fashion.  These embody binary transfers and encoded data transfers.   > v2.A4



┌────────────────────────────────┐
│ 3.4.5.1 ■ RIP_ENTER_BLOCK_MODE │
└────────────────────────────────┘

       Function: Enter block transfer mode with host
          Level: 9
        Command: Σ
      Arguments: mode:1 proto:1 file_type:2 res:4
                 [filename] <>
         Format: !|9<escape> <proto> <file_type> <res>
                 [filename] <>
        Example: !|9<escape>00010000ICONFILE.BMP<>                    > v2.A1
Uses Draw Color: NO
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO
Uses Font Style: NO
  Uses Viewport: NO                                                   > v1.54
      Uses Port: YES (in JPEG mode, or local RIP playback mode)       > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

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

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

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

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

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

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



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

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

With a filename, using X-Modem/CRC:

     !|9<escape>01020000filename.icn<>                                > v2.A2

Without a filename, using Z-Modem

     !|9<escape>07040000<>                                            > v2.A2

A File Type of 0 is intended for RIP files.  The received RIP file is > v2.A0
placed in the appropriate Host System directory and is played back    > v2.A0
like any other Local RIP file.  This gives you the ability to         > v2.A0
transmit a RIP scene and play it back without having to send two      > v2.A0
different commands.                                                   > v2.A0

A File Type of 1 is intended for generic files.  The files are placed > v2.A0
in the appropriate Host System directory and are left there for       > v2.A0
future use.  No processing is performed on any file(s) received.      > v2.A0

A File Type of 2 is identical in nature to File Type 1.  It is        > v2.A0
designated for Icon Files only (.BMP, .BMH and .BMM).  You should use > v2.A2
the Generic Mode 1 instead of this mode as they are identical and in  > v2.A0
future revisions, this File Type (2) might change.                    > v2.A0

A File Type of 3 is intended for various types of received bitmap     > v2.A0
images.  These image files (JPEG) are controlled with the             > v2.A1
RIP_IMAGE_STYLE command, which must be set prior to the image         > v2.A0
being received.  When the image file is received, it is displayed     > v2.A0
according to the given Image Mode settings.  If no previous image     > v2.A0
settings were received, the image is displayed at the full size of    > v2.A0
the current graphics viewport.  JPEG files have a file extension of   > v2.A0
.JPG.                                                                 > v2.A1

A File Type of 4 is for COMPOSITE DYNAMIC mode.  This is only useful  > v2.A0
for Batch File Transfers (ie, Zmodem and Ymodem).  When files are     > v2.A0
received by this mode, they are processed separately depending on the > v2.A0
files' extensions.  In this mode, the file(s) are simply stored in    > v2.A0
the proper location.  No further processing is done on the files      > v2.A0
after this point.  The recognized file extensions are:                > v2.A0

     RIP ... Store the RIP file locally in the proper directory       > v2.A0
     BMP ... Place icon in proper directory                           > v2.A2
     BMH ... Place hot icon in proper directory                       > v2.A2
     BMM ... Place mask icon in proper directory                      > v2.A2
     JPG ... Store JPEG file in proper directory                      > v2.A0
     GIF ... Store GIF file in proper directory                       > v2.A4



A File Type of 5 is for ACTIVE DYNAMIC mode.  This is only useful for > v2.A0
Batch File Transfers (ie, Zmodem and Ymodem).  When files are         > v2.A0
received by this mode, they are processed separately depending on the > v2.A0
files' extensions.  Files received while in this mode are stored in   > v2.A0
their proper locations and then extra processing (if any) is done on  > v2.A0
the file based on file extension.  The recognized file extensions     > v2.A0
are:                                                                  > v2.A0

     RIP ... Store and playback RIP file locally                      > v2.A0
     BMP ... Place icon in proper directory                           > v2.A1
     BMH ... Place hot icon in proper directory                       > v2.A2
     BMM ... Place mask icon in proper directory                      > v2.A2
     JPG ... Store and display JPEG file based on image settings      > v2.A0
     GIF ... Store and display GIF file based on image settings       > v2.A4

If you receive file(s) with extensions other than the ones listed     > v2.A0
above, then no processing will be done on the files other than        > v2.A0
placing them in the appropriate Host Directory.                       > v2.A0

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



┌────────────────────────────────────┐
│ 3.4.5.2 ■ RIP_BEGIN_UUENCODE_BLOCK │
└────────────────────────────────────┘

       Function: Begin a generic UU-Encoded data block                > v2.A1
          Level: 9                                                    > v2.A1
        Command: U                                                    > v2.A1
      Arguments: file_type:2 res:8                                    > v2.A1
         Format: !|9U <file_type> <res>                               > v2.A1
        Example: !|9U0200000000                                       > v2.A1
Uses Draw Color: NO                                                   > v2.A1
Uses Back Color: NO                                                   > v2.A1
Uses Line Style: NO                                                   > v2.A2
Uses Fill Style: NO                                                   > v2.A2
Uses Write Mode: NO                                                   > v2.A1
Uses Font Style: NO                                                   > v2.A1
  Uses Viewport: NO                                                   > v2.A1
      Uses Port: YES (for displayable graphics sequences)             > v2.A3
 Uses Base Math: Current setting                                      > v2.A2

This command must be the last RIPscrip command on the line of text.   > v2.A1
The very next line of text will be the beginning (header) information > v2.A1
of a UU-Encoded data file block.  In this header is contained the     > v2.A1
filename associated with the binary UU-Encoded data.  This            > v2.A1
information is decoded by the receiving terminal and the resulting    > v2.A1
filename is stored on the terminal's hard disk to be processed        > v2.A1
depending on the <file_type> parameter.  The <file_type> parameter is > v2.A1
identical in nature and values to the parameter by the same name in   > v2.A1
the RIP_ENTER_BLOCK_MODE command.  The file that results from the     > v2.A1
UU-Encoded data block might be a JPEG file, BMP file, sound file, or  > v2.A1
could be just about anything.                                         > v2.A1

Immediately after the last line of UU-Encoded data, either raw text   > v2.A1
or RIPscrip code should begin.  Some UU-Encoded data blocks have      > v2.A1
line-by-line CRC checking.  If this mode is specified in the header   > v2.A1
of the UU-Encoded data block, then CRC checking on the lines should   > v2.A1
be performed as defined in the UU-Encoding specification.  If a       > v2.A1
single CRC fails, the terminal should kill the partial file and       > v2.A1
ignore remaining UU-Encoded data until a RIPscrip or raw text block   > v2.A1
is encountered that it can then subsequently process.                 > v2.A1



╔══════════════════════════════════════════════════════╗
║ 4 ■ HOST COMMANDS - A TUTORIAL AND 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:

     ■ Control-Character specification
     ■ Pre-defined Text Variables & User-defined text variables
     ■ Pop-up pick-lists
     ■ Query text variable contents (pre-defined & user variables)
     ■ A Host Command "Template" system for added intelligence.



╔══════════════════════════╗
║ 4.1 ■ CONTROL CHARACTERS ║
╚══════════════════════════╝

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

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

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

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



╔══════════════════════╗
║ 4.2 ■ TEXT VARIABLES ║
╚══════════════════════╝

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

There are three types of Text Variables.

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

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

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

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

Some built-in text variables have been extended in RIPscrip 2.0 to    > v2.A1
allow for parameters.  This extends text variables functionality in   > v2.A1
many ways.  If a text variable has a parameter, it is enclosed in     > v2.A1
paranthesis immediately after the text variable name as in the        > v2.A1
following example:                                                    > v2.A1

          $SAVE(8)$                                                   > v2.A1

This would be basically identical in nature to the older $SAVE8$ text > v2.A1
variable which saves the screen to the eighth slot.  The new method   > v2.A1
is more universal in design than having separate text variables for   > v2.A1
basically identical operations.  The older forms of these commands    > v2.A1
will remain in the specification but their use is not recommended     > v2.A1
because the new method is far superior.                               > v2.A1

Any text variables which take parameters don't necessarily need them. > v2.A1
In any case, these text variables will have their parameters          > v2.A1
described in the appropiate sections below.                           > v2.A1

If a variable takes more than one parameter, then they are separated  > v2.A1
by commas between the paranthesis (eg, $ETW(0,1)$).                   > v2.A1


A complete listing of all pre-defined text variables (both data and   > v2.A3
active) is near the end of this document.                             > v2.A3



╔══════════════════════════════════════════╗
║ 4.2.1 ■ TEXT VARIABLE CREATION AND QUERY ║
╚══════════════════════════════════════════╝

As previously mentioned, 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 teaches the software new
things it doesn't already know.



┌──────────────────────────────────────┐
│ 4.2.1.1 ■ PRE-DEFINED TEXT VARIABLES │
└──────────────────────────────────────┘

A pre-defined text variable is either a data text variable, or an
active text variable.  A data text variable is a text variable that
inserts a piece of text wherever the text variable is used.  For
example, the sequence $DATE$ might get replaced with 09/19/94.  This
is a simple example of a data text variable.  An active text
variable on the other hand does something (usually).  They normally
don't get replaced with other text information.  For example, the
text variable $SAVE$ saves the contents of the screen to a disk file
that can later be restored with $RESTORE$.  In these situations,
active text variables are removed from whatever text message they
are present in (they are still activated though).



┌────────────────────────────────────┐
│ 4.2.1.2 ■ 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.



┌────────────────────────────────────────────────┐
│ 4.2.1.3 ■ 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.



┌───────────────────────────────────┐
│ 4.2.1.4 ■ CREATING USER VARIABLES │
└───────────────────────────────────┘

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



┌───────────────────────────────────┐
│ 4.2.1.5 ■ 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).



┌───────────────────────────────────┐
│ 4.2.1.6 ■ 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.



┌───────────────────────────────────────────┐
│ 4.2.1.7 ■ 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.



╔════════════════════════════════════════╗
║ 4.2.1.8 ■ DEFINING PERMANENT VARIABLES ║
╚════════════════════════════════════════╝

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

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

    Please enter FIRST_NAME:

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

There are six basically different text variable references, each of   > v2.A4
them take a single command character added between the first dollar   > v2.A0
sign and the beginning of the variable name.  Those characters and    > v2.A0
their significance is:                                                > v2.A0

     * ... An answer is required                                      > v2.A0
     + ... Save variable to database permanently                      > v2.A0
     = ... Save to internal memory table (lost when RIPterm hangs up) > v2.A0
     # ... Do not echo keystrokes (show #'s instead).  This is        > v2.A0
           useful for things like entering passwords.                 > v2.A0

     - ... Used in conjunction with a default response (see below).   > v2.A1
           When this option is used, the value of the variable is     > v2.A1
           set to the default value and the user is not prompted      > v2.A1
           for any data entry (transparent data variable define).     > v2.A1
           Nothing is returned to the host in this mode (unless       > v2.A4
           transparent retrieval mode is used - see below).           > v2.A4

     & ... Transparent data variable retrieval.  This allows the      > v2.A1
           host to retrieve a text variable from the terminal and     > v2.A1
           the user is not prompted to modify the information.        > v2.A1

           DEVELOPER NOTE: For database variables that are retrieved  > v2.A1
           you might want to implement a "data security" option in    > v2.A1
           your software that overides this "transparent" mode of     > v2.A1
           operation for permanent variables.  For temporary          > v2.A1
           variables (in memory) though, the system should be allowed > v2.A1
           to retrieve them transparently since it created them       > v2.A1
           itself.                                                    > v2.A1

If you do not specify the "+" or the "=" directives to actually save  > v2.A4
the text variable's contents, then the data will be passed on as part > v2.A4
of whatever host command the text variable expression was a part of,  > v2.A4
and will not be saved.  To save the text variable permanently, you    > v2.A4


must specify the "+" command which will store the variable in some    > v2.A4
kind of internal database file for permanent storage.  If you wish    > v2.A4
to only save the variable temporarily (eg, for the duration of the    > v2.A4
current session), use the "=" directive instead - this saves the      > v2.A4
variable in an internal memory table.                                 > v2.A4

To ask for the FIRST_NAME text variable that must be filled in, and   > v2.A0
to instruct RIPterm to save the variable to the local database, you   > v2.A0
would use the following text variable command syntax:                 > v2.A0

                          $*+FIRST_NAME$                              > v2.A0

The four command characters (*, +, = and #) can be in any order, but  > v2.A0
can only appear once in the text variable statement - additional      > v2.A0
occurences of them are ignored.                                       > v2.A0

You may specify how wide the data entry field for the text variable   > v2.A1
is.  To do this, simply put the number of columns after the variable  > v2.A1
name with a comma (,) in between (eg, $NAME,10$).                     > v2.A1

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

               $FIRST_NAME,20@What's your first name?$                > v2.A0

In the question text, you are not allowed to use dollar signs at all. > v2.A0

You also have the ability to X/Y location of the pop-up window that   > v2.A1
asks for the text variable.  This gives you control over the location > v2.A1
of the window.  The way you do this is by adding some coordinate      > v2.A1
information before the variable name followed by a colon.  An example > v2.A1
of this would be as follows:                                          > v2.A1

               $10,10:FIRST_NAME,20@What's your first name?$          > v2.A1

These coordinates are specified in normal decimal format.  If one or  > v2.A1
either of the number are omitted then the dialog is centered either   > v2.A1
horizontally, vertically or both.  Some examples of this are as       > v2.A1
follows:                                                              > v2.A1

       $,50:NAME$ ... Centered horizontally                           > v2.A1
       $50,:NAME$ ... Centered vertically                             > v2.A1
         $,:NAME$ ... Centered both horizontally and vertically       > v2.A1

If you omit the X/Y specification codes entirely (eg, $NAME$), then   > v2.A1
the actual location of the popup dialog is up to the discretion of    > v2.A1
the RIPscrip software.                                                > v2.A1

X/Y coordinates are in current "world coordinates".                   > v2.A4

You may also supply a default value for the text variable.  This      > v2.A1
default value is used if the variable doesn't already exist.  When    > v2.A1
the default value is used it is displayed in the data field's edit    > v2.A1
region and you have the option of changing it.                        > v2.A1


To supply a default response, you specify the default contents after  > v2.A1
an equal sign (=) which must be placed after the variable name (and   > v2.A1
width parameter and question parameter if applicable).  Some examples > v2.A1
are:                                                                  > v2.A1

     $STATE=Ca$                                                       > v2.A1
     $STATE@What state do you live in?=Ca$                            > v2.A1

User defined text variables do not always require a specific response > v2.A4
(unless the "*" flag is specified indicating that a response is       > v2.A4
required).  If the user chooses to ignore the request (ie, hitting    > v2.A4
CANCEL or whatever), then a value of "NONE" is inserted in place of   > v2.A4
the user data text variable.                                          > v2.A4

Some discussion needs to be made about the six various text variable
referencing modes described earlier and how they interact.  The two
modes "=" and "+" are used to actually store (preserve) the text
variable's contents for a period of time (how long depends on if its
a permanent variable or a memory variable).  If either of these modes
are both present, then it is considered to be a permanent variable.

The transparent data define mode ("-") and transparent data retrieval
mode (&) are used by the host to interact with the user without
having to be prompt the user for any data (eg, the operation is
"transparent" to the user).

There are four basic possibilities with transparent modes:

     1) Transparent Define and Retrieve modes are set.  One of
        the following situations will occur in this mode:

          a) Default response specified and variable exists.
             The text variable is redefined with its contents
             set to the default response.

          b) Default response not specified and variable exists.
             The user is prompted to see if he wants to change
             the contents of the text variable as it stands.

          c) Default response specified and variable doesn't exist.
             The variable is defined using the default response.

          d) Default response not specified and variable doesn't
             exist.  The user is prompted to enter a value to
             define the text variable.

        After the variable is defined (if the user didn't say to
        skip this operation - ie, he was prompted), then it is
        sent to the host system.

     2) Transparent Define is set but retrieaval isn't set.  One
        of the following situations will occur:

          a) Default response specified and variable exists.
             The text variable is redefined with its contents
             set to the default response.

          b) Default response not specified and variable exists.
             The user is prompted to see if he wants to change
             the contents of the text variable as it stands.


          c) Default response specified and variable doesn't exist.
             The variable is defined using the default response.

          d) Default response not specified and variable doesn't
             exist.  The user is prompted to enter a value to
             define the text variable.

        Nothing is sent to the host system.

     3) Transparent Retrieval is set but define isn't set.  One
        of the following situations will occur:

          a) Default response specified and variable exists.
             The default response is ignored and the contents
             of the text variable are sent to the host.

          b) Default response not specified and variable exists.
             The contents of the text variable are sent to the
             host system.

          c) Default response specified and variable doesn't exist.
             The text variable is defined with its contents set to
             the default response and those contents are sent to
             the host system.

          d) Default response not specified and variable doesn't
             exist.  The user is prompted to enter data for the
             text variable.  If the user enters some data, then
             that variable is defined with its new contents and
             those contents are sent to the host.  If the user
             decided to abort the prompt then nothing is sent to
             the host3.

     4) Neither the transparent define or retrieval flags are
        set.  If this situation occurs, one of the following
        things will happen:

          a) Default response specified and variable exists.  If
             this is the case, then the user is prompted with the
             actual contents of the text variable, giving them the
             option to modify it, then the final response is sent
             to the host system.

          b) Default response not specified and variable exists.
             Same as (a).

          c) Default response specified and variable doesn't exist.
             The user is prompted to enter data for the variable.
             The default response is the value prompted to the user
             giving him the option to accept it, or enter a new
             value.

          d) Default response not specified and variable doesn't
             exist.  The user must be prompted for some data.  The
             data entry field will be blank forcing the user to
             enter some information.

If nothing is sent to the host and the text variable isn't to be
saved to the database or to memory, then the text variable operation
can be omitted entirely - since it would produce no functional
results.


During transparent define or retrieval modes, it is possible for the
user to have to be prompted for some information (as you have already
read).  If these "special case" situations occur, then the
transparency is effectively overidden.

The "answer is required" setting forces the user (if prompted) to
make some kind of selection (ie, they can't abort the text variable
operation).



╔════════════════════════════════════════════════════╗
║ 4.2.1.9 ■ USER DEFINED VARIABLES AND DATA SECURITY ║
╚════════════════════════════════════════════════════╝

When working with user-defined text variables, a topic arises which
may or may not be addressed by the RIPscrip software developer:
security!  What if you had credit card information stored in a
permanent text variable named $CredCardNo$ and the host system asked
your terminal for that information?  Obviously the user should be
informed about this request.  Situations might arise where security
is not a concern - like in a closed environment like an internal
office system using RIPscrip.  With these situations in mind, the
designer of a RIPscrip terminal might wish to include some kind of
"data security" feature into the software package.

Data security can be in many forms.  You could implement complete
"tight" security which would overide all transparent forms of text
variable operations - in effect, always making the user approve the
request.  A lighter security might be desirable - one where any
action working on permanent database text variables requires the
user's approval, but memory variables don't have to be approved.
This kind of a situation would let allow a host system to have
control over memory variables (which it presumably created anyway),
but let access to permanent variables be under strict control.  The
exact form of data security that you offer your software's users is
unimportant - but knowing that security is a concern is.  You do
not have to implement data security on your system - it is not an
actual part of RIPscrip (per se), but it could be useful to your
customers if security is an issue.



╔══════════════════════════════════════════════════════╗
║ 4.2.1.10 ■ USER DEFINED DATA VARIABLE FORMAT OPTIONS ║
╚══════════════════════════════════════════════════════╝

Just like text variable parameters defined earlier for built-in text  > v2.A1
variables, user defined text variables have the same luxury.  These   > v2.A1
parameters define the format of the entered data.  You are allowed up > v2.A4
to two parameters for a user-defined text variable.  The first one is > v2.A4
the "mode" parameter which designates what type of data the user can  > v2.A4
enter.  The possible settings for mode are:                           > v2.A4

        ANY ... Any character is allowed                              > v2.A1
      ALPHA ... User can enter alphabetic characters only (A-Z, a-z)  > v2.A1
     NUMBER ... User can enter numeric characters only (0-9)          > v2.A1
   ALPHANUM ... User can enter alphanumeric only (A-Z, a-z, 0-9)      > v2.A1

The second parameter is an optional conversion designator.  The       > v2.A4
possible settings for this parameter are:                             > v2.A4

     TONAME ... Convert the data to "name" format.  The first letter  > v2.A4
                is capitalized and all subsequent characters in a     > v2.A4
                word are set to lower case automatically (eg,         > v2.A4
                "TOM SMITH" becomes "Tom Smith".  No special          > v2.A4
                processing is performed on names like "McDonald",     > v2.A4
                etc.  If you wish to tackle this particular           > v2.A4
                complexity of name conversion, feel free.             > v2.A4
    TOUPPER ... Convert the data to upper case.                       > v2.A4
    TOLOWER ... Convert the data to lower case                        > v2.A4

You may omit one or both of the parameters.  If both are omitted,     > v2.A4
then it will default to "ANY" data with no conversion of any kind.    > v2.A4
You may omit the mode parameter if you wish, and specify only the     > v2.A4
conversion parameter.  Under no circumstances should a conversion     > v2.A4
parameter be allowed before a mode parameter - this is considered a   > v2.A4
syntax error.  Some examples of legal and illegal user variable       > v2.A4
queries might be:                                                     > v2.A4

          Legal ..... $USERDATA$                                      > v2.A4
          Legal ..... $USERDATA()$                                    > v2.A4
          Legal ..... $USERDATA(ANY)$                                 > v2.A4
          Legal ..... $USERDATA(ALPHA,TOUPPER)$                       > v2.A4
          Legal ..... $USERDATA(TONAME)$                              > v2.A4
          Illegal ... $USERDATA(TONAME,ANY)$                          > v2.A4
          Illegal ... $USERDATA(ANY,ALPHA)$                           > v2.A4
          Illegal ... $USERDATA(TONAME,TOUPPER)$                      > v2.A4

By default, a format option of "ANY" is assumed when no parameter are > v2.A1
specified.                                                            > v2.A1



╔═════════════════════════════════════════════════════╗
║ 4.2.1.11 ■ LIMITS ON LENGTH OF VARIABLE NAMES, ETC. ║
╚═════════════════════════════════════════════════════╝

The maximum length of a text variable name is 20 characters.          > v2.A2

Valid text variable names may contain alpha characters, numbers, or   > v2.A2
an underscore ("_").  The first character MUST be an aplhabetic       > v2.A2
character.  Only uppercase letters are recognized ("A"-"Z").  Any     > v2.A2
lowercase letters should be capitilized automatically.                > v2.A2

The maximum number of text vaiable parameters (the ones appearing     > v2.A2
between parenthesis, not the text string) is 40.                      > v2.A2

The maximum size of a text variable parameter is 12 characters.       > v2.A2
These are only available to text variables that are part of the       > v2.A2
RIPscrip specification.                                               > v2.A2

The maximum size of a question or default response is 100 characters. > v2.A2
Anything longer than this length is truncated.                        > v2.A2

The maximum length of a text variable text field is 255 characters.   > v2.A2
Anything longer than this length is truncated.                        > v2.A2



╔════════════════════════════════════════════════════╗
║ 4.2.1.12 ■ EXAMPLES OF USER-DEFINED TEXT VARIABLES ║
╚════════════════════════════════════════════════════╝

Below are some examples of user defined text variables as might be    > v2.A1
used in a real world situation:                                       > v2.A1

     $*+20,50:NAME(ToName),30@What's your name?=John Doe$             > v2.A4

This is about as complex as they get.  Going from left to right, lets > v2.A1
look at what all the codes mean.  First, the "*" means that a         > v2.A1
response to this request is required (they cannot hit ESC or CANCEL   > v2.A1
to get out of it).  The "+" means to save the response to the         > v2.A1
internal database permanently.  The sequence "20,50:" means to place  > v2.A1
the dialog box's upper left corner  at location (20,50) on the        > v2.A1
screen.  The "NAME" is the name of the data variable.  The format     > v2.A1
option "(Name)" means that this should be a formatted name field      > v2.A1
where the first letter of any word should be capitolized and the      > v2.A1
remaining characters should be set to lower case.  The value ",30"    > v2.A1
after the variable name/format indicates that this field is up to 30  > v2.A1
characters in length.  "@What's your name?" indicates that the        > v2.A1
question "What's your name?" should be displayed when the user is     > v2.A1
prompted for the information.  Finally, the "=John Doe" indicates     > v2.A1
that if the field doesn't exist, it should be filled in with "John    > v2.A1
Doe" before any editing is allowed.  This gives the user the ability  > v2.A1
to choose a default name if they wish.                                > v2.A1

     $*#20,10:PASSWORD,10@Please enter your password$                 > v2.A1

This example is a required data variable that echos #'s in place of   > v2.A1
the keystrokes you entered.  The field is placed at (20,10) on the    > v2.A1
screen with a variable name of PASSWORD.  The field is 10 characters  > v2.A1
wide and the prompt is "Please enter your password".                  > v2.A1



╔════════════════════════════════════╗
║ 4.3 ■ LOCAL RIPscrip FILE PLAYBACK ║
╚════════════════════════════════════╝

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

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

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

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



╔═════════════════════════════════╗
║ 4.4 ■ LOCAL AUDIO FILE PLAYBACK ║
╚═════════════════════════════════╝

In 2.0, we are introducing audio capability (both digitized and       > v2.A1
sequenced music).  To further enhance our host command language, we   > v2.A1
are now offering an extension of local RIP file playback for audio    > v2.A1
files.  This is "Local Audio File Playback".  This command is nearly  > v2.A1
identical in syntax to the local RIP file playback command with a     > v2.A1
simple alteration.  Instead of using the ">" character to signify     > v2.A1
RIPscrip file, you use the close paranthesis ")" as in the following  > v2.A1
example:                                                              > v2.A1

          $)AUDIOFILE.FIL$                                            > v2.A1
          $)TRAIN.WAV$                                                > v2.A1

The file extension is unimportant.  See the section of this document  > v2.A1
on audio commands for more detailed information on audio.             > v2.A1



╔═══════════════════════════════════════╗
║ 4.5 ■ LOCAL BITMAP PLAYBACK (DISPLAY) ║
╚═══════════════════════════════════════╝

This command is much like the local RIPscrip playback or the local    > v2.A1
audio playback, but it intended to place a local bitmap (.BMP) file   > v2.A1
onto the screen.  The bitmap will be displayed inside the current     > v2.A1
image settings as defined by the RIP_IMAGE_STYLE command and will     > v2.A1
adhere to the settings of that command.  This mode of displaying a    > v2.A1
BMP file is the only method for showing a BMP via the image style     > v2.A1
settings.                                                             > v2.A1

For the purposes of universality, the bitmap is shown to the screen   > v2.A1
using the current screen's color palette and "auto-dithering" mode is > v2.A1
used for the viewing of the image.  If you need support for some of   > v2.A1
the other modes for viewing a bitmap image (ie, the RIP_LOAD_BITMAP's > v2.A1
flexibility), then you will have to use that command instead.  This   > v2.A1
command is provided as a simple method of showing a bitmapped image   > v2.A1
from within a host command.                                           > v2.A1

Note, if no image style definition has been recorded then the bitmap  > v2.A1
is shown in the maximum size of the current viewport.  In other       > v2.A1
words, it will be scaled to fill up the entire viewport.              > v2.A1

To instruct the terminal to playback a local bitmap file, you would   > v2.A1
execute a host command with the following in it:                      > v2.A1

     $<FILENAME.BMP$                                                  > v2.A1

Note that this uses the less-than sign unlike the greater than sign   > v2.A1
used for local RIPscrip file playback.  This is intentional.  In      > v2.A1
fact, we use the opposite angle-bracket to indicate that this is a    > v2.A1
low-level primitive type playback like local RIPscrip file playback.  > v2.A1
The audio playback uses the parenthesis because it is not a low-level > v2.A1
primitive playback, but a higher level concept.  We use the           > v2.A1
parenthesis as a distinction from the lower level playback commands.  > v2.A1



╔═══════════════════════════════════════════╗
║ 4.6 ■ LOCAL IMAGE FILE PLAYBACK (DISPLAY) ║
╚═══════════════════════════════════════════╝

This command is similar to the local bitmap playback except that      > v2.A1
dealing with raw bitmapped images, this command displays compressed   > v2.A1
photo-like images.  Currently, only JPEG compressed image files are   > v2.A1
supported.  This command takes a JPEG file and displays it based on   > v2.A1
the defined image style (set with a RIP_IMAGE_STYLE) command.  If no  > v2.A1
image style is recorded, then the JPEG file is displayed inside the   > v2.A1
current viewport and will occupy the entire viewport's dimensions.    > v2.A1

This command uses a syntax similar to the local bitmap playback       > v2.A1
operation but instead uses the "(" character instead of the "<" one.  > v2.A1
This uses the same idealogy as was noted between local RIPscrip file  > v2.A1
playback and local audio file playback.  The JPEG file is considered  > v2.A1
a higher level object then a raw bitmap, so it uses the parenthesis   > v2.A1
command character instead of the angle brackets.  To playback the     > v2.A1
local JPEG file MYFILE.JPG, issue the following command:              > v2.A1

     $(MYFILE.JPG$                                                    > v2.A1



╔════════════════════╗
║ 4.7 ■ POP-UP LISTS ║
╚════════════════════╝

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

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

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

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

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

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

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

                       Sysop

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

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

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


               Choose one of the following:


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

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

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

  Examples:

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



╔═════════════════╗
║ 4.8 ■ TEMPLATES ║
╚═════════════════╝

A template is a special variety of a host command that is used to
construct other host commands.  They are only used with the
RIP_BUTTON command, not with RIP_MOUSE or RIP_QUERY.  Their use is
solely dedicated to the Button command.  In fact, their usefulness is
predominantly designed for Radio Buttons and Check Box Buttons but
this doesn't mean that you cannot use them for other purposes.

A template, like a normal "raw" Host Command, is stored in the Host
Command field of the RIP_BUTTON command.  Unlike Raw Host Commands
that get sent to the Host immediately, templates do not transmit
immediately.  In fact, it's possible for a Template to never get
transmitted to the BBS at all.  Templates are not normally sent
directly to the BBS - they are almost always used in conjunction with
some other button's host command.

As you know with normal Mouse Host Commands, you can send any piece
of text you want when the user clicks on that button.  You could send
the word "HELLO" to the BBS for example if they click on a certain
mouse button.  This is an example of a "Direct Host Command".

There are three types of Host Commands.  There are:

     1) DIRECT HOST COMMANDS - Send a string of text to the host
        immediately after the associated button is clicked.

     2) TEMPLATE DEFINITIONS - Defines a template to be used by
        other buttons (if ever).  See below for further details
        about how to define templates.

     3) TEMPLATE EXECUTION - This allows you to plug a piece of
        string data into one or more templates (defined previously).
        The resulting string is then acted upon like a Direct Host
        Command and transmitted to the BBS immediately.

The RIP_BUTTON command "segments" its Text Parameter Block into three
portions - the Icon File, Text Label followed by the Host Command
block.  Each of these segments is separated by the two character
delimiter "<>" like this:

          ICONFILE.ICN<>Button Label<>HOST COMMAND.

With the Button command, the Host Command segment can be sub-divided
into numerous smaller sub-segments, or Command Blocks.  This is done
with another two character delimiter "[]".  So, technically, you could
do this:

     ICONFILE.ICN<>Button Label<>HELLO^m[]WORLD^m

This command would show an Icon Button using the file ICONFILE.ICN as
its Icon Image, labeling it with the phrase "Button Label", and
defining an extended Host Command block with two segments.  If the user
clicks on this button, the following will be sent to the BBS:

     HELLO<cr>
     WORLD<cr>


Notice how the "[]" is not transmitted.  This is because it is simply
a delimiter separating two Command Blocks from each other.  Now each
of these two command blocks are DIRECT HOST COMMANDS, but they don't
have to be.  One of them could have been a Direct Host Command, and
another could just as easily have been a template definition.



╔══════════════════════════════════╗
║ 4.8.1 ■ BASIC TEMPLATE MECHANICS ║
╚══════════════════════════════════╝

There can be up to 36 different templates defined simultaneously.
Each template number corresponds directly to a Button Group Number.
Templates are identified by a single meganum 0-9 and A-Z, leaving 36
distinctly separate groups.  To define a template, you use a
variation of the Command Block delimiter "[]" with the template
identifier followed by a colon like this:

     [5:]This is template #6's definition
     [G:]This is template #16's definition

Defining a template is simple.  Activating a template however, is
another story.  What if three buttons in the same group all define
their own templates for the same group/template like this:

     Button #1:   [5:]This is button #1's template
     Button #2:   [5:]This is button #2's template
     Button #3:   [5:]This is button #3's template

Now, when these three buttons are received by the terminal, it
[the terminal] knows the Host Commands for each button (it memorized
each of them).  Now, which of these three templates is the currently
active one?  None of them!  A template definition doesn't become the
active template until that button containing its definition is
clicked (selected).  What this means is, you can have a bunch of
buttons all belonging to the same Button Group with their own
respective template definitions, but only the template relating to
the most recently clicked button will be the currently active
template for that group.

There are two ways of activating a template:

     1) Draw a button as "pre-selected" - in other words, the
        button is drawn pre-clicked immediately when it is
        received by the terminal.  When this happens, the
        Host Command for that button is processed immediately
        and if a template definition exists in that host command,
        it is acted upon immediately thus making that template
        the currently active template for that Group.

     2) The user clicks on a button containing a template
        definition.  If a template is already active in that
        group, it is overwritten by the newly activated template.

In either case when templates are defined, nothing is actually
transmitted to the BBS unless the Command Block contains some Direct
Host Command sub-block(s) like this:

     [5:]Template definition[]hello world^m

If this button were clicked, then Group number 5 would have the
template activated with the template text "Template definition".
Then the Direct Host Command "hello world^m" would be transmitted to
the BBS.  In this example, we see how a single host command can do
multiple things - in this case, it defined a template in group #5 AND
transmitted something to the BBS!



╔═══════════════════════════════════════════════╗
║ 4.8.2 ■ RADIO BUTTONS AND CHECK-BOX TEMPLATES ║
╚═══════════════════════════════════════════════╝

We have seen how templates are defined and activated.  Before we go
any further, let's explain how they are used for Radio Buttons and
Check-Box buttons.

Radio Buttons are a "type" of button group.  Only one button in that
group can be active (clicked) at any one time.  If a button that is
not active is clicked, any other buttons in that group that ARE
clicked are de-selected and the one that is being clicked is
selected.  If that newly clicked button has a Host Command, it is
processed.  If it has a template definition, it too is processed,
overwriting the currently defined template for the specified group.
Since Radio Buttons can only have one currently active button in a
single given Radio Group, similarly you can only have one template
active for that group at any given moment.

Check Box Buttons are another "type" of button group.  Unlike Radio
Buttons, Check Box buttons can have zero or more buttons active
(clicked) at any one time.  If a check box button group has ten
buttons defined in it, zero, five or all ten of those buttons can be
active simultaneously.  What about each of their respective Host
Commands?  They too are all processed when the buttons are
individually clicked.  Now what about templates?  Since you can only
have one template defined in a group at any given moment, how do
check box buttons accomplish this multiple-template concept?
Whenever a check box button is clicked (or unclicked), the template
for that group is re-calculated.  Any buttons in that group that have
template definitions are scanned, and any check box buttons in that
group that are selected, have their template definitions concatenated
together (strung together) end on end.  The result is one large
template which is built up from the template definitions of each
selected check box button.

Let's take a couple simple examples step-by-step to see how templates
are maintained internally.  In the first example, we will explore the
Radio Buttons and the way templates relate to them.  In the second
example, we'll examine check box buttons and templates.


     EXAMPLE 1 - RADIO BUTTON TEMPLATES
     ──────────────────────────────────
     Let's say you have four buttons in Button Group #3, and that
     button group is defined as a Radio Button group.  Here are the
     host command definitions for each of those buttons in this
     example:

          Button #1:   [3:]ABCD
          Button #2:   [3:]EFGH
          Button #3:   [3:]IJKL
          Button #4:   [3:]MNOP

     Now, if none of the buttons are clicked, then template group #3
     is blank.  If button #1 is clicked, the template for group #3
     would be defined as "ABCD".  Now, if button #4 is clicked, what
     would the template definition for group #3 be?  That's right,
     "MNOP".  Notice how only one of the given templates is active at
     any given moment.


     EXAMPLE 2 - CHECK BOX TEMPLATES
     ───────────────────────────────
     Now let's explore the slightly more complex world of check box
     templates.  As stated previously, check box templates can be
     strung along together to make a larger template - template
     construction of sorts.  Let's say you have a Button Group #2
     defined as a check box group with 7 buttons defined in it.  Each
     of the buttons are initially drawn as "unselected", or unclicked
     (inactive).  Here are the button host command definitions for
     each of the 7 buttons:

          Button #1:   [2:]Apples^m
          Button #2:   [2:]Oranges^m
          Button #3:   [2:]Cherries^m
          Button #4:   [2:]Grapes^m
          Button #5:   [2:]Pears^m
          Button #6:   [2:]Banannas^m
          Button #7:   [2:]Lemons^m

     Now, if all 7 buttons are not clicked, then template group #2
     would be blank.  Let's click on some buttons and see what the
     template will become as we change which buttons are clicked and
     which aren't:

          Button #3 clicked (ON) .... Template:  Cherries^m
          Button #5 clicked (ON) .... Template:  Cherries^mPears^m
          Button #3 clicked (OFF) ... Template:  Pears^m
          Button #5 clicked (OFF) ... Template:  <blank>
          Button #2 clicked (ON) .... Template:  Oranges^m
          Button #1 clicked (ON) .... Template:  Apples^mOranges^m
          Button #4 clicked (ON) .... Template:  Apples^mOranges^m
                                                 Grapes^m

     As you can see, the active template for a check box group is
     actually a combination of all selected buttons' templates, in
     ORDER OF DEFINITION, not in the order that they were clicked.
     Pay close attention to the end of the example where buttons were
     clicked in the order of 2, 1 then 4.  If you notice the active
     template though, they are in 1, 2 then 4 order!  They are in the
     order that the buttons were originally defined.



╔═══════════════════════════════════════╗
║ 4.8.3 ■ TAKING ADVANTAGE OF TEMPLATES ║
╚═══════════════════════════════════════╝

We've already gone through and shown you how to define templates and
how to activate them.  Now you need to know how to put them to use -
how to take a template and make it do something.  If you've been
confused up to this point, don't worry - we're going to put it all
together in a few minutes into one big picture.

There are two ways of using templates.  One is called Template
Chaining, and another is called Template Embedding.  Each of these
two methods are quite different, but give you quite a bit of
flexibility.  Let's take each of these methods step-by-step by
describing each in detail separately.



╔════════════════════════════╗
║ 4.8.4 ■ EMBEDDED TEMPLATES ║
╚════════════════════════════╝

Template embedding is a way of "inserting" a template inside another
host command.  What this means is that you can insert the contents of
an active template inside of a button's Direct Host Command.  The
direct host command is "expanded" around the inserted template and
the contents of the specified template are made part of the direct
host command.

Let's illustrate this with an example.  Taking the check box example
above which had a list of fruits as check box buttons, we can expand
on this example to show how template embedding can be a useful tool.
In this example, we will build a menu to take someone's order for
fruit.  Here is what the simple menu screen will look like:

      ╔════════════════════════════════════════╗
      ║     What would you like to order?      ║
      ║                                        ║
      ║ ┌────────────┐                         ║
      ║ │ ■  Apples  │                         ║
      ║ │ ·  Oranges │        ┌────────────┐   ║
      ║ │ ■  Cherries│        │Submit order│   ║
      ║ │ ·  Grapes  │        └────────────┘   ║
      ║ │ ■  Pears   │                         ║
      ║ │ ·  Banannas│                         ║
      ║ │ ■  Lemons  │                         ║
      ║ └────────────┘                         ║
      ╚════════════════════════════════════════╝

As you can see, we have a set of 7 check box buttons on the left of
the menu with the choices of the fruits for sale.  On the right is a
button to submit your order.  To implement this example, we will use
two separate button groups.  Group #0 will contain one button, the
"Submit Order" button.  Button Group #2 will be a check box button
group containing our seven choices of fruits as in the preceding
example.  Here are the Host Command definitions for each of the eight
buttons:

     Group #0 (normal button - not a radio or check-box button)
     ──────────────────────────────────────────────────────────
          SUBMIT ORDER:   I wish to order $?2$ right now^m

     Group #2 (check box button group)
     ─────────────────────────────────
          APPLES:    [2:]APPLES^m
          ORANGES:   [2:]ORANGES^m
          CHERRIES:  [2:]CHERRIES^m
          GRAPES:    [2:]GRAPES^m
          PEARS:     [2:]PEARS^m
          BANANNAS:  [2:]BANANNAS^m
          LEMONS:    [2:]LEMONS^m

Notice in the "Submit Order" button that there is a special code in
the Direct Host Command "$?2$".  This is a special variation of a text
variable.  This form of text variable is used only in Template
Embedding.  What it does is instructs the terminal to "insert template
#2 here".  The format of the template embedding code is:


          $?x$

...where "x" is the template identifier (0-Z) that is to be inserted.
Now back to the example, if the user clicked on "APPLES", "CHERRIES",
"PEARS" and "LEMONS" as in the menu shown above, then clicks on
"Submit Order", what would the Host Command look like when it gets
transmitted to the BBS?  Well, for starters, the Submit Order
button's host command reads:

     I wish to order $?2$ right now^m

After template #2 is inserted where the embedding code is, the host
command would look like this:

     I wish to order APPLES^mCHERRIES^mPEARS^mLEMONS^m right now^m

And after the ^m's are converted to carriage returns the final host
command would be like this:

     I wish to order APPLES
     CHERRIES
     PEARS
     LEMONS
     right now

What if the user didn't click on any of the fruits, but did click on
the Submit Order button?  Well, since template #2 belongs to a group
that is a Check Box group, which can have zero or more items selected
simultaneously, the $?2$ code would be expanded to a null string, or
nothing, so the final host command would be:

     I wish to order  right now

If template #2 was associated with a Radio group which has to have
one button clicked at all times, and none of the buttons were active,
then the terminal would hilight all the radio buttons in group #2 and
instruct the user to choose one first.  This is done automatically by
the terminal, you don't need to worry about Radio Buttons.

Just remember, Check Box buttons can legitimately have a blank
template, but Radio Buttons cannot due to the very nature of the
buttons.

The final host command after template embedding is limited to 4096
bytes of data.  If a host command would grow beyond 4096 bytes due to
embedding, it is truncated to exactly 4096 bytes.



╔═══════════════════════════╗
║ 4.8.5 ■ TEMPLATE CHAINING ║
╚═══════════════════════════╝

Now, on to the second form of using templates, Template Chaining.
Template Chaining is another method of using templates.  Unlike
Template Embedding though, template chaining is quite different.
Rather than inserting the contents of a template into a host command,
like in embedding, template chaining feeds data into a template and
then takes the result and transmits that to the BBS.  In other words,
Template Embedding inserts a template into a Host Command.  In
Template Chaining, a Host Command is inserted into a template (the
exact opposite).

If you recall from the Template Embedding discussion earlier, there
was a code for inserting a template into a host command.  The command
was $?x$ where "x" was the template number.  Template Chaining uses a
similar insertion code but with a subtle difference - there is no
template identifier.  The code is:

     $?$

This is a "generic insertion code".  It is used in the template
definition itself, not in the Direct Host Command like the template
embedding code was used.  The actual data that replaces the $?$
depends on the Direct Host Command that is "feeding" the template.

Before template chaining becomes crystal clear, we need to muddy the
waters some more by introducing one more thing - the Chaining
command.  A template chaining operation is performed almost exactly
like defining a template with a subtle difference, the colon (:) is
omitted from the template definition like this:

     [5]This is template chaining
     [5:]This is template definition

What's the difference?  In the case of the [5:], a template for group
#5 is defined.  In the [5] example, the template chaining instruction
is invoked on Template #5.  The phrase "This is template chaining"
will be fed into template number 5.  If template number 5 has a
generic insertion code $?$ in it, then it will be replaced with the
phrase "This is template chaining".  The final result after the
replacement will be a direct host command that will be transmitted to
the BBS.  Since template #5 doesn't have an insertion code, the
phrase "This is template chaining" will be lost in the chaining
process and the final host command would be "This is template
definition".

Here are a couple examples of template chaining illustrating several
ways that it may be used (we'll only show "active" template
definitions):

     [3:]This is a plain old template
     [4:]This template inserts $?$ here!
     [5:]This has two insertion codes $?$ and $?$

     [3]This text is lost in the chaining process
     [4]SOMETHING
     [5]HERE


This would be the result of the three chaining operations:

     3 ... This is a plain old template
     4 ... This template inserts SOMETHING here!
     5 ... This has two insertion codes HERE and HERE

We skipped over the "user clicked on this button" operations and went
directly to the end results to make the example as clear as possible.
There are three distinctly different situations in this example.  The
first shows a regular template without an insertion code being used
in a chaining operation.  As you can see, the data that was fed into
template #3 was lost because template #3 didn't have an insertion
code.  In the second example, a single insertion code is used and the
word "SOMETHING" is inserted in place of the insertion code.  The
third example shows that an insertion code can be used more than once
in a given template.

What if you tried to chain to a template that hasn't been activated
yet (ie, a blank template)?  If the template in question belongs to a
radio group, then the terminal would instruct the user to click on
one of the radio buttons to activate the template (he doesn't know
that templates are invovled of course).  If it was a check box
template, then the final host command would be nothing and in effect,
nothing would be transmitted to the host.  If the template in
question belonged to a generic button group, then also nothing would
get transmitted to the BBS.

In the preceding Template Chaining examples, only one template was
used (chained-to).  In reality, you can chain to multiple templates
with ease.  The format of multiple Template Chaining is simple, just
add the template identifiers for the templates you want to chain to
in the order you wish to chain to like this:

     [1E3]This is a three-level chaining operation

Notice how the Template Chain command has three template identifiers
in it, 1, E and 3.  The Host Command would be fed into template #1
first.  After any replacements, the final result of the template #1
chaining would be finished and that string of text would be fed into
template #E.  After any replacements/insertions are performed on
template #E, then the final result is fed into template #3 and the
final result of that chaining operation is sent to the BBS.

Here is an example of multiple template chaining calls:

     [1:]red green $?$ blue
     [E:]LOUD QUIET $?$ YELL
     [3:]soft $?$ hard smooth gritty

     [1E3](host command)

In this example, the phrase (host command) is fed into template #1,
then the result into template #E then that result into template #3
then finally transmitted to the BBS.  We can break this down
conceptually into three separate chaining operations to illustrate
what happens step-by-step:

     [1E3](host command)

Results in:


     [E3]red green (host command) blue

Resulting in:

     [3]LOUD QUIET red green (host command) blue YELL

And then finally:

     soft LOUD QUIET red green (host command) blue YELL hard smooth gritty

This last phrase is then sent to the BBS verbatim.  As you can see,
things can get pretty complex when multiple template chains are used,
however some dramatic things can be achieved with a little bit of
effort and some well thought out planning of your template
definitions.  Template chaining is useful for controlling HOW
particular data is transmitted to the BBS, while template embedding
is useful for controlling WHAT data is transmitted to the BBS.

You can think of template chaining as a method of defining "commands"
that will be sent to the BBS where the commands can be different
depending on which buttons are clicked in that group.  Template
embedding on the other hand is often used for controlling the data
parameters that are used with particular commands.

You are allowed up to 36 separate template chaining levels in one
template chaining operation.  After all chaining is completed, the
final host command cannot exceed 4096 bytes.  If a chaining operation
would exceed that amount, it is truncated to exactly 4096 bytes.



╔════════════════════════════════════╗
║ 4.8.6 ■ ADVANCED TEMPLATE CONCEPTS ║
╚════════════════════════════════════╝

You've already learned about Template Embedding and Template
Chaining.  These two methods of using templates do not need to be
separate methods.  You can combine these methods if you wish.  This
means that you can have embedded templates inside of template chains.
This provides for utter flexibility in doing whatever you want.

Here are a couple of examples of combinations:


   EXAMPLE 1
   ─────────
          [5:]EMBEDDED VALUE

          [3:]Here is a $?$ and an $?5$

          [3]CHAINED HOST COMMAND

     This would result in:

          Here is a CHAINED HOST COMMAND and an EMBEDDED VALUE


   EXAMPLE 2
   ─────────
          [5:]EMBEDDED VALUE

          [3:]Here is a $?$ and an $?5$
          [4:]print("$?$")

          [34]CHAINED HOST COMMAND

     This would result in:

          print("Here is a CHAINED HOST COMMAND and an EMBEDDED VALUE")


   EXAMPLE 3
   ─────────
          [4:](hello)
          [5:]ANOTHER $?5$ EMBEDDED $?4$ VALUE

          [3:]Here is a $?$ and $?5$

          [3]CHAINED COMMAND

     This would result in:

          Here is a CHAINED COMMAND and ANOTHER ANOTHER $?5$ EMBEDDED $?4$
          VALUE EMBEDDED (hello) VALUE


     Taking this one step-by-step:

          Step #1:   Here is a CHAINED COMMAND and $?5$



          Step #2:   Here is a CHAINED COMMAND and ANOTHER $?5$
                     EMBEDDED $?4$ VALUE

          Step #3:   Here is a CHAINED COMMAND and ANOTHER ANOTHER
                     $?5$ EMBEDDED $?4$ VALUE EMBEDDED (hello) VALUE

               <end of processing>


   EXAMPLE 4
   ─────────
          [5:]HELLO

          [3:]$?5$ $?$ WORLD

          [4:]print("$?$")^m

          [344](silly)

     This would result in:

          print("print("HELLO (silly) WORLD")^m")^m

Example #1 shows a situation with a single chaining operation and a
single embedding operation done at the same time.  You can see how
the final host command is in relation to the data fed into the
templates at different points.

Example #2 shows a more complex situation where multiple levels of
template chaining are going on while embedding is also being used.

Example #3 is somewhat different though.  Why weren't the embedded
template codes expanded at the lowest level of template #5?  If you
look closely at template #5, it has an insertion code instructing the
system to insert template #5 (itself) in the middle of the template.
This is legal, but only because an embedded template inside an
embedded template cannot have any more embedding performed on it.  In
other words, you are allowed up to two levels of embedded templates,
but the lowest level (2nd) cannot have any insertion codes, text
variables, control characters or pick-list definitions in it - if it
does, they will be treated as "raw" text instead of host command
directives.

Example #4 shows a more involved Template Chaining operation in which
the same template is chained to more than once in a given operation.
This is allowable for extra flexibility, although in the real world
will probably not be used much.



╔═════════════════════════════════════════════╗
║ 4.8.7 ■ HOST COMMAND LANGUAGE AND TEMPLATES ║
╚═════════════════════════════════════════════╝

Now that we have thouroughly discussed templates, we come upon
another subject - that of text variables, pop-up pick lists, and
control characters.  In any template definition or host command, you
can have text variables, pick lists or control characters anywhere.
This gives you the ability to do a great many things.

You can freely use text variables, control characters or pick lists
anywhere in a Direct Host Command, in a template chain and embedded
templates.  There is nothing unusual about text variables, pop-up
pick lists or control characters when they're used in template chains
or Direct Host Commands.  They do get a bit odd though in how they
interact with Embedded Templates - but only if you have an embedded
template within an embedded template.

Recall from a previous discussion about embedded templates within
embedded templates.  At the lowest level of the embedding, there is
no processing done on the string of text.  This is to prevent endless
loops and combinatorial explosion of data and CPU time.  Text
Variables, pick lists and control characters WILL be processed at the
first level of an embedded template, but not at the second level.

Here are some examples that better illustrate text variables:


     EXAMPLE 1
     ─────────
          [3:]The date is $DATE$ ... $?$

          [3]HELLO

       Results in:

          The date is 07/18/93 ... HELLO


     EXAMPLE 2
     ─────────
          [3:]The date is $DATE$

          HELLO THERE, $?3$

       Results in:

          HELLO THERE, The date is 07/18/93


     EXAMPLE 3
     ─────────
          [2:]The time is $TIME$^m
          [3:]The date is $DATE$^m

          HELLO THERE^m$?3$$?2$


       Results in:


          HELLO THERE
          The date is 07/18/93
          The time is 03:43:32


     EXAMPLE 4
     ─────────
          [1:]The day is $DOW$^m

          [2:]The time is $TIME$^m
          [3:]The date is $DATE$^m$?1$^m

          HELLO THERE^m($?3$)($?4$)($?1$)

       Results in:

          HELLO THERE
          (The date is 07/18/93)
          The day is $DOW$^m
          (The time is 03:43:32)
          (The day is Sunday)

       Notice how the $?1$ embedded template used in template #3 does
       not get processed - it is just inserted raw.



╔═════════════════════════════════╗
║ 4.8.8 ■ PROCESSING OF TEMPLATES ║
╚═════════════════════════════════╝

As stated previously, template definitions may contain text
variables, pick lists, control characters, and template insertion
codes.  When do these special "directives" get processed?  The answer
is when the template gets USED, not when it becomes ACTIVE!  To
better illustrate this, let's look at a simple example.

Let's say you have three radio buttons (group #2) on the screen and
another button (group #0) which uses the template for the radio
button group 3.  Here's the host command definitions for each of
these four buttons:

     Group #2 - Radio Button Group
     ─────────────────────────────
          Button #1:  [2:]It's a pretty day at $TIME$
          Button #2:  [2:]It's a rainy day at $TIME$
          Button #3:  [2:]It's a hazy day at $TIME$

     Group #0 - Ordinary button group
     ────────────────────────────────
          Button #4:  Today's forecast:^m$?2$

Now, let's say that none of the radio buttons are drawn as "selected"
for starters.  At 11:45:03 in the morning, the user clicks on button
#2 indicating it's a rainy day.  The active template for group #2
would be defined as:

          It's a rainy day at $TIME$

At 11:46:37 he clicks on the Forecast button.  What would be the host
command sent to the BBS in this example?  It would be:

          Today's forecast:
          It's a rainy day at 11:46:37

Notice that the time that is inserted in place of $TIME$ is the time
that the user clicked on the Forecast button, NOT the time he clicked
on the "rainy day" button which activated the proper template.  This
illustrates that text variables, pick lists, and control characters
are not "processed" until they are referenced (used) by some other
button or template in an active Host Command situation.



╔══════════════════════════════════════════════════╗
║ 4.8.9 ■ COMMAND BLOCK SEGMENTATION AND TEMPLATES ║
╚══════════════════════════════════════════════════╝

Near the beginning of our discussion of templates we spoke about
Direct Host Commands, Template Definitions and Template Execution.
You have seen how to define templates with a template definition
command like [3:]HELLO, and how to execute templates by either
Chaining (eg, "[3]WORLD"), or by using Embedded Templates
(eg, "$?3$ WORLD").

Now, remember that we spoke about how a single Host Command can be
segmented into multiple "Command Blocks" by separating them with the
delimiter "[]".  An example of this might be:

     HELLO^m[]WORLD^m

This would transmit the following to the BBS:

     HELLO<cr>
     WORLD<cr>

Realistically, you wouldn't use such an overly simple example like
this, but would use the following instead:

     HELLO^mWORLD^m

This would produce the same result.  But it doesn't illustrate the
purpose of Command Blocks.  Here's a real-world example of a host
command broken down into several command blocks:

  [3:]Template Definition[4]Template chaining[]BBS TEXT

If you look carefully at the above host command, three distinct
things are happening.  First, template #3 is defined with the text
"Template Definition".  Secondly, the phrase "Template chaining"
is chained (fed) into template #4 (whatever that one is) and the
final result of the chaining operation is sent to the BBS.  Finally,
the last command block is processed which happens to be a Direct Host
Command, so the text "BBS TEXT" will be transmitted to the Host as
well.

If a host command doesn't have one of the command block delimiters
like a template definition (eg, "[3:]"), or a template chain
directive (eg, "[3]"), or a Direct Host Command Directive (eg, "[]"),
then the Host Command is, by default, considered to be a Direct Host
Command.  The following are all considered Direct Host Commands and
they all do the exact same thing:

     HELLO^mWORLD^m
     HELLO^m[]WORLD^m
     []HELLO^mWORLD^m
     []HELLO^m[]WORLD^m

Here are some more examples of Command Blocks using the previous
example as a foundation, but this time we throw in another command
block.  Again, all four of these examples do the exact same thing:



     HELLO^mWORLD^m[3:]Template Definition
     HELLO^m[]WORLD^m[3:]Template Definition
     []HELLO^mWORLD^m[3:]Template Definition
     []HELLO^m[]WORLD^m[3:]Template Definition



╔════════════════════════════════════════════════════════╗
║ 4.8.10 ■ COMMAND BLOCKS, RADIO AND CHECK BOX TEMPLATES ║
╚════════════════════════════════════════════════════════╝

If you recall from our earlier discussions about Radio Buttons and
Check Box Buttons, the templates definitions are activated based upon
a Button being activated.  If you think about Command Blocks though,
you might be inclined to think that figuring out which template
definition block of a command block to activate might get insane.  It
could!  Look at the following set of three Radio Button definitions:

     Button #1:  [3:]Hello world[3:]This is Pluto
     Button #2:  [3:]Hello world[3:]This is Saturn
     Button #3:  [3:]Hello world[3:]This is Jupiter

What happens if button #2 is clicked, thus activating that template?
What template command block is used to create the final, active
template?  The answer is the last one!  The text that becomes the
actual active template for template #3 would be this:

     This is Saturn

If a Host Command references this template as in the following
example, you will see that the secondary template definition is
the one that is actually in use:

     I'm a martian singing in the rain^m$?3$

Resulting in:

     I'm a martian singing in the rain
     This is Saturn

In short, Command Blocks are processed in all situations, and if a
discrepency exists where two or more template definitions in the same
Host String correspond to the same template group, the last
definition is the one that becomes active.  This applies even if you
are dealing with Check Box buttons.  In the above example of the
martian, if Buttons #1, 2 and 3 were Check Box Buttons instead, the
"Hello World" template definitions would still be lost and would NOT
get concatenated together to create the final Host Command.  If
buttons #1 and #3 are clicked, then template #3 would be:

     This is PlutoThis is Jupiter

It would NOT be:

     Hello worldThis is PlutoHello worldThis is Jupiter



╔═════════════════════════════════════════════════════╗
║ 4.9 ■ HOST COMMANDS DIRECTIVES - WHAT CAN GO WHERE? ║
╚═════════════════════════════════════════════════════╝

With all this talk about Templates, Text Variables, Local RIP file
playback, pop-up pick lists and control characters, you might be
interested in knowing what can be used where in the RIPscrip
language.  It has already been stated that Templates can be used only
in Button Host Commands.  Text Variables, Local RIP file playback,
pop-up lists and control characters can be used in several places
though.  The places that these commands can be used and not used are
listed in the following chart:

                    ╔═════╤═════╤═════╤═════╤═════╤═════╗
                    ║  T  │ D V │   T │  P  │  C  │  L  ║
                    ║  E  │ A A │ A E │  I  │  T  │  O  ║
                    ║  M  │ T R │ C X │  C  │  R  │  C  ║
                    ║  P  │ A I │ T T │  K  │  L  │  A  ║
                    ║  L  │   A │ I   │     │     │  L  ║
                    ║  A  │ T B │ V V │  L  │  C  │     ║
                    ║  T  │ E L │ E A │  I  │  H  │  R  ║
                    ║  E  │ X E │   R │  S  │  A  │  I  ║
                    ║  S  │ T S │   S │  T  │  R  │  P  ║
                    ╠═════╪═════╪═════╪═════╪═════╪═════╣
                    ║     │     │     │     │     │     ║
Button Host Commands║  Y  │  Y  │  Y  │  Y  │  Y  │  Y  ║
                    ║     │     │     │     │     │     ║ Host
Simple Mouse Fields ║  N  │  Y  │  Y  │  Y  │  Y  │  Y  ║ Related
                    ║     │     │     │     │     │     ║ Commands
Query Command       ║  N  │  Y  │  Y  │  Y  │  Y  │  Y  ║
                    ║     │     │     │     │     │     ║
                    ╟─────┼─────┼─────┼─────┼─────┼─────╢
                    ║     │     │     │     │     │     ║
Button Labels       ║  N  │  Y  │  N  │  N  │  N  │  N  ║
                    ║     │     │     │     │     │     ║ Text Output
RIP_TEXT_XY         ║  N  │  Y  │  N  │  N  │  N  │  N  ║ Related
                    ║     │     │     │     │     │     ║ Commands
RIP_TEXT            ║  N  │  Y  │  N  │  N  │  N  │  N  ║
                    ║     │     │     │     │     │     ║
                    ╚═════╧═════╧═════╧═════╧═════╧═════╝



╔══════════════════════════════════════════════════════╗
║ 4.10 ■ THINGS TO TAKE SPECIAL CARE WITH HOST COMMANDS║
╚══════════════════════════════════════════════════════╝

Special care must be taken when executing Host Commands or Query
commands that contain local RIP file playback or that contain active
text variables.  Either of these operations could instruct RIPterm to
destroy all Mouse Fields by either performing a RIP_RESET_WINDOWS
command ($RESET$), a RIP_KILL_MOUSE_FIELDS command ($MKILL$), a
restore mouse fields text variable ($RMF$) or other such things.

If a situation like this happens, care should be taken to preserve
currently processed Host Buffer.  If it is a mouse field's host
command that is being processed, you wouldn't want your application
destroying the very buffer that you're processing before you're done
processing it, would you?  In the case of RIPterm, we do a sub-string
search on the Host buffer before any processing is done.  We search
for the following strings:

     $RMF$    ... Restore Mouse Fields
     $>       ... Beginning segment of a Local RIP playback command
     $APP     ... Instruction to execute an external application
     $RESET$  ... Performs a RIP_RESET_WINDOWS command
     $MKILL$  ... Destroys the contents of the internal mouse table

If any one of the above strings are found, RIPterm will physically
back-up the Host buffer into another location - one that won't be
destroyed by the execution of the above commands.  The processing of
the Host buffer is then done on the new buffer, not the actual
buffer.  In this way, the application can destroy the mouse table to
its heart's content but the processing of the buffer will not be
affected.



╔══════════════════════════════╗
║ 5 ■ TEXT VARIABLES REFERENCE ║
╚══════════════════════════════╝

This section details all of the pre-defined text variables in the     > v2.A4
RIPscrip language.  Each variable is described thoroughly, and where  > v2.A4
applicable, simple ANSI-C source code extracts are provided to show   > v2.A4
how to implement the variable under the C programming language.       > v2.A4



╔═════════════════════════════════════════╗
║ 5.1 ■ TEXT VARIABLE SYNTAX DESCRIPTIONS ║
╚═════════════════════════════════════════╝

Each text variable's description details the exact syntax of that
variable.  The syntax is described in concise detail so that you can
easily spot at the glance of an eye exactly what parameters are
allowed, and if omitted, what the default values are for those
parameters.  You can also determine what text variables have optional
parameters, and what parameters are required.

There are two basic text variables - those that take parameters, and
those that don't.  Those that don't use any parameters are the
simplest of all to describe syntactically.  If a text variable does
not require any parameters, then its syntax description would be
nearly identical to the following:

     Syntax:  $TEXTVAR$

This simply states that in order use this text variable in an
expression, you insert the text "$TEXTVAR$" in your host command.

For text variables that require parameters though, more detailed
descriptions are necessary.  Here is an example listing of a text
variable requiring one parameter and having an optional second
parameter:

     Syntax:  $TEXTVAR(req:PARAM1, opt:PARAM2)$

You should notice the text "req:" and "opt:".  The "req:PARAM1" text
indicates that the parameter named "PARAM1" is required.  The
second piece of text is "opt:PARAM2", which means that the parameter
named "PARAM2" is optional.

But what values can PARAM1 or PARAM2 be?  It's not mentioned at all
what values they can obtain.  This is where the parameter value
notation comes in.  Suppose that PARAM1 can be set to "TRUE" or
"FALSE", and that PARAM2 can be set to "BLUE" and "RED".  To
describe these values our new syntax description would be:

     Syntax:  $TEXTVAR(req:PARAM1, opt:PARAM2)$
                           ──────      ──────
                           TRUE        BLUE
                           FALSE       RED

From the above description, it is quite simple to determine what
parameters are required, which ones are optional, and which ones
can be set to what values.  Now, let's add a new color to PARAM2,
called "GREEN", and let's say that it can only be used as PARAM2 when
PARAM1 is equal to "TRUE".  We denote this like the following:

     Syntax:  $TEXTVAR(req:PARAM1, opt:PARAM2)$
                           ──────      ──────
                           TRUE        BLUE
                           FALSE       RED
                                       GREEN:PARAM1=TRUE

Notice the "GREEN:PARAM1=TRUE".  This means that PARAM2 can be set to
"GREEN" only if PARAM1 is equal to TRUE.  What if we added another
value to PARAM1 that could also be green, called "MAYBE".  Then our
example would look like this:


     Syntax:  $TEXTVAR(req:PARAM1, opt:PARAM2)$
                           ──────      ──────
                           TRUE        BLUE
                           FALSE       RED
                           MAYBE       GREEN:PARAM1=TRUE,MAYBE

Now the description of GREEN has "PARAM1=TRUE,MAYBE".  This means
that PARAM2 can be set to "GREEN" only if PARAM1 is equal to TRUE
or MAYBE.  Pretty simple.  This same situation could be written
more shortly (in this case) with the "not equal" expression <> as
in the following:

     Syntax:  $TEXTVAR(req:PARAM1, opt:PARAM2)$
                           ──────      ──────
                           TRUE        BLUE
                           FALSE       RED
                           MAYBE       GREEN:PARAM1<>FALSE

This means that PARAM2 can be set to GREEN only if PARAM1 is not
equal to FALSE.  If PARAM2 could only be set to GREEN if PARAM1 was
equal to TRUE, we could list this (using a previously described
notation):

     Syntax:  $TEXTVAR(req:PARAM1, opt:PARAM2)$
                           ──────      ──────
                           TRUE        BLUE
                           FALSE       RED
                           MAYBE       GREEN:PARAM1<>FALSE,MAYBE

Optional parameters do not need to be specified.  If they are not,
then some "suitable" default value will be used for that parameter.
Let's take a variation of our previous example:

     Syntax:  $TEXTVAR(req:PARAM1, opt:PARAM2)$
                           ──────      ──────
                           TRUE        BLUE
                           FALSE       RED
                           MAYBE       GREEN
                                       ──────
                                   def=BLUE

This says that if PARAM2 is omitted, that BLUE will be the default.
What if BLUE is only the default when PARAM1 is set to TRUE, and
RED is default all the other times?  Then you would have the
following syntax description:

     Syntax:  $TEXTVAR(req:PARAM1, opt:PARAM2)$
                           ──────      ──────
                           TRUE        BLUE
                           FALSE       RED
                           MAYBE       GREEN
                                       ──────
                                   def=BLUE:PARAM1=TRUE
                                       RED:PARAM1<>TRUE

Lastly, a number of text variables have a variable number of
parameters.  This means that one of the parameters can be repeated
more than once, but it must be specified at least once.  This is
represented in the actual text variable "short description" with
an ellipse "..." shown in the parameter list like the following:


     $TEXTVAR(param1,param2,...)$ - Perform some kind of operation

In the syntax description, it is also shown as an ellipse "...".  The
parameter immediately preceding the ellipse is the one that is
repeated and all subsequent instances of that parameter use the same
syntax as the first one repeated.  Here is an example if we allowed
PARAM2 to be repeated multiple times:

     Syntax:  $TEXTVAR(req:PARAM1, req:PARAM2, ...)$
                           ──────      ──────
                           TRUE        BLUE
                           FALSE       RED
                           MAYBE       GREEN
                                       ──────
                                   def:BLUE

Notice how PARAM2 is set to "req:".  This means that PARAM2 must be
specified at least once, but can be repeated.  It is also possible
that the repeated parameter itself may be optional (eg, "opt:").  If
this is the case then there can be zero or more occurrences of that
parameter.

If no specific default value is allowed for an omitted parameter (ie,
it has special significance if it is omitted), then the default value
would be listed as "<none>".



╔════════════════════════════════════════════════╗
║ 5.2 ■ VERSION NUMBER AND VENDOR TEXT VARIABLES ║
╚════════════════════════════════════════════════╝

These text variables are for version number, vendor determination,    > v2.A4
and software features of a RIPscrip package.  These are used heavily  > v2.A4
for "detecting" what kind of RIPscrip software a host is connected    > v2.A4
with.                                                                 > v2.A4


┌────────────────────────────────────────┐
│ 5.2.1 ■ $IFS$ ... Is Feature Supported │
└────────────────────────────────────────┘

Format:  $IFS(keyword,function)$
Syntax:  $IFS(req:KEYWORD,    opt:CATEGORY)$                          > v2.A4
                  ───────         ────────                            > v2.A4
                  LIST            ALL:KEYWORD=LIST                    > v2.A4
                  _AUDIO          _AUDIO:KEYWORD=LIST                 > v2.A4
                  _EMULATIONS     _EMULATIONS:KEYWORD=LIST            > v2.A4
                  _IMAGE          _IMAGE:KEYWORD=LIST                 > v2.A4
                  _LANGUAGES      _LANGUAGES:KEYWORD=LIST             > v2.A4
                  _MISC           _MISC:KEYWORD=LIST                  > v2.A4
                  _PROTOCOLS      _PROTOCOLS:KEYWORD=LIST             > v2.A4
                  ANSI            ────────                            > v2.A4
                  BMP         def=<none>                              > v2.A4
                  CISQUICKB                                           > v2.A4
                  DOORWAY                                             > v2.A4
                  ENG                                                 > v2.A4
                  EXTAPPS                                             > v2.A4
                  JPEG                                                > v2.A4
                  KERMIT                                              > v2.A4
                  RIPSCRIP                                            > v2.A4
                  SUPERKERMIT                                         > v2.A4
                  VT102                                               > v2.A4
                  WAV                                                 > v2.A4
                  XMODEM                                              > v2.A4
                  XMODEMCRC                                           > v2.A4
                  XMODEM1K                                            > v2.A4
                  XMODEM1KG                                           > v2.A4
                  YMODEM                                              > v2.A4
                  YMODEMG                                             > v2.A4
                  ZMODEM                                              > v2.A4
                  ZMODEMCR                                            > v2.A4

This is a unique and powerful text variable.  This is the mechanism   > v2.A2
by which the host can find out what capabilities are supported in the > v2.A2
remote terminal.  For example, if the host needs to know if the       > v2.A2
terminal supports JPEG files, the host could send a query:            > v2.A2

    !|1Σ0000$IFS(JPEG)$                                               > v2.A2

Note that the character "Σ" is actually an escape character (ASCII    > v2.A4
value 27).                                                            > v2.A4

The terminal would respond with `1' if it has JPEG display ability,   > v2.A4
or "0" if it doesn't.                                                 > v2.A4



Because the number of features supported by a software package can    > v2.A4
get quite extensive, they are categorized for the purposes of this    > v2.A4
command.  This allows the host to be able to query particular sub-    > v2.A4
sets of information (eg, what file transfer protocols are supported,  > v2.A4
etc).  These categories are simple keyword names just like the        > v2.A4
keyword names used to identify particular features, but with one      > v2.A4
slight difference.  Categories begin with an underscore character (_) > v2.A4
to differentiate them from actual feature keywords.  These categories > v2.A4
are used in conjunction with a special $IFS$ directive called LIST.   > v2.A4
This will list out all keywords for a specific category, or if no     > v2.A4
category is specified, it will list out all categories.  The basic    > v2.A4
categories and their corresponding sub-items are as follows:          > v2.A4

  Keyword/category  Description                                       > v2.A4
  ──────────────────────────────────────────────────────────────────  > v2.A4
  _IMAGE            Category:  what image formats are supported       > v2.A4
     JPEG           JPEG photographic image file format supported     > v2.A4
     BMP            BMP bitmap image file format supported            > v2.A4
  _AUDIO            Category:  what audio formats are supported       > v2.A4
     WAV            WAV digitized audio file format supported         > v2.A4
  _PROTOCOLS        Category:  file transfer protocols                > v2.A4
     KERMIT         Kermit file transfer protocol supported           > v2.A4
     CISQUICKB      Compuserve(TM) QuickB protocol supported          > v2.A4
     SUPERKERMIT    Super Kermit protocol supported                   > v2.A4
     XMODEM         X-Modem protocol supported                        > v2.A4
     XMODEMCRC      X-Modem protocol with CRC checking supported      > v2.A4
     XMODEM1K       X-Modem protocol with 1K blocks supported         > v2.A4
     XMODEM1KG      X-Modem protocol with 1K blocks / G supported     > v2.A4
     YMODEM         Y-Modem Batch protocol supported                  > v2.A4
     YMODEMG        Y-Modem protocol with G supported                 > v2.A4
     ZMODEM         Z-Modem protocol supported                        > v2.A4
     ZMODEMCR       Z-Modem protocol with Crash Recovery supported    > v2.A4
  _LANGUAGES        Category:  what languages are supported           > v2.A4
     ENG            English language is supported                     > v2.A4
  _EMULATIONS       Category:  what terminal emulations are supported > v2.A4
     RIPSCRIP       RIPscrip terminal emulation is supported          > v2.A4
     DOORWAY        Doorway (tm) mode is supported                    > v2.A4
     ANSI           ANSI terminal emulation supported                 > v2.A4
     VT102          DEC VT-102 terminal emulation supported           > v2.A4
  _MISC             Category:  miscellaneous features                 > v2.A4
     EXTAPPS        External applications are supported               > v2.A4

If you specify the LIST directive all by itself as in the text        > v2.A4
variable $IFS(LIST)$, then the categories will be returned in an      > v2.A4
alphabetical, comma-delimited list like this:                         > v2.A4

     Example:  $IFS(LIST)$                                            > v2.A4
     Returns:  _AUDIO,_EMULATIONS,_IMAGE,_LANGUAGES,_MISC,_PROTOCOLS  > v2.A4

You may list out a particular category by issuing an $IFS$ variable   > v2.A4
with the LIST keyword and the category as the second parameter as in  > v2.A4
the following example:                                                > v2.A4

     Example:  $IFS(LIST, _EMULATIONS)$                               > v2.A4
     Returns:  ANSI,DOORWAY,RIPSCRIP,VT102                            > v2.A4

One final LIST directive is the "ALL" directive.  This returns a list > v2.A4
of all feature keywords (omitting category keywords) in one very long > v2.A4
alphabetical, comma-delimited list.  This would be like asking for    > v2.A4
each category's listing separately then sorting the list of keywords  > v2.A4
and stringing them all together.  Here's an example of the above      > v2.A4


keywords being queried in ALL mode (note, we use an ellipse (...) at  > v2.A4
the end of the line to indicate continuation to the next line.        > v2.A4

     Example:  $IFS(LIST, ALL)$                                       > v2.A4
     Returns:  ANSI,BMP,CISQUICKB,DOORWAY,ENG,EXTAPPS,JPEG, ...       > v2.A4
               KERMIT,RIPSCRIP,SUPERKERMIT,VT102,WAV,XMODEM, ...      > v2.A4
               XMODEM1K,XMODEM1KG,XMODEMCRC,YMODEM,YMODEMG, ...       > v2.A4
               ZMODEM,ZMODEMCR                                        > v2.A4

If you omit all parameters from the $IFS$ variable, then it should    > v2.A4
be considered a text variable syntax error.                           > v2.A4

In the future, more categories will probably be added for different   > v2.A4
purposes like hardcopy support, network support and many other        > v2.A4
things.  That is why this command has been designed with such         > v2.A4
flexibility in mind.                                                  > v2.A4

Note that the comma-delimited list of keywords returned from a LIST   > v2.A4
directive are alphatbetically sorted and have no spaces in them.  In  > v2.A4
addition, there are no carriage returns or any other form of          > v2.A4
delimiter after the last keyword returned.  If you wish to have a     > v2.A4
carriage return after the list, place a ^M control character          > v2.A4
directive in the query command that you used to work with this        > v2.A4
text variable.                                                        > v2.A4

Note, a category must have at least one keyword defined underneath    > v2.A4
it in order for it to be considered "defined".                        > v2.A4

If a LIST directive is specified on a category that doesn't exist,
then nothing is returned to the host (a null string).  If a specific
keyword is inquired about and it doesn't exist, a "0" is returned to
indicate that the feature isn't supported.


┌───────────────────────────────────────────────────────────┐
│ 5.2.2 ■ $NULL$ ... A null text variable (returns nothing) │
└───────────────────────────────────────────────────────────┘

Format:  $NULL$
Syntax:  $NULL$                                                       > v2.A4

This text variable is a special variable.  It always returns nothing  > v2.A1
to the host system.  It doesn't prompt the user or any information    > v2.A1
and it doesn't set anything.  It is intended to be a place-holder for > v2.A1
commands that require a text parameter (RIP_MOUSE, RIP_BUTTON and     > v2.A4
RIP_QUERY).  When you have this text variable all by itself in a host > v2.A4
command, it makes the host command do absolutely nothing, but has     > v2.A1
something defined for the host command to satisfy the RIPscrip        > v2.A1
interpreter (which expects something to be defined in host command    > v2.A1
text parameters).                                                     > v2.A1

     Example:  $NULL$                                                 > v2.A1
     Returns:  nothing                                                > v2.A1



┌────────────────────────────────────────────────────────────────┐
│ 5.2.3 ■ $RIPVER$ ... RIPscrip version (e.g., "RIPSCRIP015300") │
└────────────────────────────────────────────────────────────────┘

Format:  $RIPVER$
Syntax:  $RIPVER$                                                     > v2.A4

This Text Variable returns a phrase which will identify a
RIPscrip-compatible software package.  It is designed to be used by a
host to detect what version of RIPscrip graphics your terminal can
support as well as the type (brand) of RIPscrip terminal that is in
use.  When this Text Variable is used, it will respond back with
"RIPSCRIP" followed by the Version Number (e.g., "01.54"), followed   > v1.54
by two digits identifying the Vendor of the terminal.  The first      > v1.54
digit of the Vendor ID field is the Vendor Code (1=RIPterm).  The     > v1.54
second digit is the Vendor's sub-version code identifying sub-        > v1.54
versions of the software that still support the same RIPscrip         > v1.54
software version.  Valid Vendor Codes are:                            > v1.54

     CODE   VENDOR                                                    > v1.54
     ─────────────────────────────────────────────────                > v1.54
       0    Generic RIPscrip terminal (vendor unknown)                > v1.54
       1    RIPterm (from TeleGrafix Communications)                  > v1.54
       2    Qmodem Pro (from Mustang Software, Inc)                   > v1.54

See the section earlier in this document on ANSI sequences for a      > v1.54
more robust description of the Vendor Codes and Auto-Sensing.         > v1.54

     Example:  $RIPVER$
     Returns:  RIPSCRIP015300


┌─────────────────────────────────────────────────────┐
│ 5.2.4 ■ $TERMINFO$ ... Returns vendor specific data │
└─────────────────────────────────────────────────────┘

Format:  $TERMINFO(keyword)$
Syntax:  $TERMINFO(opt:KEYWORD)$                                      > v2.A4
                       ───────                                        > v2.A4
                       NAME                                           > v2.A4
                       VENDOR                                         > v2.A4
                       VERSION                                        > v2.A4
                       LIST                                           > v2.A4
                       ───────                                        > v2.A4
                   def=NAME                                           > v2.A4

This text variable returns specific information about the RIPscrip    > v2.A4
software package in use by the terminal (remote) user.  If no         > v2.A4
parameter is specified, for example, $TERMINFO$ or $TERMINFO()$, then > v2.A4
the sequence returned to the host is the name of the terminal (see    > v2.A4
the "NAME" keyword below).  Otherwise, you may specify a particular   > v2.A4
terminal information keyword to request information about.  If the    > v2.A4
specific keyword is undefined (ie, not used by the terminal), a value > v2.A4
of "NONE" will be returned.                                           > v2.A4

The following keywords are prerequisites for any generic RIPscrip     > v2.A4
2.0 terminal system and must be implemented.  You may add as many     > v2.A4
more as you wish, but these following keywords must be defined:       > v2.A4


     Keyword        Description                                       > v2.A4
     ──────────────────────────────────────────────────────────────   > v2.A4
     NAME           Name of the software (default with no parameter). > v2.A4
                    Example "RIPterm Professional".                   > v2.A4
     VENDOR         Name of the company who wrote the software.       > v2.A4
                    Example, "TeleGrafix Communications, Inc."        > v2.A4
     VERSION        The Version number of the software.  For          > v2.A4
                    example, "2.00.00".                               > v2.A4
     LIST           List all allowable keywords (see below).          > v2.A4

The text returned to the host is not terminated with any carriage     > v2.A4
returns or anything like that.  It's up to you to provide that kind   > v2.A4
of information in a button's host string or in a query string.  The   > v2.A4
LIST directive though returns a list of all recognized keywords for   > v2.A4
that terminal.  For example, RIPterm Pro returns the following        > v2.A4
for the $TERMINFO(LIST)$ expression:                                  > v2.A4

     LIST,NAME,VENDOR,VERSION                                         > v2.A4

Note, the list is comma (,) delimited between keywords, but not after > v2.A4
the last keyword.  In addition, the keywords are returned in          > v2.A4
alphabetical order, converted to all capitals.                        > v2.A4

     Example:  $TERMINFO$                                             > v2.A4
     Returns:  RIPterm Professional                                   > v2.A4

     Example:  $TERMINFO(NAME)$                                       > v2.A4
     Returns:  RIPterm Professional                                   > v2.A4

     Example:  $TERMINFO(VERSION)$                                    > v2.A4
     Returns:  2.00.00                                                > v2.A4

     Example:  $TERMINFO(VENDOR)$                                     > v2.A4
     Returns:  TeleGrafix Communications, Inc.                        > v2.A4

     Example:  $TERMINFO(LIST)$                                       > v2.A4
     Returns:  LIST,NAME,VENDOR,VERSION                               > v2.A4

     Example:  $TERMINFO(GOOSE)$                                      > v2.A4
     Returns:  NONE                                                   > v2.A4


╔══════════════════════════════════════════════╗
║ 5.3 ■ DATE AND TIME RETURNING TEXT VARIABLES ║
╚══════════════════════════════════════════════╝

These text variables return information on the current date and/or    > v2.A4
the current time.                                                     > v2.A4



┌────────────────────────────────────────────┐
│ 5.3.1 ■ $ADOW$ ... Abbreviated Day of Week │
└────────────────────────────────────────────┘

Format:  $ADOW$
Syntax:  $ADOW$                                                       > v2.A4

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


┌───────────────────────────────────────────────────────┐
│ 5.3.2 ■ $AMPM$ ... Returns AM or PM depending on time │
└───────────────────────────────────────────────────────┘

Format:  $AMPM$
Syntax:  $AMPM$                                                       > v2.A4

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

     Example:  $AMPM$
     Returns:  PM


┌─────────────────────────────────────────┐
│ 5.3.3 ■ $DATE$ ... Date in short format │
└─────────────────────────────────────────┘

Format:  $DATE$
Syntax:  $DATE$                                                       > v2.A4

This Text Variable returns the current date. in the format MM/DD/YY.

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


┌──────────────────────────────────────┐
│ 5.3.4 ■ $DATETIME$ ... Date and Time │
└──────────────────────────────────────┘

Format:  $DATETIME$
Syntax:  $DATETIME$                                                   > v2.A4

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.


┌───────────────────────────────────────┐
│ 5.3.5 ■ $DAY$ ... Day of Month Number │
└───────────────────────────────────────┘

Format:  $DAY$
Syntax:  $DAY$                                                        > v2.A4

This Text Variable returns the current day of the month.  Possible
values for this Variable are from 01-31.

     Example:  $DAY$
     Returns:  05


┌─────────────────────────────────────────────────┐
│ 5.3.6 ■ $DOW$ ... Day of week fully spelled out │
└─────────────────────────────────────────────────┘

Format:  $DOW$
Syntax:  $DOW$                                                        > v2.A4

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


┌───────────────────────────────┐
│ 5.3.7 ■ $DOY$ ... Day of year │
└───────────────────────────────┘

Format:  $DOY$
Syntax:  $DOY$                                                        > v2.A4

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


┌──────────────────────────────────┐
│ 5.3.8 ■ $FYEAR$ ... 4 digit year │
└──────────────────────────────────┘

Format:  $FYEAR$
Syntax:  $FYEAR$                                                      > v2.A4
This Text Variable returns the four-digit number of the current year.

     Example:  $FYEAR$
     Returns:  1993



┌────────────────────────────────────────────────────┐
│ 5.3.9 ■ $HOUR$ ... Hour (format HH) - normal style │
└────────────────────────────────────────────────────┘

Format:  $HOUR$
Syntax:  $HOUR$                                                       > v2.A4

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


┌────────────────────────────────────────────────────────┐
│ 5.3.10 ■ $MHOUR$ ... Hour (format HH) - military style │
└────────────────────────────────────────────────────────┘

Format:  $MHOUR$
Syntax:  $MHOUR$                                                      > v2.A4

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


┌────────────────────────────┐
│ 5.3.11 ■ $MIN$ ... Minutes │
└────────────────────────────┘

Format:  $MIN$
Syntax:  $MIN$                                                        > v2.A4

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


┌─────────────────────────────────┐
│ 5.3.12 ■ $MONTH$ ... Month Name │
└─────────────────────────────────┘

Format:  $MONTH$
Syntax:  $MONTH$                                                      > v2.A4

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



┌──────────────────────────────────────┐
│ 5.3.13 ■ $MONTHNUM$ ... Month Number │
└──────────────────────────────────────┘

Format:  $MONTHNUM$
Syntax:  $MONTHNUM$                                                   > v2.A4

This Text Variable returns the number of the current month.
January=01 and December=12.

     Example:  $MONTHNUM$
     Returns:  12


┌────────────────────────────┐
│ 5.3.14 ■ $SEC$ ... Seconds │
└────────────────────────────┘

Format:  $SEC$
Syntax:  $SEC$                                                        > v2.A4

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

     Example:  $SEC$
     Returns:  59


┌─────────────────────────────────────────────┐
│ 5.3.15 ■ $TIME$ ... Time in standard format │
└─────────────────────────────────────────────┘

Format:  $TIME$
Syntax:  $TIME$                                                       > v2.A4

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


┌────────────────────────────────────────────────────────┐
│ 5.3.16 ■ $TIMEZONE$ ... Time Zone or "NONE" if unknown │
└────────────────────────────────────────────────────────┘

Format:  $TIMEZONE$
Syntax:  $TIMEZONE$                                                   > v2.A4

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


┌─────────────────────────────────┐
│ 5.3.17 ■ $WDAY$ ... Day of Week │
└─────────────────────────────────┘

Format:  $WDAY$
Syntax:  $WDAY$                                                       > v2.A4

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


┌───────────────────────────────────────────────────────────────────────┐
│ 5.3.18 ■ $WOY$ ... Week of current year 00-53; Sunday=1st Day of Week │
└───────────────────────────────────────────────────────────────────────┘

Format:  $WOY$
Syntax:  $WOY$                                                        > v2.A4

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


┌────────────────────────────────────────────────────────────────────────┐
│ 5.3.19 ■ $WOYM$ ... Week of current year 00-53; Monday=1st Day of Week │
└────────────────────────────────────────────────────────────────────────┘

Format:  $WOYM$
Syntax:  $WOYM$                                                       > v2.A4

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



┌──────────────────────────────────┐
│ 5.3.20 ■ $YEAR$ ... 2 digit year │
└──────────────────────────────────┘

Format:  $YEAR$
Syntax:  $DOY$                                                        > v2.A4

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

     Example:  $YEAR$
     Returns:  93



╔════════════════════════════════════╗
║ 5.4 ■ SOUND RELATED TEXT VARIABLES ║
╚════════════════════════════════════╝

These text variables generate different kinds of sounds.              > v2.A4


┌─────────────────────────────────────────────────────────────┐
│ 5.4.1 ■ $ALARM$ ... Warning!  This sound indicates failure! │
└─────────────────────────────────────────────────────────────┘

Format:  $ALARM(count)$
Syntax:  $ALARM(opt:COUNT)$                                           > v2.A4
                    ─────                                             > v2.A4
                    1-65535                                           > v2.A4
                    ─────                                             > v2.A4
                def=3                                                 > v2.A4

This Active Text Variable produces a warning sound, indicating
failure of an action.  This sound is used for aborted downloads.

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

The C source code to play this sound is:

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


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


┌────────────────────────────────────────────┐
│ 5.4.2 ■ $BEEP$ ... Beep Sound (ala Ctrl-G) │
└────────────────────────────────────────────┘

Format:  $BEEP(frequency,length)$
Syntax:  $BEEP(opt:FREQUENCY, opt:LENGTH)$                            > v2.A4
                   ─────────      ──────                              > v2.A4
                   1-65535        1-65535                             > v2.A4
                   ─────────      ──────                              > v2.A4
               def=1000       def=75                                  > v2.A4

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

This command allows you to specify no parameters (default settings),  > v2.A4
only one parameter (the frequency), or both parameters (frequency and > v2.A4
length/duration).  Under no circumstances will values for any of the  > v2.A4
two parameters above 65535 be permitted.  If values above these       > v2.A4


limits are encountered then the variable is not processed.            > v2.A4

Note that this text variable has a 75 millisecond delay after the     > v2.A4
beep is complete where no sound is playing.  Stringing multiple       > v2.A4
beeps together will have a noticable gap between the sounds.  To      > v2.A4
play continuous tones at different frequencies, use multiple $T$      > v2.A4
variables (see below).                                                > v2.A4

The C source code to play this sound is:

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

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


┌──────────────────────────────────────────────────────────────┐
│ 5.4.3 ■ $BLIP$ ... Blipping Sound (like a hitting a barrier) │
└──────────────────────────────────────────────────────────────┘

Format:  $BLIP(freq,length)$
Syntax:  $BLIP(opt:FREQUENCY, opt:LENGTH)$                            > v2.A4
                   ─────────      ──────                              > v2.A4
                   1-65535        1-65535                             > v2.A4
                   ─────────      ──────                              > v2.A4
               def=50         def=25                                  > v2.A4

This Active Text Variable is like $BEEP$, except the sound is
different.  It produces a barrier sound; like you're running into a
wall.

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

This command allows you to specify no parameters (default settings),  > v2.A4
only one parameter (the frequency), or both parameters (frequency and > v2.A4
length/duration).  Under no circumstances will values for any of the  > v2.A4
two parameters above 65535 be permitted.  If values above these       > v2.A4
limits are encountered then the variable is not processed.            > v2.A4

The C source code to play this sound is:

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

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



┌──────────────────────────────────────────────┐
│ 5.4.4 ■ $MUSIC$ ... Musical (cheerful) sound │
└──────────────────────────────────────────────┘

Format:  $MUSIC(count)$
Syntax:  $MUSIC(opt:COUNT)$                                           > v2.A4
                    ─────                                             > v2.A4
                    1-65535                                           > v2.A4
                    ─────                                             > v2.A4
                def=4                                                 > v2.A4

This Active Text Variable produces a cheerful sound, indicating
success of an action.  This sound is used for successful downloads
and dialed connections.

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

The C source code to play this sound is:

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


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


┌────────────────────────────────────┐
│ 5.4.5 ■ $PHASER$ ... Fire phasers! │
└────────────────────────────────────┘

Format:  $PHASER(start,stop,inc,time)$
Syntax:  $PHASER(opt:START, opt:STOP, opt:INCREMENT, opt:TIME)$       > v2.A4


                 opt:START      opt:STOP                              > v2.A4
                     ─────          ────                              > v2.A4
                     1-65535        START-65535                       > v2.A4
                     ───────        ────                              > v2.A4
                 def=2500       def=50                                > v2.A4


                 opt:INCREMENT  opt:TIME                              > v2.A4
                     ─────────      ────                              > v2.A4
                     1-65535        1-65535                           > v2.A4
                     ─────────      ────                              > v2.A4
                 def=20         def=2                                 > v2.A4


This Active Text Variable produces a sound like firing your energy
weapons in a game.  Now you too can blast away with the best of them.
Trivia question:  What does phaser stand for?  See $REVPHASERS$ for
the answers.

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

This command allows you to specify no parameters (default settings),  > v2.A4
only one parameter (the starting frequency), two parameters (start    > v2.A4
and end frequency), three parmaters (start and end frequency as well  > v2.A4
as the increment frequency), or finally all four parameters which     > v2.A4
correspond to the start and stop frequencies, the increment frequency > v2.A4
and lastly the increment time delay (in milliseconds).  Under no      > v2.A4
circumstances will values for any of the four parameters above 65535  > v2.A4
be permitted.  If values above these limits are encountered then the  > v2.A4
variable is not processed.                                            > v2.A4

The C source code to play this sound is:

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


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


┌───────────────────────────────────────┐
│ 5.4.6 ■ $REVPHASER$ ... Fire phasers! │
└───────────────────────────────────────┘

Format:  $REVPHASER(start,stop,inc.time)$
Syntax:  $REVPHASER(opt:START, opt:STOP,   opt:INCREMENT, opt:TIME)$  > v2.A4


                    opt:START      opt:STOP                           > v2.A4
                        ─────          ────                           > v2.A4
                        1-65535        1-START                        > v2.A4
                        ─────          ────                           > v2.A4
                    def=50         def=2500                           > v2.A4


                    opt:INCREMENT  opt:TIME                           > v2.A4
                        ─────────      ────                           > v2.A4
                        1-65535        1-65535                        > v2.A4
                        ─────────      ────                           > v2.A4
                    def=20         def=2                              > v2.A4



This Active Text Variable produces a sound like firing your energy
weapons in a game.  Like $PHASER$ makes an ascending tone,
$REVPHASER$ makes a descending tone.  Answer to trivia question in
$PHASER$: Phaser stands for PHoton Amplification by Stimulated
Emission of Radiation.  Sound familiar?  Laser is Light Amplification
by Stimulated Emission of Radiation, and Maser is Microwave
Amplification by Stimulated Emission of Radiation.

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

This command allows you to specify no parameters (default settings),  > v2.A4
only one parameter (the starting frequency), two parameters (start    > v2.A4
and end frequency), three parmaters (start and end frequency as well  > v2.A4
as the increment frequency), or finally all four parameters which     > v2.A4
correspond to the start and stop frequencies, the increment frequency > v2.A4
and lastly the increment time delay (in milliseconds).  Under no      > v2.A4
circumstances will values for any of the four parameters above 65535  > v2.A4
be permitted.  If values above these limits are encountered then the  > v2.A4
variable is not processed.                                            > v2.A4

The C source code to play this sound is:

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

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


┌──────────────────────────────────────────┐
│ 5.4.7 ■ $T$ ... Play a simple audio tone │
└──────────────────────────────────────────┘

Format:  $T(freq,length)$
Syntax:  $T(opt:FREQUENCY, opt:LENGTH)$                               > v2.A4
                ─────────      ──────                                 > v2.A4
                1-65535        1-65535                                > v2.A4
                ─────────      ──────                                 > v2.A4
            def=1000       def=75                                     > v2.A4

This Active Text Variable produces an audible sound.  Both parameters > v2.A4
are required.  The <freq> parameter determines the frequency in Hertz > v2.A4
and the <length> parameter determines the duration of the tone in     > v2.A4
milliseconds.                                                         > v2.A4
frequency is assumed to be 1000 Hertz and the length of time that it  > v2.A4
should play is 75 milliseconds.                                       > v2.A4

Under no circumstances will values for any of the two parameters      > v2.A4
above 65535 be permitted.  If values above these limits are           > v2.A4
encountered then the variable is not processed.                       > v2.A4


Unlike the $BEEP$ command, this variable has no pause after the sound > v2.A4
stops playing, thus allowing you to string multiple $T$ variables     > v2.A4
together in rapid succession to produce musical notes.                > v2.A4

The C source code to play this sound is:                              > v2.A4

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

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



╔════════════════════════════════════╗
║ 5.5 ■ MOUSE RELATED TEXT VARIABLES ║
╚════════════════════════════════════╝

These text variables return information on, or manipulate the mouse   > v2.A4
in some fashion.                                                      > v2.A4


┌──────────────────────────────────────────┐
│ 5.5.1 ■ $M$ ... Mouse Button Status: LMR │
└──────────────────────────────────────────┘

Format:  $M$
Syntax:  $M$                                                          > v2.A4

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


┌─────────────────────────────────────────────────────────┐
│ 5.5.2 ■ $MCURSOR$ ... Set the mouse cursor style number │
└─────────────────────────────────────────────────────────┘

Format:  $MCURSOR(cursor_no)$
Syntax:  $MCURSOR(opt:CURSOR_NO)$                                     > v2.A4
                      ─────────                                       > v2.A4
                      0-6                                             > v2.A4
                      ─────────                                       > v2.A4
                  def=0                                               > v2.A4

This command changes the current mouse cursor style to one of the     > v2.A1
pre-defined mouse cursor styles as defined in the                     > v2.A1
RIP_SET_MOUSE_CURSOR command.  The cursor_no parameter is identical   > v2.A1
to the cursor style numbers permitted for the RIPscrip command to     > v2.A1
alter the cursor.  If you omit the CURSOR_NO parameter, the default   > v2.A1
"pointer" cursor is activated.                                        > v2.A1



┌──────────────────────────────────┐
│ 5.5.3 ■ $MSTAT$ ... Mouse Status │
└──────────────────────────────────┘

Format:  $MSTAT$
Syntax:  $MSTAT$                                                      > v2.A4

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


┌──────────────────────────────────┐
│ 5.5.4 ■ $X$ ... X Mouse location │
└──────────────────────────────────┘

Format:  $X(domain)$
Syntax:  $X(opt:DOMAIN)$                                              > v2.A4
                ──────                                                > v2.A4
                WORLD                                                 > v2.A4
                DEVICE                                                > v2.A4
                ──────                                                > v2.A4
            def=WORLD (except under "text mode query - see below)     > v2.A4


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.

If this text variable is used inside a "text window query", then the  > v2.A4
X coordinate is returned in text cell coordinates based on the        > v2.A4
internal dimensions of the text window.  This kind of result cannot   > v2.A4
happen unless the user clicks inside a text window's display area     > v2.A4
that has a text window query command in it, so there's no possibility > v2.A4
for the coordinate to be out of bounds for that text window's         > v2.A4
dimensions.                                                           > v2.A4

The results are in current world coordinates if no parameter is       > v2.A1
specified.  If TYPE is "DEVICE" then the result is in raw video       > v2.A4
device coordinates.  If TYPE is "WORLD" then the result is in desktop > v2.A4
world coordinates.  If the domain parameter is specified when this    > v2.A4
text variable is used in a text mode query, then it is explicitly     > v2.A4
overiding the "text coordinate" defaults of this command and          > v2.A4
returning the mouse coordinate information in the desired coordinate  > v2.A4
system.                                                               > v2.A4

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



┌─────────────────────────────────────┐
│ 5.5.5 ■ $XY$ ... X/Y Mouse Location │
└─────────────────────────────────────┘

Format:  $XY(domain)$
Syntax:  $XY(opt:DOMAIN)$                                             > v2.A4
                 ──────                                               > v2.A4
                 WORLD                                                > v2.A4
                 DEVICE                                               > v2.A4
                 ──────                                               > v2.A4
             def=WORLD (except under text mode query - see below)     > v2.A4

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

If this text variable is used inside a "text window query", then the  > v2.A4
X/Y coordinates are returned in text cell coordinates based on the    > v2.A4
internal dimensions of the text window.  This kind of result cannot   > v2.A4
happen unless the user clicks inside a text window's display area     > v2.A4
that has a text window query command in it, so there's no possibility > v2.A4
for the coordinate to be out of bounds for that text window's         > v2.A4
dimensions.  The format that the coordinates are returned in is XX:YY > v2.A4
where XX and YY can range from 00-99.                                 > v2.A4

The results are in current world coordinates if no parameter is       > v2.A1
specified.  If TYPE is "DEVICE" then the results are in raw video     > v2.A4
device coordinates.  If TYPE is "WORLD" then the results are in       > v2.A4
desktop world coordinates.  If the domain parameter is specified when > v2.A4
this text variable is used in a text mode query, then it is           > v2.A4
explicitly overiding the "text coordinate" defaults of this command   > v2.A4
and returning the mouse coordinate information in the desired         > v2.A4
coordinate system.                                                    > v2.A4

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


┌────────────────────────────────────────┐
│ 5.5.6 ■ $XYM$ ... X, Y & button status │
└────────────────────────────────────────┘

Format:  $XYM(domain)$
Syntax:  $XYM(opt:DOMAIN)$                                            > v2.A4
                  ──────                                              > v2.A4
                  WORLD                                               > v2.A4
                  DEVICE                                              > v2.A4
                  ──────                                              > v2.A4
              def=WORLD (except under text mode query - see below)    > v2.A4

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


If this text variable is used inside a "text window query", then the  > v2.A4
X/Y coordinates are returned in text cell coordinates based on the    > v2.A4
internal dimensions of the text window.  This kind of result cannot   > v2.A4
happen unless the user clicks inside a text window's display area     > v2.A4
that has a text window query command in it, so there's no possibility > v2.A4
for the coordinate to be out of bounds for that text window's         > v2.A4
dimensions.  The format that the coordinates are returned in is       > v2.A4
XX:YY:LMR where XX and YY can range from 00-99.                       > v2.A4

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

The results are in current world coordinates if no parameter is       > v2.A1
specified.  If TYPE is "DEVICE" then the results are in raw video     > v2.A4
device coordinates.  If TYPE is "WORLD" then the results are in       > v2.A4
desktop world coordinates.  If the domain parameter is specified when > v2.A4
this text variable is used in a text mode query, then it is           > v2.A4
explicitly overiding the "text coordinate" defaults of this command   > v2.A4
and returning the mouse coordinate information in the desired         > v2.A4
coordinate system.                                                    > v2.A4

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


┌──────────────────────────────────┐
│ 5.5.7 ■ $Y$ ... Y Mouse location │
└──────────────────────────────────┘

Format:  $Y(domain)$
Syntax:  $Y(opt:DOMAIN)$                                              > v2.A4
                ──────                                                > v2.A4
                WORLD                                                 > v2.A4
                DEVICE                                                > v2.A4
                ──────                                                > v2.A4
            def=WORLD (except under text mode query - see below)      > v2.A4

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.

If this text variable is used inside a "text window query", then the  > v2.A4
Y coordinate is returned in text cell coordinates based on the        > v2.A4
internal dimensions of the text window.  This kind of result cannot   > v2.A4
happen unless the user clicks inside a text window's display area     > v2.A4
that has a text window query command in it, so there's no possibility > v2.A4
for the coordinate to be out of bounds for that text window's         > v2.A4
dimensions.                                                           > v2.A4

The results are in current world coordinates if no parameter is       > v2.A1
specified.  If TYPE is "DEVICE" then the result is in raw video       > v2.A4
device coordinates.  If TYPE is "WORLD" then the result is in desktop > v2.A4
world coordinates.  If the domain parameter is specified when this    > v2.A4
text variable is used in a text mode query, then it is explicitly     > v2.A4
overiding the "text coordinate" defaults of this command and          > v2.A4
returning the mouse coordinate information in the desired coordinate  > v2.A4
system.                                                               > v2.A4


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



╔═════════════════════════════════════════╗
║ 5.6 ■TEXT WINDOW RELATED TEXT VARIABLES ║
╚═════════════════════════════════════════╝

These text variables return information on, or manipulate the text    > v2.A4
window.                                                               > v2.A4


┌──────────────────────────────────────────────────────┐
│ 5.6.1 ■ $ATW$ ... Activates a text window definition │
└──────────────────────────────────────────────────────┘

Format:  $ATW(window1,window2,...)$
Syntax:  $ATW(opt:WINDOW1, ...)$                                      > v2.A4
                  ───────                                             > v2.A4
                  ALL                                                 > v2.A4
                  CUR                                                 > v2.A4
                  0-35                                                > v2.A4
                  ───────                                             > v2.A4
              def=CUR                                                 > v2.A4

This command does the exact opposite of the $DTW$ text variable which > v2.A1
deactivates a text window.  When a window is activated, it no longer  > v2.A4
discards raw ANSI text that is sent to it.  This does not make        > v2.A1
any visual changes on the screen immediately unless the current text  > v2.A1
window is the one activated, whereby the cursor might appear all of a > v2.A1
sudden.                                                               > v2.A1

You may specify one or more parameters to indicate that you wish to   > v2.A4
activate more than one text window in the same $ATW$ statement.  If   > v2.A4
any one of them fails to match the proper parameters, then the entire > v2.A4
command is considered a syntax error and none of the parameters are   > v2.A4
processed.                                                            > v2.A4

If the text window being activated is protected, then it is not       > v2.A4
changed (ie, activated).                                              > v2.A4

You may activate more then one window by specifying multiple text     > v2.A$
window slot numbers (0-35).  You may also specify the following:      > v2.A1

            ALL ... Activate all text windows at once                 > v2.A4
            CUR ... Activate only the current text window             > v2.A4

     Example:  $ATW(CUR)$                                             > v2.A1
     Returns:  nothing                                                > v2.A1


┌────────────────────────────────────────────┐
│ 5.6.2 ■ $COFF$ ... Disable the Text Cursor │
└────────────────────────────────────────────┘

Format:  $COFF(window1,window2,...)$
Syntax:  $COFF(opt:WINDOW1, ...)$                                     > v2.A4
                   ───────                                            > v2.A4
                   ALL                                                > v2.A4
                   CUR                                                > v2.A4
                   0-35                                               > v2.A4
                   ───────                                            > v2.A4
               def=CUR                                                > v2.A4


This Active Text Variable turns off the text cursor in the specified  > v2.A4
text window(s).  If that text window(s) is undefined or disabled,     > v2.A4
this this command does nothing for that parameter.  If the window     > v2.A4
parameters are omitted, then the cursor in the current text window is > v2.A4
displayed.  If the window parameter(s) are specified, then they can   > v2.A4
be a value from 0-35 to indicate a specific text window data table    > v2.A4
entry, the value "CUR" to indicate the current text window, or the    > v2.A4
value of "ALL" to indicate that you wish to turn off the cursor in    > v2.A4
all text windows simultaneously.                                      > v2.A4

If you attempt to turn off a cursor in a text window that isn't       > v2.A4
defined, or that is deactivated, then that parameter does nothing.    > v2.A4

If any one of the parameters is invalid, then the entire command is   > v2.A4
considered a syntax error and none of the parameters are processed.   > v2.A4

If you turn off the cursor in a text window other than the current    > v2.A4
text window, then only the internal cursor status of that text window > v2.A4
is altered.  Since the cursor wouldn't be visible in that text window > v2.A4
anyway, you wouldn't expect anything to visually happen on the        > v2.A4
screen.  If you switch to that text window though, the cursor would   > v2.A4
not be displayed upon switching to it (normally it would).            > v2.A4

     Example:  $COFF$
     Returns:  nothing


┌──────────────────────────────────────────┐
│ 5.6.3 ■ $CON$ ... Enable the Text Cursor │
└──────────────────────────────────────────┘

Format:  $CON(window1,window2,...)$
Syntax:  $CON(opt:WINDOW1, ...)$                                      > v2.A4
                  ───────                                             > v2.A4
                  ALL                                                 > v2.A4
                  CUR                                                 > v2.A4
                  0-35                                                > v2.A4
                  ───────                                             > v2.A4
              def=CUR                                                 > v2.A4

This Active Text Variable turns on the text cursor in the specified   > v2.A4
text window(s).  If that text window is undefined or deactivated,     > v2.A4
this command does nothing.  If the window parameter(s) are omitted,   > v2.A4
then the cursor in the current text window is displayed.  If the      > v2.A4
window parameter is specified, then it can be a value from 0-35 to    > v2.A4
indicate a specific text window data table entry, the value "CUR" to  > v2.A4
indicate the current text window, or the value "ALL" to indicate all  > v2.A4
defined text windows (ie, in use).                                    > v2.A4

If you attempt to turn on a cursor in a text window that isn't        > v2.A4
defined, or that is deactivated, then that parameter does nothing.    > v2.A4

If any one of the parameters is invalid, then the entire command is   > v2.A4
considered a syntax error and none of the parameters are processed.   > v2.A4

If you turn on the cursor in a text window other than the current     > v2.A4
text window, then only the internal cursor status of that text window > v2.A4
is altered - it will not be turned on until you switch to that text   > v2.A4
window.  In this respect, only altering the current text window's     > v2.A4
cursor will actually make any immediate visible effect on the screen. > v2.A4


     Example:  $CON$
     Returns:  nothing


┌─────────────────────────────────────────┐
│ 5.6.4 ■ $CURSOR$ ... Text Cursor Status │
└─────────────────────────────────────────┘

Format:  $CURSOR(window)$
Syntax:  $CURSOR(opt:WINDOW)$                                         > v2.A4
                     ──────                                           > v2.A4
                     CUR                                              > v2.A4
                     0-35                                             > v2.A4
                     ──────                                           > v2.A4
                 def=CUR                                              > v2.A4

This Text Variable returns "YES" if the Text Cursor is enabled in the
specified text window, and "NO" if the Text Cursor is deactivated.    > v2.A4
If the specified text window doesn't exist, or is currently           > v2.A4
deactivated, then this command returns a value of "NO".               > v2.A4

If you do not specify a window parameter, then this command refers to > v2.A4
the current text window.  If you specify the window number parameter, > v2.A4
then you can specify a value from 0-35 to indicate a specific text    > v2.A4
window data table entry, or a value of "CUR" to indicate the current  > v2.A4
text window.                                                          > v2.A4

     Example:  $CURSOR$
     Returns:  YES


┌─────────────────────────────────────────────┐
│ 5.6.5 ■ $CURX$ ... Text Cursor X Coordinate │
└─────────────────────────────────────────────┘

Format:  $CURX(window)$
Syntax:  $CURX(opt:WINDOW)$                                           > v2.A4
                   ──────                                             > v2.A4
                   CUR                                                > v2.A4
                   0-35                                               > v2.A4
                   ──────                                             > v2.A4
               def=CUR                                                > v2.A4

This Text Variable returns the X coordinate of the text cursor in the
specified text window, relative to the upper left of the Text Window. > v2.A4
The location is "one based", so the first column of data is a value   > v2.A4
of "1", not "0".  Typical return values for valid cursor locations    > v2.A4
could easily range from 1-91.  If the specified text window is not    > v2.A4
defined, or is currently deactivated (via the $DTW$ command for       > v2.A4
example), then this text variable returns a value of "0" to indicate  > v2.A4
that the information isn't available.                                 > v2.A4

If you do not specify a window parameter, then this command refers to > v2.A1
the current text window.  If you specify the window number parameter, > v2.A4
then you can specify a value from 0-35 to indicate a specific text    > v2.A4
window data table entry, or a value of "CUR" to indicate the current  > v2.A4
text window.                                                          > v2.A4


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


┌─────────────────────────────────────────────┐
│ 5.6.6 ■ $CURY$ ... Text Cursor Y Coordinate │
└─────────────────────────────────────────────┘

Format:  $CURY(window)$
Syntax:  $CURY(opt:WINDOW)$                                           > v2.A4
                   ──────                                             > v2.A4
                   CUR                                                > v2.A4
                   0-35                                               > v2.A4
                   ──────                                             > v2.A4
               def=CUR                                                > v2.A4

This Text Variable returns the Y coordinate of the text cursor in the
specified text window, relative to the upper left of the Text Window. > v2.A4
The location is "one based", so the first column of data is a value   > v2.A4
of "1", not "0".  Typical return values for valid cursor locations    > v2.A4
could easily range from 1-43.  If the specified text window is not    > v2.A4
defined, or is currently deactivated (via the $DTW$ command for       > v2.A4
example), then this text variable returns a value of "0" to indicate  > v2.A4
that the information isn't available.                                 > v2.A4

If you do not specify a window parameter, then this command refers to > v2.A1
the current text window.  If you specify the window number parameter, > v2.A4
then you can specify a value from 0-35 to indicate a specific text    > v2.A4
window data table entry, or a value of "CUR" to indicate the current  > v2.A4
text window.                                                          > v2.A4

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


┌──────────────────────────────────────────┐
│ 5.6.7 ■ $DTW$ ... Deactivate Text Window │
└──────────────────────────────────────────┘

Format:  $DTW(window1,window2,...)$
Syntax:  $DTW(opt:WINDOW1, ...)$                                      > v2.A4
                  ───────                                             > v2.A4
                  ALL                                                 > v2.A4
                  CUR                                                 > v2.A4
                  0-35                                                > v2.A4
                  ───────                                             > v2.A4
              def=CUR                                                 > v2.A4

If no slot parameter is specified then the current text window is     > v2.A1
deactivated, preventing any received raw text from being displayed in > v2.A1
that window.  Switching to another text window data table entry can   > v2.A4
re-enable text displaying if that other window is "activated".        > v2.A4

You may specify one or more parameters to indicate that you wish to   > v2.A4
disable more than one text window in the same $DTW$ statement.  If    > v2.A4
any one of them fails to match the proper parameters, then the entire > v2.A4
command is considered a syntax error and none of the parameters are   > v2.A4
processed.                                                            > v2.A4


If a slot (0-35) is specified then that text window slot is           > v2.A4
deactivated.  This may or may not affect the current status of        > v2.A4
received text.  If the slot specified just happens to be the current  > v2.A4
slot then all received text is deactivated.  If the text window slot  > v2.A4
isn't the current text window then that text window is deactivated,   > v2.A4
but what is done with received raw text depends on the status of the  > v2.A4
current text window's status.                                         > v2.A1

You may specify "CUR" to explicitly deactivate the current text       > v2.A4
window.                                                               > v2.A4

You may also specify a slot of "ALL" to deactivate all defined text   > v2.A4
window slots.  Text window data table entries that are not defined,   > v2.A4
or that are protected are not affected by this operation.  This would > v2.A4
also deactivate any raw text that is received because the act of      > v2.A4
deactivating all windows will consequently deactivate the current one > v2.A4
too.                                                                  > v2.A4

If the text window being deactivated is protected, then it is not     > v2.A4
changed (ie, deactivated).                                            > v2.A4

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


┌─────────────────────────────────────┐
│ 5.6.8 ■ $ETW$ ... Erase Text Window │
└─────────────────────────────────────┘

Format:  $ETW(window1,window2,...)$
Syntax:  $ETW(opt:WINDOW1, ...)$                                      > v2.A4
                  ───────                                             > v2.A4
                  ALL                                                 > v2.A4
                  CUR                                                 > v2.A4
                  0-35                                                > v2.A4
                  ───────                                             > v2.A4
              def=CUR                                                 > v2.A4

If no parameter(s) are specified then the current text window in use  > v2.A4
is cleared.  If you specify a slot from 0-35 then the corresponding   > v2.A4
text window slot is erased.  You may also specify "ALL" to erase all  > v2.A4
currently defined text window slots.  Finally, you may specify the    > v2.A4
value of "CUR" to also indicate the current text window.              > v2.A4

It should be noted that the entire text window's bounding rectangle   > v2.A4
is erased, not just the display region inside the bounding rectangle. > v2.A4

You may specify one or more parameters to indicate that you wish to   > v2.A4
erase more than one text window in the same $ETW$ statement.  If      > v2.A4
any one of them fails to match the proper parameters, then the entire > v2.A4
command is considered a syntax error and none of the parameters are   > v2.A4
processed.                                                            > v2.A4

If any text window specified aren't defined, or if the viewport is    > v2.A4
deactivated, then this command does nothing for that viewport         > v2.A4
parameter.                                                            > v2.A4


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

     Example:  $ETW(ALL)$
     Returns:  nothing


┌────────────────────────────────────────────────────────────────┐
│ 5.6.9 ■ $ISEXTWIN$ ... Is text window an extended text window? │
└────────────────────────────────────────────────────────────────┘

Format:  $ISEXTWIN(windowno)$
Syntax:  $ISEXTWIN(opt:WINDOWNO)$                                     > v2.A4
                       ────────                                       > v2.A4
                       CUR                                            > v2.A4
                       0-35                                           > v2.A4
                       ────────                                       > v2.A4
                   def=CUR                                            > v2.A4

This text variable determines if the specified text window is an      > v2.A4
extended text window or not.  If the WINDOWNO parameter is omitted,   > v2.A4
then it will inquire about the current text window.  If WINDOWNO is   > v2.A4
specified, then it must be the value "CUR" for the current text       > v2.A4
window, or a window data table entry number from 0-35 to inquire      > v2.A4
about a specific text window data table entry.                        > v2.A4

If the specified text window is not defined, or deactivated, then     > v2.A4
this text variable returns a value of "-1".  If it is an extended     > v2.A4
text window, then a "1" is returned, otherwise a "0" is returned to   > v2.A4
indicate that it is a standard (non-extended) text window.            > v2.A4

     Example:  $ISEXTWIN(5)$                                          > v2.A4
     Returns:  1                                                      > v2.A4


┌──────────────────────────────────────────────────────┐
│ 5.6.10 ■ $MTW$ ... Maximize text window to full size │
└──────────────────────────────────────────────────────┘

Format:  $MTW(window1,window2,...)$
Syntax:  $MTW(opt:WINDOW1, ...)$                                      > v2.A4
                  ───────                                             > v2.A4
                  ALL                                                 > v2.A4
                  CUR                                                 > v2.A4
                  0-35                                                > v2.A4
                  ───────                                             > v2.A4
              def=CUR                                                 > v2.A4

This command maximizes a particular text window to full screen using  > v2.A1
whatever text window font is associated with that text window.  This  > v2.A1
does not affect any text that is already on the screen, only the      > v2.A1
internal definition of the text window (any scroll margins are        > v2.A1
reset).  The cursor is moved to the home position, but is not         > v2.A4
re-enabled if it was previously disabled (use $CON$ for this).  ANSI  > v2.A4
color attributes are not changed.  The possible settings for the      > v2.A1
WHICH parameter are:                                                  > v2.A1


            ALL ... Maximize all text windows at once                 > v2.A1
            CUR ... Maximize only the current text window             > v2.A1
         number ... Maximize a particular text window slot number     > v2.A1

You may specify one or more parameters to indicate that you wish to   > v2.A4
maximize more than one text window in the same $MTW$ statement.  If   > v2.A4
any one of them fails to match the proper parameters, then the entire > v2.A4
command is considered a syntax error and none of the parameters are   > v2.A4
processed.                                                            > v2.A4

It should be noted that if a text window being maximized is a         > v2.A4
standard text window created with the RIP_TEXT_WINDOW command, or if  > v2.A4
you just switched to a previously "unused" text window without        > v2.A4
explicitly defining it with a RIP_EXTENDED_TEXT_WINDOW command, then  > v2.A4
this command will treat the text window still as a "standard" text    > v2.A4
window.  The window is moved to the very upper-left corner of the     > v2.A4
display.  If it was an extended text window, then it is still moved   > v2.A4
to the upper-left corner of the screen, and the bounding box is made  > v2.A4
to exactly fit the actual text window display region.  Remember,      > v2.A4
extended text windows don't know anything about text coordinate base  > v2.A4
locations of the upper-left corner, but standard text windows do.     > v2.A4
This command maintains this nature of the text window being           > v2.A4
maximized.                                                            > v2.A4

If a text window being maximized is currently protected, this command > v2.A4
also does nothing to that text window.                                > v2.A4

     Example:  $MTW(ALL)$                                             > v2.A1
     Returns:  nothing                                                > v2.A1


┌────────────────────────────────────────────────────┐
│ 5.6.11 ■ $RTW$ ... Restore Text Window information │
└────────────────────────────────────────────────────┘

Format:  $RTW(source)$
Syntax:  $RTW(opt:SOURCE)$                                            > v2.A4
                  ──────                                              > v2.A4
                  BASE                                                > v2.A4
                  POP                                                 > v2.A4
                  0-9                                                 > v2.A4
                  ──────                                              > v2.A4
              def=BASE                                                > v2.A4

If no slot parameter is specified then this command restores all text > v2.A1
window definitions from the slot-less definition file saved with a    > v2.A1
$STW$ command (with no parameters).  The file is not deleted and you  > v2.A1
can restore many times.                                               > v2.A1

If you specify a slot parameter then that identifies which of the ten > v2.A1
different slots you wish to restore from (0-9).  Once the slot file   > v2.A1
is read it is deleted.                                                > v2.A1

If you specify a slot number of "POP" then you are performing a       > v2.A1
stack-based pop operation (eg, $RTW(POP)$).                           > v2.A1

If you specify "BASE" instead of a slot number than the text window   > v2.A4
table will be restored from the text window backup area's base save   > v2.A4
area.                                                                 > v2.A4


In any case, the text window settings active when a $STW$ (Save Text  > v2.A1
Window) was executed are saved.  The current cursor location, window  > v2.A1
location, ANSI attributes, cursor ON/OFF status, vertical scrolling   > v2.A1
margins, and the System Font are restored.                            > v2.A1

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

     Example:  $RTW(5)$
     Returns:  nothing


┌─────────────────────────────────────────────────┐
│ 5.6.12 ■ $STW$ ... Save Text Window information │
└─────────────────────────────────────────────────┘

Format:  $STW(destination)$
Syntax:  $STW(opt:DESTINATION)$                                       > v2.A4
                  ───────────                                         > v2.A4
                  BASE                                                > v2.A4
                  PUSH                                                > v2.A4
                  0-9                                                 > v2.A4
                  ───────────                                         > v2.A4
               def=BASE                                               > v2.A4

If no slot parameter is specified, then this command stores all       > v2.A1
currently defined text windows' settings base save area.  The         > v2.A4
windows' X/Y dimensions are preserved, as are the current cursor      > v2.A4
location, ANSI attributes, cursor ON/OFF status and the vertical      > v2.A4
scrolling margins.  Even the current System Fonts used for all        > v2.A4
windows are saved (if necessary).                                     > v2.A4

If you specify a slot parameter, then you are specifying to save the  > v2.A1
text window definitions to one of up to ten different slots (0-9).    > v2.A1
These allow you to have up to ten different text window               > v2.A1
configurations saved at the same time.  If you save to a slot then    > v2.A1
when you restore that slot the saved definitions are deleted from the > v2.A1
disk.  If you don't specify a slot parameter (a slot-less save) then  > v2.A1
you can restore that definition file multiple times without the file  > v2.A1
being deleted.                                                        > v2.A1

If you specify a slot number of "PUSH" then you are performing a      > v2.A1
stack-based save operation (eg, $STW(PUSH)$).                         > v2.A1

If you specify "BASE" instead of a slot number than the text window   > v2.A4
table will be stored into the text window backup area's base save     > v2.A4
area.                                                                 > v2.A4

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

     Example:  $STW(5)$
     Returns:  nothing



┌─────────────────────────────────────────────────────────┐
│ 5.6.13 ■ $TWERASEEOL$ ... Erase text window to line end │
└─────────────────────────────────────────────────────────┘

Format:  $TWERASEEOL(window1,window2
Syntax:  $TWERASEEOL(opt:WINDOW1, ...)$                               > v2.A4
                         ───────                                      > v2.A4
                         ALL                                          > v2.A4
                         CUR                                          > v2.A4
                         0-35                                         > v2.A4
                         ───────                                      > v2.A4
                     def=CUR                                          > v2.A4

This variable clears the current line in the specified text window    > v2.A4
from the cursor (inclusive) to the end of the line in the current     > v2.A4
ANSI color attributes.  If the you specify no parameters, then the    > v2.A4
current text window is used for the destination window.  If you do    > v2.A4
specify any parameters, they must be set to "CUR" for the current     > v2.A4
text window, "ALL" for all currently defined text windows, or 0-35 to > v2.A4
indicate a specific text window slot number.                          > v2.A4

You may specify one or more parameters to indicate that you wish to   > v2.A4
erase more than one text window's current lines in the same           > v2.A4
$TWERASEEOL$ statement.  If any one of them fails to match the proper > v2.A4
parameters, then the entire command is considered a syntax error and  > v2.A4
none of the parameters are processed.                                 > v2.A4

If the specified text window is deactivated or undefined then nothing > v2.A4
happens for that parameter.                                           > v2.A4

Unlike many other text window commands, this one can make an actual   > v2.A4
visual effect on the screen even if the specified text window isn't   > v2.A4
the current text window.                                              > v2.A4

     Example:  $TWERASEEOL(5)$                                        > v2.A1
     Returns:  nothing                                                > v2.A1


┌────────────────────────────────────────┐
│ 5.6.14 ■ $TWFONT$ ... Active Text Font │
└────────────────────────────────────────┘

Format:  $TWFONT(window)$
Syntax:  $TWFONT(opt:WINDOW)$                                         > v2.A4
                     ──────                                           > v2.A4
                     CUR                                              > v2.A4
                     0-35                                             > v2.A4
                     ──────                                           > v2.A4
                 def=CUR                                              > v2.A4

This Text Variable returns which of the five Text Window Fonts is
active, or 0 (zero) if specified text window is not defined, or is
deactivated.  The following values are returned:                      > v2.A4

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


Note that this command returns the actual text window font number     > v2.A4
plus one.  So to match the returned value to actual RIPscrip text     > v2.A4
window font numbers, subtract one from this result (providing that it > v2.A4
is greater than 0).                                                   > v2.A4

If you do not specify a window parameter, then this command refers to > v2.A1
the current text window.  If you do specify the window number         > v2.A4
parameter, then you may specify a value of 0-35 for a specific text   > v2.A4
window data table entry, or the value "CUR" to indicate the current   > v2.A4
text window (the default).                                            > v2.A4

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


┌─────────────────────────────────────────────────────────┐
│ 5.6.15 ■ $TWGOTO$ ... Move cursor to X,Y in text window
└─────────────────────────────────────────────────────────┘

Format:  $TWGOTO(winno,x_pos,y_pos)$
Syntax:  $TWGOTO(req:WINNO, opt:X_POS, opt:Y_POS)$                    > v2.A4
                     ─────      ─────      ─────                      > v2.A4
                     CUR        CUR        CUR                        > v2.A4
                     0-35       0-90       0-42                       > v2.A4
                                ─────      ─────                      > v2.A4
                            def=CUR    def=CUR                        > v2.A4

This variable allows you to move the cursor position in a given text  > v2.A1
window to a specified X/Y position.  If no parameters are given or no > v2.A1
X/Y parameters are given then nothing happens when this is executed.  > v2.A1

If the specified text window doesn't exist, or is deactivated, then   > v2.A4
this command does nothing.                                            > v2.A4

The WINNO parameter specifies a text window data table entry to move  > v2.A4
the cursor in.  Valid settings for WINNO are 0-35 for a specific text > v2.A4
window data table entry, or "CUR" to indicate the current text        > v2.A4
window.  If the specified window is not the current text window then  > v2.A4
the cursor in that window's definition is moved but no visible things > v2.A1
occur on the screen.  If the specified window is "CUR" or the window  > v2.A1
number happens to be the current text window, then the cursor that is > v2.A1
(potentially) on the screen is moved to the new location.             > v2.A1

The X/Y coordinates are text coordinates (1 based).  Specifying both  > v2.A1
coordinates allows you to place the cursor anywhere in the chosen     > v2.A1
window.  You may omit the Y parameter entirely to move the cursor     > v2.A1
horizontally only.  Either the X or Y parameter (or both) may be      > v2.A1
specified as "CUR" to indicate the the row or column is not to        > v2.A1
change.  In other words, if you wanted to move the cursor to line 2   > v2.A1
in the text window 5, but leave its column unchanged, you would       > v2.A1
use $TWGOTO(5,CUR,2)$.                                                > v2.A1

If the goto sequence would put the cursor outside the dimensions of   > v2.A1
the text window then the cursor is placed at the closest point to the > v2.A1
given location at the windows border.                                 > v2.A4

Text locations in this command are zero based (eg, the first column   > v2.A4
is specified as "0").  If the no X or Y parameters are specified,     > v2.A4
then this command does nothing because there is no X/Y information to > v2.A4
move to.                                                              > v2.A4


     Example:  $TWGOTO(CUR,10,2)$                                     > v2.A1
     Returns:  nothing                                                > v2.A1


┌───────────────────────────────────────┐
│ 5.6.16 ■ $TWH$ ... Text Window Height │
└───────────────────────────────────────┘

Format:  $TWH(window,type,domain)$
Syntax:  $TWH(opt:WINDOW, opt:TYPE, opt:DOMAIN)$                      > v2.A4
                  ──────      ────      ──────                        > v2.A4
                  CUR         BOUND     WORLD                         > v2.A4
                  0-35        CELL      DEVICE                        > v2.A4
                  ──────      TEXT      ROWS:TYPE=TEXT                > v2.A4
              def=CUR         ────      ──────                        > v2.A4
                          def=TEXT  def=ROWS:TYPE=TEXT                > v2.A4
                                        WORLD:TYPE<>TEXT              > v2.A4

If no parameters are specified, then this command returns the height  > v2.A4
of the current text window in text cells (lines).  You may specify a  > v2.A4
window number to indicate which text window you are inquiring about.  > v2.A4
The text window number parameters may be a value from 0-35 to         > v2.A4
reference a specific text window data table entry, or you may specify > v2.A4
a keyword of "CUR" to indicate the current text window.  If the       > v2.A4
specified text window doesn't exist, or is deactivated, then a value  > v2.A4
of "0" is returned.                                                   > v2.A4

If you specify any parameters then they must be in a specific order.  > v2.A4
The first (already discussed) is the text window number, and if it    > v2.A4
is omitted, then the current text window is assumed.  If you specify  > v2.A4
two parameters, then you must specify the window number parameter     > v2.A4
and the type parameter.  The type parameter determines what type of   > v2.A4
information you are inquiring about.  If you omit the type parameter  > v2.A4
then you are inquiring about the text window height itself, in actual > v2.A4
text window cell sizes (eg, the window might respond with "5" to      > v2.A4
indicate that it is 5 lines of text tall.                             > v2.A4

If you specify the type parameter, then you are directing this        > v2.A4
command to respond with information about a specific text window      > v2.A4
piece of information.  The available type parameters are:             > v2.A4

     Keyword   Description                                            > v2.A4
     ─────────────────────────────────────────────────────────────    > v2.A4
     BOUND     Return the height of the bounding box in pixels        > v2.A4
     TEXT      Return the height of the display region                > v2.A4
     CELL      Return the height of a text cell in the text window    > v2.A4

The third and final parameter is only of use if the BOUND or CELL     > v2.A4
parameter is used, and it determines the domain of the pixel size     > v2.A4
returned by the text variable.  The possible values of domain are:    > v2.A4

     Keyword   Description                                            > v2.A4
     ─────────────────────────────────────────────────────────────    > v2.A4
     WORLD     Return the value in world coordinates                  > v2.A4
     DEVICE    Return the value in raw device pixel coordinates       > v2.A4
     ROWS      Return height of area in text lines (valid only for    > v2.A4
               a type of "TEXT".                                      > v2.A4



If the domain parameter is omitted, then it automatically defaults    > v2.A4
to WORLD (except for the TEXT type, which defaults to the height of   > v2.A4
the text window in lines of text).  When a world coordinate value is  > v2.A4
returned, the actual "raw" dimensions are converted to the current    > v2.A4
environment's world coordinate system then returned to the host.  If  > v2.A4
the domain is set to "DEVICE" then the value is returned in raw,      > v2.A4
device-level pixel coordinates.                                       > v2.A4

The BOUND parameter refers to the text window's bounding rectangle.   > v2.A4
It is the absolute exterior that the text window may extend to.  It   > v2.A4
can also be thought of as a margin outside the actual text window     > v2.A4
where nothing can be displayed from the text window.  See the         > v2.A4
RIP_EXTENDED_TEXT_WINDOW for more details about this bounding         > v2.A4
rectangle.                                                            > v2.A4

The CELL parameter indicates that you are inquiring about the height  > v2.A4
of a character cell used in the text window.  The height of a cell    > v2.A4
is based on the font number and resolution currently in use on the    > v2.A4
actual destination RIPscrip software package.  Under 640x350, this    > v2.A4
was typically 8x8 for font #0 (ie, in RIPscrip 1.54).  This may be    > v2.A4
different now at varying resolutions.  So, if you are running at a    > v2.A4
resolution of 640x350 and you inquire about a text window's cell      > v2.A4
height for a text window using font #0, then it most likely will      > v2.A4
return a result of 8 pixels (in device coordinates).  The actual      > v2.A4
value in world coordinates could vary well be different based on the  > v2.A4
size of the world coordinate resolution frame.                        > v2.A4

The "TEXT" type indicates that you are requesting information about   > v2.A4
the text window sub-section of the text window definition.  If the    > v2.A4
domain parameter is specified, then you are requesting the actual     > v2.A4
height of the text window display area in "lines of text".  This can  > v2.A4
also be retrieved if the domain parameter is "ROWS".  This            > v2.A4
particular domain parameter known as "ROWS" is only valid for a       > v2.A4
type parameter of "TEXT".  Using it in any other context is           > v2.A4
considered a syntax error.  If the domain parameter is specified, and > v2.A4
it is set to "WORLD", then the pixel height of the display region is  > v2.A4
being requested in world coordinates.  If domain is set to DEVICE,    > v2.A4
then you are requesting the height of the display region in actual    > v2.A4
hardware pixel coordinates.                                           > v2.A4

It should be noted that the bounding box of a text window can be      > v2.A4
obtained regardless of whether it is an old-style 1.54 text window    > v2.A4
created with RIP_TEXT_WINDOW or a new "resolution independent" text   > v2.A4
window defined via the RIP_EXTENDED_TEXT_WINDOW command.  This can    > v2.A4
be because under the older text window concept, the bounding box      > v2.A4
is exactly as large as the text window itself, while under the        > v2.A4
extended text window, the text window will typically be inside the    > v2.A4
bounding rectangle.                                                   > v2.A4

If you completely omit the type parameter, then you must omit the     > v2.A4
domain parameter.  In this case, you are asking for the height of the > v2.A4
text window in "lines of text", not in pixels.                        > v2.A4

     Example:  $TWH$ ................... Height of current text       > v2.A4
                                         window in lines of text.     > v2.A4
     Returns:  5                                                      > v2.A4



     Example: $TWH(CUR)$ ............... Height of current text       > v2.A4
                                         window in lines of text.     > v2.A4
     Returns:  5                                                      > v2.A4


     Example:  $TWH(5,BOUND)$ .......... Height of text window 5's    > v2.A4
                                         bounding box in world        > v2.A4
                                         coordinates.                 > v2.A4
     Returns:  800                                                    > v2.A4


     Example:  $TWH(5,BOUND,DEVICE)$ ... Height of text window 5's    > v2.A4
                                         bounding box in device       > v2.A4
                                         pixel coordinates            > v2.A4
     Returns:  400                                                    > v2.A4


     Example:  $TWH(CUR,CELL) .......... Height of current text       > v2.A4
                                         window's character cell      > v2.A4
                                         in world coordinates.        > v2.A4
     Returns:  16                                                     > v2.A4


     Example:  $TWH(5,CELL,DEVICE)$ .... Height of text window 5's    > v2.A4
                                         character cell in device     > v2.A4
                                         pixel coordinates.           > v2.A4


┌───────────────────────────────────────────────────────────────────┐
│ 5.6.17 ■ $TWHOME$ ... Move cursor to home position in text window │
└───────────────────────────────────────────────────────────────────┘

Format:  $TWHOME(winno)$
Syntax:  $TWHOME(opt:WINNO)$                                          > v2.A4
                     ─────                                            > v2.A4
                     CUR                                              > v2.A4
                     0-35                                             > v2.A4
                     ─────                                            > v2.A4
                 def=CUR                                              > v2.A4

This command moves the cursor in the specified text window data table > v2.A4
entry to the upper-left corner of the window.  WINNO may be any value > v2.A4
from 0-35 to indicate the desired data table entry, or the value      > v2.A4
"CUR" to indicate the current text window.  If the WINNO slot number  > v2.A4
happens to correspond to the current text window or the WINNO         > v2.A1
parameter is specified as "CUR" then the cursor that is on the        > v2.A1
screen (potentially) will be visibly moved.  If the WINNO parameter   > v2.A1
specifies a window that is not the current text window then the       > v2.A1
cursor position definition for that non-current window is altered     > v2.A1
only - no visible thing would happen on the screen.                   > v2.A1

If the specified window is deactivated or is undefined then nothing   > v2.A1
happens.                                                              > v2.A1

If the WINNO parameter is omitted then the current text window is     > v2.A1
assumed.                                                              > v2.A1

     Example:  $TWHOME(5)$                                            > v2.A1
     Returns:  nothing                                                > v2.A1


┌────────────────────────────────────────┐
│ 5.6.18 ■ $TWIN$ ... Text Window Status │
└────────────────────────────────────────┘

Format:  $TWIN(window)$
Syntax:  $TWIN(opt:WINDOW)$                                           > v2.A4
                   ──────                                             > v2.A4
                   CUR                                                > v2.A4
                   0-35                                               > v2.A4
                   ──────                                             > v2.A4
               def=CUR                                                > v2.A4

This Text Variable checks to see if the specified Text Window is
activated, and returns "YES" if the specified text window is          > v2.A4
activated or returns "NO" if it is deactivated (eg, with the $DTW$    > v2.A4
command for example).  If the specified text window isn't defined,    > v2.A4
then this command returns a value of "NO".                            > v2.A4

If you do not specify a window parameter, then this command refers to > v2.A1
the current text window.  If you do specify a window parameter then   > v2.A1
it can be a value from 0-35 to indicate a specific text window data   > v2.A4
table entry, or the value "CUR" to indicate the current text window.  > v2.A4

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


┌──────────────────────────────────────┐
│ 5.6.19 ■ $TWW$ ... Text Window Width │
└──────────────────────────────────────┘

Format:  $TWW(window,type,domain)$
Syntax:  $TWW(opt:WINDOW, opt:TYPE, opt:DOMAIN)$                      > v2.A4
                  ──────      ────      ──────                        > v2.A4
                  CUR         BOUND     WORLD                         > v2.A4
                  0-35        CELL      DEVICE                        > v2.A4
                  ──────      TEXT      COLS:TYPE=TEXT                > v2.A4
              def=CUR         ────      ──────                        > v2.A4
                          def=TEXT  def=COLS:TYPE=TEXT                > v2.A4
                                        WORLD:TYPE<>TEXT              > v2.A4

If no parameters are specified, then this command returns the width   > v2.A4
of the current text window in text cells (columns).  You may specify  > v2.A4
a window number to indicate which text window you are inquiring       > v2.A4
about.  The text window number parameters may be a value from 0-35 to > v2.A4
reference a specific text window data table entry, or you may specify > v2.A4
a keyword of "CUR" to indicate the current text window.  If the       > v2.A4
specified text window doesn't exist, or is deactivated, then a value  > v2.A4
of "0" is returned.                                                   > v2.A4

If you specify any parameters then they must be in a specific order.  > v2.A4
The first (already discussed) is the text window number, and if it    > v2.A4
is omitted, then the current text window is assumed.  If you specify  > v2.A4
two parameters, then you must specify the window number parameter     > v2.A4
and the type parameter.  The type parameter determines what type of   > v2.A4
information you are inquiring about.  If you omit the type parameter  > v2.A4
then you are inquiring about the text window width itself, in actual  > v2.A4
text window cell sizes (eg, the window might respond with "5" to      > v2.A4
indicate that it is 5 columns wide.                                   > v2.A4


If you specify the type parameter, then you are directing this        > v2.A4
command to respond with information about a specific text window      > v2.A4
piece of information.  The available type parameters are:             > v2.A4

     Keyword   Description                                            > v2.A4
     ─────────────────────────────────────────────────────────────    > v2.A4
     BOUND     Return the width of the bounding box in pixels         > v2.A4
     TEXT      Return the width of the display region                 > v2.A4
     CELL      Return the width of a text cell in the text window     > v2.A4

The third and final parameter is only of use if the BOUND or CELL     > v2.A4
parameter is used, and it determines the domain of the pixel size     > v2.A4
returned by the text variable.  The possible values of domain are:    > v2.A4

     Keyword   Description                                            > v2.A4
     ─────────────────────────────────────────────────────────────    > v2.A4
     WORLD     Return the value in world coordinates                  > v2.A4
     DEVICE    Return the value in raw device pixel coordinates       > v2.A4
     COLS      Return width of area in text columns (valid only for   > v2.A4
               a type of "TEXT".                                      > v2.A4

If the domain parameter is omitted, then it automatically defaults    > v2.A4
to WORLD (except for the TEXT type, which defaults to the height of   > v2.A4
the text window in lines of text).  When a world coordinate value is  > v2.A4
returned, the actual "raw" dimensions are converted to the current    > v2.A4
environment's world coordinate system then returned to the host.  If  > v2.A4
the domain is set to "DEVICE" then the value is returned in raw,      > v2.A4
device-level pixel coordinates.                                       > v2.A4

If the domain parameter is omitted, then it automatically defaults    > v2.A4
to WORLD (except for the TEXT type, which defaults to the width of    > v2.A4
the text window in columns of text).  When a world coordinate value   > v2.A4
is returned, the actual "raw" dimensions are converted to the current > v2.A4
environment's world coordinate system then returned to the host.  If  > v2.A4
the domain is set to "DEVICE" then the value is returned in raw,      > v2.A4
device-level pixel coordinates.                                       > v2.A4

The BOUND parameter refers to the text window's bounding rectangle.   > v2.A4
It is the absolute exterior that the text window may extend to.  It   > v2.A4
can also be thought of as a margin outside the actual text window     > v2.A4
where nothing can be displayed from the text window.  See the         > v2.A4
RIP_EXTENDED_TEXT_WINDOW for more details about this bounding         > v2.A4
rectangle.                                                            > v2.A4

The CELL parameter indicates that you are inquiring about the width   > v2.A4
of a character cell used in the text window.  The width of a cell     > v2.A4
is based on the font number and resolution currently in use on the    > v2.A4
actual destination RIPscrip software package.  Under 640x350, this    > v2.A4
was typically 8x8 for font #0 (ie, in RIPscrip 1.54).  This may be    > v2.A4
different now at varying resolutions.  So, if you are running at a    > v2.A4
resolution of 640x350 and you inquire about a text window's cell      > v2.A4
width for a text window using font #0, then it most likely will       > v2.A4
return a result of 8 pixels (in device coordinates).  The actual      > v2.A4
value in world coordinates could vary well be different based on the  > v2.A4
size of the world coordinate resolution frame.                        > v2.A4

The "TEXT" type indicates that you are requesting information about   > v2.A4
the text window sub-section of the text window definition.  If the    > v2.A4
domain parameter is specified, then you are requesting the actual     > v2.A4
width of the text window display area in "columns of text".  This can > v2.A4
also be retrieved if the domain parameter is "COLS".  This            > v2.A4


particular domain parameter known as "COLS" is only valid for a       > v2.A4
type parameter of "TEXT".  Using it in any other context is           > v2.A4
considered a syntax error.  If the domain parameter is specified, and > v2.A4
it is set to "WORLD", then the pixel width of the display region is   > v2.A4
being requested in world coordinates.  If domain is set to DEVICE,    > v2.A4
then you are requesting the width of the display region in actual     > v2.A4
hardware pixel coordinates.                                           > v2.A4

It should be noted that the bounding box of a text window can be      > v2.A4
obtained regardless of whether it is an old-style 1.54 text window    > v2.A4
created with RIP_TEXT_WINDOW or a new "resolution independent" text   > v2.A4
window defined via the RIP_EXTENDED_TEXT_WINDOW command.  This can    > v2.A4
be because under the older text window concept, the bounding box      > v2.A4
is exactly as large as the text window itself, while under the        > v2.A4
extended text window, the text window will typically be inside the    > v2.A4
bounding rectangle.                                                   > v2.A4

If you completely omit the type parameter, then you must omit the     > v2.A4
domain parameter.  In this case, you are asking for the width of the  > v2.A4
text window in "text columns", not in pixels.                         > v2.A4

     Example:  $TWW$ ................... Width of current text        > v2.A4
                                         window in columns of text.   > v2.A4
     Returns:  5                                                      > v2.A4


     Example: $TWW(CUR)$ ............... Width of current text        > v2.A4
                                         window in columns of text.   > v2.A4
     Returns:  5                                                      > v2.A4


     Example:  $TWW(5,BOUND)$ .......... Width of text window 5's     > v2.A4
                                         bounding box in world        > v2.A4
                                         coordinates.                 > v2.A4
     Returns:  800                                                    > v2.A4


     Example:  $TWW(5,BOUND,DEVICE)$ ... Width of text window 5's     > v2.A4
                                         bounding box in device       > v2.A4
                                         pixel coordinates            > v2.A4
     Returns:  400                                                    > v2.A4


     Example:  $TWW(CUR,CELL) .......... Width of current text        > v2.A4
                                         window's character cell      > v2.A4
                                         in world coordinates.        > v2.A4
     Returns:  16                                                     > v2.A4


     Example:  $TWW(5,CELL,DEVICE)$ .... Width of text window 5's     > v2.A4
                                         character cell in device     > v2.A4
                                         pixel coordinates.           > v2.A4



┌───────────────────────────────────────────────────────┐
│ 5.6.20 ■ $TWX0$ ... Text Win Upper Left X Coordinates │
└───────────────────────────────────────────────────────┘

Format:  $TWX0(window,type,domain)$
Syntax:  $TWX0(opt:WINDOW, opt:TYPE, opt:DOMAIN)$                     > v2.A4
                   ──────      ────      ──────                       > v2.A4
                   CUR         BOUND     WORLD                        > v2.A4
                   0-35        TEXT      DEVICE                       > v2.A4
                   ──────      ────      ──────                       > v2.A4
               def=CUR     def=TEXT  def=WORLD                        > v2.A4

This variable returns upper-left X coordinate information about a     > v2.A4
text window.  The exact type and nature of the returned information   > v2.A4
is determined by the parameters provided (if any).  Without any       > v2.A4
parameters, this command returns the upper-left X coordinate of the   > v2.A4
text window in text coordinates (see below for a more detailed        > v2.A4
explanation).                                                         > v2.A4

If the first parameter is provided, then it indicates which text      > v2.A4
window you requesting information on.  It may be set to a numeric     > v2.A4
value from 0-35 to indicate a specific text window data table entry,  > v2.A4
or it may be "CUR" to indicate the current text window.               > v2.A4

If the specified text window doesn't exist, or is deactivated, then   > v2.A4
this command returns a value of "-1" to indicate failure.             > v2.A4

     NOTE:  Under 1.54, this text variable used to return "0" to      > v2.A4
            indicate that a text window was deactivated.  This was    > v2.A4
            inaccurately documented in previous RIPscrip releases     > v2.A4
            because "0" could be a valid upper-left X coordinate.     > v2.A4

If the second parameter, type, is provided, then the window number    > v2.A4
parameter must be present.  The type parameter defines what type of   > v2.A4
information you are requesting about the text window.  The avaiable   > v2.A4
keyword values for the type parameter are as follows:                 > v2.A4

     Keyword   Description                                            > v2.A4
     ───────────────────────────────────────────────────────────      > v2.A4
     BOUND     Upper left X coordinate of the bounding rectangle      > v2.A4
     TEXT      Upper left X coordinate of text window display         > v2.A4
               rectangle                                              > v2.A4

The BOUND parameter indicates that you are inquiring about the text   > v2.A4
window's bounding rectangle's upper left X coordinate.  The result    > v2.A4
is returned in either world coordinates or in physical device         > v2.A4
coordinates based on the domain parameter (see below).                > v2.A4

The TEXT parameter indicates that you are inquiring about the actual  > v2.A4
text window's display area somewhere inside the bounding rectangle.   > v2.A4
The information returned is the upper-left X graphical coordinate of  > v2.A4
the text window display rectangle.  It is returned either in world    > v2.A4
coordinates or in device pixel coordinates based on the domain        > v2.A4
parameter (see below).                                                > v2.A4

The third parameter is only valid if the type parameter is provided.  > v2.A4
It indicates the domain under which the type parameter data is        > v2.A4
returned to the host.  The possible values for domain are:            > v2.A4



     Keyword   Description                                            > v2.A4
     ───────────────────────────────────────────────────────────      > v2.A4
     WORLD     Return information in current world coordinates        > v2.A4
     DEVICE    Return information in physical device coordinates      > v2.A4

The domain parameter determines what type of numbers are returned     > v2.A4
for the bounding box or the text window display rectangle.  If this   > v2.A4
parameter is omitted, then the coordinates are returned in world      > v2.A4
coordinates.  If the parameter is specified, then the result is in    > v2.A4
either world or device coordinates depending on the value of the      > v2.A4
parameter.                                                            > v2.A4

If no type parameter is specified (as previously described), then     > v2.A4
the text window's upper-left X coordinate is returned in text         > v2.A4
coordinates.  This is to maintain backward compability with older     > v2.A4
RIPscrip v1.54 related commands.  In fact, this is not the best way   > v2.A4
of determining where the text window is on the screen - graphical     > v2.A4
coordinates are a much better method.  If a text window is defined    > v2.A4
with the RIP_TEXT_WINDOW command where you specify the location of    > v2.A4
the text window solely on the basis of text coordinate X/Y data,      > v2.A4
then this form of this command will return a number indicating        > v2.A4
which X character cell the text window starts at.  If the text window > v2.A4
is defined using the RIP_EXTENDED_TEXT_WINDOW command, where the      > v2.A4
upper-left corner of the text window might not start on an even       > v2.A4
multiple of the window's cell size, then this command returns a       > v2.A4
value of "-1" to indicate that the desired request cannot be          > v2.A4
processed because the text window isn't the right kind of text        > v2.A4
window.  In this manner, the value "-1" is used to indicate that an   > v2.A4
error has occurred with this command.                                 > v2.A4

     Example:  $TWX0$ ..................... Upper left X coordinate   > v2.A4
                                            of the current text       > v2.A4
                                            window in text            > v2.A4
                                            coordinates               > v2.A4
     Returns:  5                                                      > v2.A4


     Example:  $TWX0(CUR)$ ................ Upper left X coordinate   > v2.A4
                                            of the current text       > v2.A4
                                            window in text            > v2.A4
                                            coordinates               > v2.A4
     Returns:  5                                                      > v2.A4


     Example:  $TWX0(CUR,BOUND)$ .......... Upper left X coordinate   > v2.A4
                                            of the current text       > v2.A4
                                            window's bounding box in  > v2.A4
                                            world coordinates.        > v2.A4
     Returns:  100                                                    > v2.A4


     Example:  $TWX0(CUR,BOUND,WORLD)$ .... Upper left X coordinate   > v2.A4
                                            of the current text       > v2.A4
                                            window's bounding box in  > v2.A4
                                            world coordinates.        > v2.A4
     Returns:  100                                                    > v2.A4



     Example:  $TWX0(CUR,BOUND,DEVICE)$ ... Upper left X coordinate   > v2.A4
                                            of the current text       > v2.A4
                                            window's bounding box in  > v2.A4
                                            device pixel coordinates. > v2.A4
     Returns:  50                                                     > v2.A4


     Example:  $TWX0(CUR,TEXT,DEVICE)$ .... Upper left X coordinate   > v2.A4
                                            of the text window's      > v2.A4
                                            display box in device     > v2.A4
                                            pixel coordinates.        > v2.A4
     Returns:  55                                                     > v2.A4


┌───────────────────────────────────────────────────────┐
│ 5.6.21 ■ $TWX1$ ... Text Win Lower Right X Coordinate │
└───────────────────────────────────────────────────────┘

Format:  $TWX1(window,type,domain)$
Syntax:  $TWX1(opt:WINDOW, opt:TYPE, opt:DOMAIN)$                     > v2.A4
                   ──────      ────      ──────                       > v2.A4
                   CUR         BOUND     WORLD                        > v2.A4
                   0-35        TEXT      DEVICE                       > v2.A4
                   ──────      ────      COLS                         > v2.A4
               def=CUR     def=TEXT      ──────                       > v2.A4
                                     def=COLS:TYPE=TEXT               > v2.A4
                                         WORLD:TYPE<>TEXT             > v2.A4

This variable returns lower-right X coordinate information about a    > v2.A4
text window.  The exact type and nature of the returned information   > v2.A4
is determined by the parameters provided (if any).  Without any       > v2.A4
parameters, this command returns the lower-right X coordinate of the  > v2.A4
text window in text coordinates (see below for a more detailed        > v2.A4
explanation).                                                         > v2.A4

If the first parameter is provided, then it indicates which text      > v2.A4
window you requesting information on.  It may be set to a numeric     > v2.A4
value from 0-35 to indicate a specific text window data table entry,  > v2.A4
or it may be "CUR" to indicate the current text window.               > v2.A4

If the specified text window doesn't exist, or is deactivated, then   > v2.A4
this command returns a value of "-1" to indicate failure.             > v2.A4

     NOTE:  Under 1.54, this text variable used to return "0" to      > v2.A4
            indicate that a text window was deactivated.  This was    > v2.A4
            inaccurately documented in previous RIPscrip releases     > v2.A4
            because "0" could be a valid lower-right X coordinate.    > v2.A4

If the second parameter, type, is provided, then the window number    > v2.A4
parameter must be present.  The type parameter defines what type of   > v2.A4
information you are requesting about the text window.  The avaiable   > v2.A4
keyword values for the type parameter are as follows:                 > v2.A4

     Keyword   Description                                            > v2.A4
     ───────────────────────────────────────────────────────────      > v2.A4
     BOUND     Lower right X coordinate of the bounding rectangle     > v2.A4
     TEXT      Lower right X coordinate of text window display        > v2.A4
               rectangle                                              > v2.A4


The BOUND parameter indicates that you are inquiring about the text   > v2.A4
window's bounding rectangle's lower right X coordinate.  The result   > v2.A4
is returned in either world coordinates or in physical device         > v2.A4
coordinates based on the domain parameter (see below).                > v2.A4

The TEXT parameter indicates that you are inquiring about the actual  > v2.A4
text window's display area somewhere inside the bounding rectangle.   > v2.A4
The information returned is the lower-right X graphical coordinate of > v2.A4
the text window display rectangle.  It is returned either in world    > v2.A4
coordinates or in device pixel coordinates based on the domain        > v2.A4
parameter (see below).                                                > v2.A4

The third parameter is only valid if the type parameter is provided.  > v2.A4
It indicates the domain under which the type parameter data is        > v2.A4
returned to the host.  The possible values for domain are:            > v2.A4

     Keyword   Description                                            > v2.A4
     ───────────────────────────────────────────────────────────      > v2.A4
     WORLD     Return information in current world coordinates        > v2.A4
     DEVICE    Return information in physical device coordinates      > v2.A4

The domain parameter determines what type of numbers are returned     > v2.A4
for the bounding box or the text window display rectangle.  If this   > v2.A4
parameter is omitted, then the coordinates are returned in world      > v2.A4
coordinates.  If the parameter is specified, then the result is in    > v2.A4
either world or device coordinates depending on the value of the      > v2.A4
parameter.                                                            > v2.A4

If no type parameter is specified (as previously described), then     > v2.A4
the text window's lower-right X coordinate is returned in text        > v2.A4
coordinates.  This is to maintain backward compability with older     > v2.A4
RIPscrip v1.54 related commands.  In fact, this is not the best way   > v2.A4
of determining where the text window is on the screen - graphical     > v2.A4
coordinates are a much better method.  If a text window is defined    > v2.A4
with the RIP_TEXT_WINDOW command where you specify the location of    > v2.A4
the text window solely on the basis of text coordinate X/Y data,      > v2.A4
then this form of this command will return a number indicating        > v2.A4
which X character cell the text window starts at.  If the text window > v2.A4
is defined using the RIP_EXTENDED_TEXT_WINDOW command, where the      > v2.A4

lower-right corner of the text window might not start on an even      > v2.A4
multiple of the window's cell size, then this command returns a       > v2.A4
value of "-1" to indicate that the desired request cannot be          > v2.A4
processed because the text window isn't the right kind of text        > v2.A4
window.  In this manner, the value "-1" is used to indicate that an   > v2.A4
error has occurred with this command.                                 > v2.A4

When graphical coordinate information is returned on the lower right  > v2.A4
X location, it is returned based on the resolution independent nature > v2.A4
of rectangles in RIPscrip.  This means that if the very last most     > v2.A4
device pixel of text window data is at X coordinate 299, then this    > v2.A4
command would return a value of 300 for the lower right X coordinate  > v2.A4
value.  See the section on the THE MATHEMATICS OF GRAPHICS AND        > v2.A4
COORDINATES" for more details about why we use this coordinate        > v2.A4
convention.                                                           > v2.A4

     Example:  $TWX1$ ..................... Lower right X coordinate  > v2.A4
                                            of the current text       > v2.A4
                                            window in text            > v2.A4
                                            coordinates               > v2.A4
     Returns:  5                                                      > v2.A4


     Example:  $TWX1(CUR)$ ................ Lower right X coordinate  > v2.A4
                                            of the current text       > v2.A4
                                            window in text            > v2.A4
                                            coordinates               > v2.A4
     Returns:  5                                                      > v2.A4


     Example:  $TWX1(CUR,BOUND)$ .......... Lower right X coordinate  > v2.A4
                                            of the current text       > v2.A4
                                            window's bounding box in  > v2.A4
                                            world coordinates.        > v2.A4
     Returns:  100                                                    > v2.A4


     Example:  $TWX1(CUR,BOUND,WORLD)$ .... Lower right X coordinate  > v2.A4
                                            of the current text       > v2.A4
                                            window's bounding box in  > v2.A4
                                            world coordinates.        > v2.A4
     Returns:  100                                                    > v2.A4


     Example:  $TWX1(CUR,BOUND,DEVICE)$ ... Lower right X coordinate  > v2.A4
                                            of the current text       > v2.A4
                                            window's bounding box in  > v2.A4
                                            device pixel coordinates. > v2.A4
     Returns:  50                                                     > v2.A4


     Example:  $TWX1(CUR,TEXT,DEVICE)$ .... Lower right X coordinate  > v2.A4
                                            of the text window's      > v2.A4
                                            display box in device     > v2.A4
                                            pixel coordinates.        > v2.A4
     Returns:  55                                                     > v2.A4


┌──────────────────────────────────────────────────────┐
│ 5.6.22 ■ $TWY0$ ... Text Win Upper Left Y Coordinate │
└──────────────────────────────────────────────────────┘

Format:  $TWY0(window,type,domain)$
Syntax:  $TWY0(opt:WINDOW, opt:TYPE, opt:DOMAIN)$                     > v2.A4
                   ──────      ────      ──────                       > v2.A4
                   CUR         BOUND     WORLD                        > v2.A4
                   0-35        TEXT      DEVICE                       > v2.A4
                   ──────      ────      ──────                       > v2.A4
               def=CUR     def=TEXT  def=WORLD                        > v2.A4

This command is identical in every way to the $TWX0$ text variable    > v2.A4
except that it returns information on the upper-left Y coordinate     > v2.A4
of the text window.  The exact same parameters apply as in the $TWX0$ > v2.A4
text variable (see that command for more details).                    > v2.A4



┌───────────────────────────────────────────────────────┐
│ 5.6.23 ■ $TWY1$ ... Text Win Lower Right Y Coordinate │
└───────────────────────────────────────────────────────┘

Format:  $TWY1(window,type,domain)$
Syntax:  $TWY1(opt:WINDOW, opt:TYPE, opt:DOMAIN)$                     > v2.A4
                   ──────      ────      ──────                       > v2.A4
                   CUR         BOUND     WORLD                        > v2.A4
                   0-35        TEXT      DEVICE                       > v2.A4
                   ──────      ────      ──────                       > v2.A4
               def=CUR     def=TEXT  def=WORLD                        > v2.A4

This command is identical in every way to the $TWX1$ text variable    > v2.A4
except that it returns information on the lower-right Y coordinate    > v2.A4
of the text window.  The exact same parameters apply as in the $TWX1$ > v2.A4
text variable, as do conventions for coordinates (see that command    > v2.A4
for more details).                                                    > v2.A4



╔════════════════════════════════════════════╗
║ 5.7 ■ PORT/VIEWPORT RELATED TEXT VARIABLES ║
╚════════════════════════════════════════════╝

These text variables return information on, or manipulate ports or    > v2.A4
viewports.                                                            > v2.A4


┌───────────────────────────────────────────────────┐
│ 5.7.1 ■ $AVP$ ... Activates a viewport definition │
└───────────────────────────────────────────────────┘

Format:  $AVP(port1,port2,...)$
Syntax:  $AVP(opt:PORT1, ...)$                                        > v2.A4
                  ─────                                               > v2.A4
                  ALL                                                 > v2.A4
                  CUR                                                 > v2.A4
                  0-35                                                > v2.A4
                  ─────                                               > v2.A4
              def=CUR                                                 > v2.A4

This command does the exact opposite of the $DVP$ text variable which > v2.A1
deactivates a viewport.  When a viewport is activated, it no longer   > v2.A1
discards graphical commands that are sent to it.  This does not make  > v2.A1
any visual changes on the screen immediately - they only affect       > v2.A1
subsequent graphical RIPscrip operations that are received when that  > v2.A1
viewport is selected as the current viewport.  You may activate more  > v2.A1
then one viewport by specifying multiple viewport slot numbers.       > v2.A1

You may specify one or more parameters to indicate that you wish to   > v2.A4
activate more than one viewport in the same $AVP$ statement.  If      > v2.A4
any one of them fails to match the proper parameters, then the entire > v2.A4
command is considered a syntax error and none of the parameters are   > v2.A4
processed.                                                            > v2.A4

If the port you are trying to activate is protected, then it is not   > v2.A4
changed (ie, activated).                                              > v2.A4

You may activate more then one viewport by specifying multiple        > v2.A4
viewport slot numbers (0-35).  You may also specify the following:    > v2.A4

            ALL ... Activate all viewports at once                    > v2.A4
            CUR ... Activate only the current viewport                > v2.A4

     Example:  $AVP(CUR)$                                             > v2.A1
     Returns:  nothing                                                > v2.A1



┌────────────────────────────────────────────────────┐
│ 5.7.2 ■ $DVP$ ... Deactivate a viewport definition │
└────────────────────────────────────────────────────┘

Format:  $DVP(port1,port2,...)$
Syntax:  $DVP(opt:PORT1, ...)$                                        > v2.A4
                  ─────                                               > v2.A4
                  ALL                                                 > v2.A4
                  CUR                                                 > v2.A4
                  0-35                                                > v2.A4
                  ─────                                               > v2.A4
              def=CUR                                                 > v2.A4

This command deactivates  a viewport, making no more RIPscrip         > v2.A4
graphics commands displayable in that viewport.  When a viewport is   > v2.A4
deactivated, it no longer accepts graphical commands that are sent to > v2.A4
it.  This does not make any visual changes on the screen immediately; > v2.A4
they only affect subsequent graphical RIPscrip operations that are    > v2.A4
received when that viewport is selected as the current viewport.  You > v2.A4
may deactivate more then one viewport by specifying multiple viewport > v2.A4
slot numbers.                                                         > v2.A4

You may specify one or more parameters to indicate that you wish to   > v2.A4
deactivate more than one viewport in the same $DVP$ statement.  If    > v2.A4
any one of them fails to match the proper parameters, then the entire > v2.A4
command is considered a syntax error and none of the parameters are   > v2.A4
processed.                                                            > v2.A4

If the port you are trying to deactivate is protected, then it is not > v2.A4
changed (ie, deactivated).                                            > v2.A4

You may deactivate more then one viewport by specifying multiple      > v2.A4
viewport slot numbers (0-35).  You may also specify the following:    > v2.A4

            ALL ... Deactivate all viewports at once                  > v2.A4
            CUR ... Deactivate only the current viewport              > v2.A4

     Example:  $DVP(CUR)$                                             > v2.A4
     Returns:  nothing                                                > v2.A4


┌───────────────────────────────────────────┐
│ 5.7.3 ■ $EGW$ ... Erase Graphics viewport │
└───────────────────────────────────────────┘

Format:  $EGW(port1,port2,...)$
Syntax:  $EGW(opt:PORTNO, ...)$                                       > v2.A4
                  ──────                                              > v2.A4
                  ALL                                                 > v2.A4
                  CUR                                                 > v2.A4
                  0-35                                                > v2.A4
                  ──────                                              > v2.A4
              def=CUR                                                 > v2.A4

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


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

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

If any viewports specified belong to a port that isn't defined, or    > v2.A4
if the viewport is deactivated, then this command does nothing for    > v2.A4
that viewport parameter.                                              > v2.A4

You can specify mulitple viewport/port slots to erase to erase more   > v2.A4
than one withine one command if you wish.                             > v2.A4

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


┌─────────────────────────────────────────────────────┐
│ 5.7.4 ■ $MVP$ ... Maximizes viewport to full screen │
└─────────────────────────────────────────────────────┘

Format:  $MVP(port1,port2,...)$
Syntax:  $MVP(opt:PORT1, ...)$                                        > v2.A4
                  ─────                                               > v2.A4
                  ALL                                                 > v2.A4
                  CUR                                                 > v2.A4
                  0-35                                                > v2.A4
                  ─────                                               > v2.A4
              def=CUR                                                 > v2.A4

This command will take the specified viewport and make it full-screen > v2.A1
regardless of its current settings.  This does not affect any current > v2.A1
graphics on the screen, only the internal viewport definition.  The   > v2.A1
possible settings for the WHICH parameter are:                        > v2.A1

            ALL ... Maximize all viewports at once                    > v2.A1
            CUR ... Maximize only the current viewport                > v2.A1
         number ... Maximize a particular viewport slot number (0-35) > v2.A4

To maximize more then one slot at the same time without maximizing    > v2.A1
all slots, simply specify more then one slot number parameter.        > v2.A1

If any one of the parameters fails to match the proper parameters,    > v2.A4
then the entire command is considered a syntax error and none of the  > v2.A4
parameters are processed.  If the underlying port of any viewport     > v2.A4
specified is not in use (ie, defined), deactivated or protected, then > v2.A4
this command does nothing for that viewport.                          > v2.A4

     Example:  $MVP(5)$                                               > v2.A1
     Returns:  nothing                                                > v2.A1



┌──────────────────────────────────────────────────────────────┐
│ 5.7.5 ■ $OFFSCREEN$ ... Get offscreen bitmap port pixel data │
└──────────────────────────────────────────────────────────────┘

Format:  $OFFSCREEN(mode)$
Syntax:  $OFFSCREEN(opt:MODE)$                                        > v2.A4
                        ────                                          > v2.A4
                        FREE                                          > v2.A4
                        USED                                          > v2.A4
                        TOTAL                                         > v2.A4
                        ────                                          > v2.A4
                    def=FREE                                          > v2.A4

This command determines offscreen bitmap port pixel data.  As         > v2.A4
described earlier on in this document, the offscreen bitmap ports     > v2.A4
that you may defined cannot exceed the total number of device pixels  > v2.A4
used on your screen.  In other words, if you have a screen that is    > v2.A4
1000 pixels wide, by 500 tall, then you would have a total number of  > v2.A4
pixels available for offscreen bitmap ports of 1000x500 (or 500,000). > v2.A4

When a new port is defined as an offscreen bitmap port, it calculates > v2.A4
the width and height of that port in hardware pixels and reduces the  > v2.A4
remaining offscreen pixels by that amount.                            > v2.A4

If you specify the MODE parameter of this command as "FREE", then you > v2.A4
are requesting the total number of unused pixels available for use    > v2.A4
in offscreen bitmap ports.  If MODE is set to "USED", then you are    > v2.A4
requesting the total number of offscreen pixels current "in use" by   > v2.A4
offscreen bitmap ports.  Finally, if MODE is set to "TOTAL", then you > v2.A4
are requesting the total number of offscreen pixels for all bitmap    > v2.A4
ports at once (FREE plus USED should equal TOTAL).  If you omit the   > v2.A4
MODE parameter, then "FREE" is assumed.                               > v2.A4

     Example:  $OFFSCREEN(TOTAL)$                                     > v2.A4
     Returns:  500000                                                 > v2.A4

     Example:  $OFFSCREEN(USED)$                                      > v2.A4
     Returns:  200000                                                 > v2.A4

     Example:  $OFFSCREEN(FREE)$                                      > v2.A4
     Returns:  300000                                                 > v2.A4


┌────────────────────────────────────┐
│ 5.7.6 ■ $PORTH$ ... Height of port │
└────────────────────────────────────┘

Format:  $PORTH(portno,type,domain)$
Syntax:  $PORTW(opt:PORTNO, opt:DOMAIN)$                              > v2.A4
                    ──────      ──────                                > v2.A4
                    CUR         WORLD                                 > v2.A4
                    0-35        DEVICE                                > v2.A4
                    ──────      ──────                                > v2.A4
                def=CUR     def=WORLD                                 > v2.A4

This text variable is identical in nature to the $PORTW$ text         > v2.A4
variable, except that it returns height information about the port    > v2.A4
instead of width.                                                     > v2.A4



┌───────────────────────────────────┐
│ 5.7.7 ■ $PORTW$ ... Width of port │
└───────────────────────────────────┘

Format:  $PORTW(portno,domain)$
Syntax:  $PORTW(opt:PORTNO, opt:DOMAIN)$                              > v2.A4
                    ──────      ──────                                > v2.A4
                    CUR         WORLD                                 > v2.A4
                    0-35        DEVICE                                > v2.A4
                    ──────      ──────                                > v2.A4
                def=CUR     def=WORLD                                 > v2.A4

This text variable returns the a piece of width information about the > v2.A4
specified port.                                                       > v2.A4

If no parameters are specified, then you a request is being made for  > v2.A4
the width of the current drawing port itself.

If you specify the portno parameter, then you are indicating which    > v2.A4
port you are requesting information on.  You may indicate "CUR" for   > v2.A4
the current port, or a value from 0-35 to indicate a specific port    > v2.A4
number.                                                               > v2.A4

The type parameter defines what type of port information you are      > v2.A4
requesting.  If it is omitted then you can only specify the portno    > v2.A4
parameter and this will return the width of the port itself.  If you  > v2.A4
specify the type parameter, then you may set this to "PORT" to        > v2.A4
explicitly indicate that you want information specifically on the     > v2.A4
port, or a value of "VIEW" to return information on the viewport.     > v2.A4

If the type parameter is "VIEW", then you are specifically requesting > v2.A4
the width of the viewport itself.                                     > v2.A4

The third and final parameter is the domain parameter.  This          > v2.A4
specifies what type of coordinate information you are requesting.  By > v2.A4
default, if this parameter is omitted then you are requesting your    > v2.A4
coordinate information in world coordinate values.  Possible domain   > v2.A4
values are "WORLD" to explicitly request world coordinate values, or  > v2.A4
"DEVICE" for physical hardware device pixel coordinates.              > v2.A4

If you request information on a port (or the viewport belonging to a  > v2.A4
port) where the port isn't defined (ie, not in use), or it is         > v2.A4
deactivated, then this variable returns a value of "0" to indicate    > v2.A4
this error condition.                                                 > v2.A4

     Example:  $PORTW$                                                > v2.A4
     Returns:  100                                                    > v2.A4

     Example:  $PORTW(CUR)$                                           > v2.A4
     Returns:  100                                                    > v2.A4

     Example:  $PORTW(CUR,PORT)$                                      > v2.A4
     Returns:  100                                                    > v2.A4

     Example:  $PORTW(CUR,PORT,WORLD)$                                > v2.A4
     Returns:  100                                                    > v2.A4

     Example:  $PORTW(CUR,PORT,DEVICE)$                               > v2.A4
     Returns:  50                                                     > v2.A4



┌─────────────────────────────────────────────────────┐
│ 5.7.8 ■ $PORTX0$ ... Port's upper left X coordinate │
└─────────────────────────────────────────────────────┘

Format:  $PORTX0(portno,type,domain)$
Syntax:  $PORTX0(opt:PORTNO, opt:TYPE, opt:DOMAIN)$                   > v2.A4
                     ──────      ────      ──────                     > v2.A4
                     CUR         PORT      WORLD                      > v2.A4
                     0-35        VIEW      DEVICE                     > v2.A4
                     ──────      ────      ──────                     > v2.A4
                 def=CUR     def=PORT  def=WORLD                      > v2.A4

This text variable returns the a piece of upper-left X coordinate     > v2.A4
information about the specified port.                                 > v2.A4

If no parameters are specified, then you a request is being made for  > v2.A4
the upper-left X coordinate of the current drawing port itself        > v2.A4
related to the current screen.  This is only meaningful for "screen   > v2.A4
ports" where this X coordinate specifies an offset from the left      > v2.A4
border of the screen in pixels.  For offscreen bitmapped ports, there > v2.A4
is no upper-left X coordinate (or more precisely, an offset from some > v2.A4
screen), so for offscreen ports this variation returns a value of     > v2.A4
"0".  Port number 0 would always yield a value of "0" because its     > v2.A4
port is set to the full dimensions of the screen so there's no offset > v2.A4
information for the upper-left X coordinate.                          > v2.A4

If you specify the portno parameter, then you are indicating which    > v2.A4
port you are requesting information on.  You may indicate "CUR" for   > v2.A4
the current port, or a value from 0-35 to indicate a specific port    > v2.A4
number.                                                               > v2.A4

The type parameter defines what type of port information you are      > v2.A4
requesting.  If it is omitted then you can only specify the portno    > v2.A4
parameter and this will return the upper-left X coordinate of the     > v2.A4
port itself.  If you specify the type parameter, then you may set     > v2.A4
this to "PORT" to explicitly indicate that you want information       > v2.A4
specifically on the port, or a value of "VIEW" to return information  > v2.A4
on the viewport.                                                      > v2.A4

If the type parameter is "VIEW", then you are specifically requesting > v2.A4
the upper-left X coordinate of the viewport in relation to the port's > v2.A4
actual origin (the upper-left corner of the port).                    > v2.A4

The third and final parameter is the domain parameter.  This          > v2.A4
specifies what type of coordinate information you are requesting.  By > v2.A4
default, if this parameter is omitted then you are requesting your    > v2.A4
coordinate information in world coordinate values.  Possible domain   > v2.A4
values are "WORLD" to explicitly request world coordinate values, or  > v2.A4
"DEVICE" for physical hardware device pixel coordinates.              > v2.A4

If you request information on a port (or the viewport belonging to a  > v2.A4
port) where the port isn't defined (ie, not in use), or it is         > v2.A4
deactivated, then this variable returns a value of "-1" to indicate   > v2.A4
this error condition.                                                 > v2.A4

     Example:  $PORTX0$                                               > v2.A4
     Returns:  100                                                    > v2.A4

     Example:  $PORTX0(CUR)$                                          > v2.A4
     Returns:  100                                                    > v2.A4


     Example:  $PORTX0(CUR,PORT)$                                     > v2.A4
     Returns:  100                                                    > v2.A4

     Example:  $PORTX0(CUR,PORT,WORLD)$                               > v2.A4
     Returns:  100                                                    > v2.A4

     Example:  $PORTX0(CUR,PORT,DEVICE)$                              > v2.A4
     Returns:  50                                                     > v2.A4


┌──────────────────────────────────────────────────────┐
│ 5.7.9 ■ $PORTX1$ ... Port's lower right X coordinate │
└──────────────────────────────────────────────────────┘

Format:  $PORTX1(portno,type,domain)$
Syntax:  $PORTX1(opt:PORTNO, opt:TYPE, opt:DOMAIN)$                   > v2.A4
                     ──────      ────      ──────                     > v2.A4
                     CUR         PORT      WORLD                      > v2.A4
                     0-35        VIEW      DEVICE                     > v2.A4
                     ──────      ────      ──────                     > v2.A4
                 def=CUR     def=PORT  def=WORLD                      > v2.A4

This text variable returns the a piece of lower-right X coordinate    > v2.A4
information about the specified port.                                 > v2.A4

If no parameters are specified, then you a request is being made for  > v2.A4
the lower-right X coordinate of the current drawing port itself       > v2.A4
related to the current screen.  This is only meaningful for "screen   > v2.A4
ports" where this X coordinate specifies an offset from the left      > v2.A4
border of the screen in pixels.  For offscreen bitmapped ports, there > v2.A4
is no upper-left X coordinate (or more precisely, an offset from some > v2.A4
screen), so for offscreen ports this variation returns a value that   > v2.A4
is equivalent to the width of the port.  Port number 0 would always   > v2.A4
yield a value that is the width of the actual screen because its port > v2.A4
is set to the full dimensions of the screen so there's no offset      > v2.A4
information for the upper-left X coordinate.                          > v2.A4

If you specify the portno parameter, then you are indicating which    > v2.A4
port you are requesting information on.  You may indicate "CUR" for   > v2.A4
the current port, or a value from 0-35 to indicate a specific port    > v2.A4
number.                                                               > v2.A4

The type parameter defines what type of port information you are      > v2.A4
requesting.  If it is omitted then you can only specify the portno    > v2.A4
parameter and this will return the lower-right X coordinate of the    > v2.A4
port itself.  If you specify the type parameter, then you may set     > v2.A4
this to "PORT" to explicitly indicate that you want information       > v2.A4
specifically on the port, or a value of "VIEW" to return information  > v2.A4
on the viewport.                                                      > v2.A4

If the type parameter is "VIEW", then you are specifically requesting > v2.A4
the lower-right X coordinate of the viewport in relation to the       > v2.A4
port's actual origin (the lower-right corner of the port).            > v2.A4

The third and final parameter is the domain parameter.  This          > v2.A4
specifies what type of coordinate information you are requesting.  By > v2.A4
default, if this parameter is omitted then you are requesting your    > v2.A4
coordinate information in world coordinate values.  Possible domain   > v2.A4
values are "WORLD" to explicitly request world coordinate values, or  > v2.A4
"DEVICE" for physical hardware device pixel coordinates.              > v2.A4


If you request information on a port (or the viewport belonging to a  > v2.A4
port) where the port isn't defined (ie, not in use), or it is         > v2.A4
deactivated, then this variable returns a value of "-1" to indicate   > v2.A4
this error condition.                                                 > v2.A4

Note that the lower-right X coordinate is non-inclusive.  This means  > v2.A4
that the lower-right X coordinate is not actually part of the port's  > v2.A4
drawing area.  It works exactly like the rectangle defining a filled  > v2.A4
rectangle.                                                            > v2.A4

     Example:  $PORTX1$                                               > v2.A4
     Returns:  100                                                    > v2.A4

     Example:  $PORTX1(CUR)$                                          > v2.A4
     Returns:  100                                                    > v2.A4

     Example:  $PORTX1(CUR,PORT)$                                     > v2.A4
     Returns:  100                                                    > v2.A4

     Example:  $PORTX1(CUR,PORT,WORLD)$                               > v2.A4
     Returns:  100                                                    > v2.A4

     Example:  $PORTX1(CUR,PORT,DEVICE)$                              > v2.A4
     Returns:  50                                                     > v2.A4


┌───────────────────────────────────────────────────────────────────┐
│ $PORTY0(portno,type,domain)$ ... Port's upper left Y coordinate   │
└───────────────────────────────────────────────────────────────────┘

Syntax:  $PORTY0(opt:PORTNO, opt:TYPE, opt:DOMAIN)$                   > v2.A4
                     ──────      ────      ──────                     > v2.A4
                     CUR         PORT      WORLD                      > v2.A4
                     0-35        VIEW      DEVICE                     > v2.A4
                     ──────      ────      ──────                     > v2.A4
                 def=CUR     def=PORT  def=WORLD                      > v2.A4

This command is identical in nature to the $PORTX0$ text variable,    > v2.A4
except that it returns upper-left Y coordinate information on the     > v2.A4
port.                                                                 > v2.A4


┌───────────────────────────────────────────────────────┐
│ 5.7.11 ■ $PORTY1$ ... Port's lower right Y coordinate │
└───────────────────────────────────────────────────────┘

Format:  $PORTY1(viewno,coordtype)$
Syntax:  $PORTY1(opt:PORTNO, opt:TYPE, opt:DOMAIN)$                   > v2.A4
                     ──────      ────      ──────                     > v2.A4
                     CUR         PORT      WORLD                      > v2.A4
                     0-35        VIEW      DEVICE                     > v2.A4
                     ──────      ────      ──────                     > v2.A4
                 def=CUR     def=PORT  def=WORLD                      > v2.A4

This command is identical in nature to the $PORTX1$ text variable,    > v2.A4
except that it returns lower-right Y coordinate information on the    > v2.A4
port.                                                                 > v2.A4



╔═════════════════════════════════════════╗
║ 5.8 ■ TERMINAL OPERATION TEXT VARIABLES ║
╚═════════════════════════════════════════╝

These text variables return information on, or manipulate a mode of   > v2.A4
operation of the RIPscrip terminal.                                   > v2.A4


┌─────────────────────────────────────────────┐
│ 5.8.1 ■ $APP$ ... External Application Call │
└─────────────────────────────────────────────┘

Format:  $APP(appno,argument)$
Syntax:  $APP(opt:APPNO, opt:ARGUMENT)$                               > v2.A4
                  ─────      ────────                                 > v2.A4
                  0-9        A word                                   > v2.A4
                  ─────      ────────                                 > v2.A4
              def=0      def=<none>                                   > v2.A4

This text variable instructs the terminal to execute an external      > v2.A1
application.  If you do not specify any parameters, then application  > v2.A1
number zero will be executed.  If you do specify any parameters, you  > v2.A1
may specify one or both of them.  If you supply the ARGUMENT          > v2.A1
parameter, you must specify the APPNO option.  APPNO is a number from > v2.A1
0-9 indicating which application should be executed.  If used, the    > v2.A1
ARGUMENT parameter is an arbitrary command line argument that will be > v2.A1
added to the end of the application's command line string.  This      > v2.A1
gives the ability to allow the host to control portions of the        > v2.A1
external application's operation.                                     > v2.A1

     Example:  $APP(0,FILENAME.TXT)                                   > v2.A1
     Returns:  nothing                                                > v2.A1


┌──────────────────────────────────────────────────────┐
│ 5.8.2 ■ $APPx$ ... External Application Call (x=0-9) │
└──────────────────────────────────────────────────────┘

Format:  $APP0$ - $APP9$
Syntax:  $APP0$ ... $APP9$                                            > v2.A4

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

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

     Example:  $APP1$
     Returns:  nothing



┌───────────────────────────────────────────────────────┐
│ 5.8.3 ■ $BAUDEMUL$ ... Set/return baud rate emulation │
└───────────────────────────────────────────────────────┘

Format:  $BAUDEMUL(env_no, baud_rate)$
Syntax:  $BAUDEMUL(opt:ENV_NO, opt:BAUD_RATE)$                        > v2.A4
                       ──────      ─────────                          > v2.A4
                       CUR         Number                             > v2.A4
                       0-35        ─────────                          > v2.A4
                       ──────  def=0                                  > v2.A4
                   def=CUR                                            > v2.A4

This variable allows the host to determine the current baud rate      > v2.A4
emulation setting for use with local RIP file playback.               > v2.A4

Without any parameters, this variable inquires about the baud rate    > v2.A4
setting for the current environment.  If only one parameter is        > v2.A4
supplied, then it is inquiring about a specific environment number    > v2.A4
and that number can be from 0-35 or the value "CUR" for the current   > v2.A4
environment.  If the environment being inquired about isn't in use,   > v2.A4
then this command returnes a value of "NONE".                         > v2.A4

A return value of "0" means that playback should occur at full speed. > v2.A4
Typical return values can be 0, 300, 1200, 2400, 4800, 9600, 14400,   > v2.A4
16800, 19200, 28800, 38400, 57600 and 115200.  These are not the only > v2.A4
values that can be returned.  If you want to set a baud rate          > v2.A4
emulation value of 12345, baud you can.                               > v2.A4

If you specify two parameters, then the first one must be the         > v2.A4
environment to be modified (0-35 or CUR - see above).  The second     > v2.A4
parameter can be a number from 0 on up, which specifies the baud rate > v2.A4
which you wish to set to that environment.  If the destination        > v2.A4
environment isn't in use, then a syntax erorr is generated.           > v2.A4

     Example:  $BAUDEMUL$                                             > v2.A4
     Returns:  9600                                                   > v2.A4

     Example:  $BAUDEMUL(CUR)$                                        > v2.A4
     Returns:  9600                                                   > v2.A4

     Example:  $BAUDEMUL(35)$                                         > v2.A4
     Returns:  NONE                                                   > v2.A4

     Example:  $BAUDEMUL(CUR, 2400)$                                  > v2.A4
     Returns:  nothing - sets current environment to 2400 baud        > v2.A4


┌────────────────────────────────────────────────────┐
│ 5.8.4 ■ $D$ ... Delay for a number of milliseconds │
└────────────────────────────────────────────────────┘

Format:  $D(duration)$
Syntax:  $D(req:DURATION)$                                            > v2.A4
                ────────                                              > v2.A4
                1-65535                                               > v2.A4

This command causes a delay to occur.  During this time, the terminal > v2.A1
program "stops" everything except for any sound related activity.     > v2.A2
The TIME parameter must be specified.  Its value is specified in      > v2.A1
60ths of a second.  This command is useful to pause for a short time  > v2.A1


for things like prompts to go by or whatever.                         > v2.A1

     Example:  $D(60)$                                                > v2.A4
     Returns:  nothing                                                > v2.A1


┌─────────────────────────────────────────────┐
│ 5.8.5 ■ $DWAYOFF$ ... Turn Doorway Mode OFF │
└─────────────────────────────────────────────┘

Format:  $DWAYOFF$
Syntax:  $DWAYOFF$                                                    > v2.A4

This Active Text Variable disables the Doorway keyboard mode.  This
will return the keyboard to normal operation.

     Example:  $DWAYOFF$
     Returns:  nothing


┌───────────────────────────────────────────┐
│ 5.8.6 ■ $DWAYON$ ... Turn Doorway Mode ON │
└───────────────────────────────────────────┘

Format:  $DWAYON$
Syntax:  $DWAYON$                                                     > v2.A4

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


┌─────────────────────────────────────────────────────┐
│ 5.8.7 ■ $FILEDEL$ ... Delete one or more host files │
└─────────────────────────────────────────────────────┘

Format:  $FILEDEL(filename,file2
Syntax:  $FILEDEL(req:FILENAME, ...)$                                 > v2.A4
                      ────────                                        > v2.A4
                      A filename                                      > v2.A4

This text variable exists so that a host system can clean up          > v2.A4
after itself, with the ability to delete files that it created, but   > v2.A4
no longer needs.  At least one parameter must be specified, and it    > v2.A4
must be a filename that the host created, or downloaded to the        > v2.A4
terminal via RIP_ENTER_BLOCK_MODE or by some other means.  No         > v2.A4
form of wildcard information is processed, nor is path information.   > v2.A4
If present, it will be ignored to the best of the terminal's          > v2.A4
ability.  You may specify more than one filename parameter with this  > v2.A4
command to delete multiple files with one "shorter" command.          > v2.A4



┌──────────────────────────────────────────────┐
│ 5.8.8 ■ $HKEYOFF$ ... Disable Button Hotkeys │
└──────────────────────────────────────────────┘

Format:  $HKEYOFF$
Syntax:  $HKEYOFF$                                                    > v2.A4

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


┌────────────────────────────────────────────┐
│ 5.8.9 ■ $HKEYON$ ... Enable Button Hotkeys │
└────────────────────────────────────────────┘

Format:  $HKEYON$
Syntax:  $HKEYON$                                                     > v2.A4

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


┌─────────────────────────────────────────────────────────────┐
│ 5.8.10 ■ $NOREFRESH$ ... Disables screen refresh expression │
└─────────────────────────────────────────────────────────────┘

Format:  $NOREFRESH$
Syntax:  $NOREFRESH$                                                  > v2.A4

This command disables a host defined refresh expression.  When you do > v2.A1
this, the refresh option for the terminal is disabled and cannot be   > v2.A1
selected (or if it can be selected, does nothing).  This is           > v2.A1
equivalent to issuing a RIP_SET_REFRESH with a $OFF$ parameter to     > v2.A4
disable refreshing.                                                   > v2.A1

     Example:  $NOREFRESH$                                            > v2.A1
     Returns:  none                                                   > v2.A1



┌────────────────────────────────────────────────────────┐
│ 5.8.11 ■ $OPTION$ ... Enable/disable a software option │
└────────────────────────────────────────────────────────┘

Format:  $OPTION(option_name,mode)$
Syntax:  $OPTION(req:OPTION_NAME, opt:MODE)$                          > v2.A4
                     ───────────      ────                            > v2.A4
                     LIST             ON:OPTION_NAME<>LIST            > v2.A4
                     DOORWAY          OFF:OPTION_NAME<>LIST           > v2.A4
                     HOTKEY           QUERY:OPTION_NAME<>LIST         > v2.A4
                     STATBAR          ────                            > v2.A4
                     TAB          def=<none>:OPTION_NAME=LIST         > v2.A4
                                      QUERY:OPTION_NAME<>LIST         > v2.A4

This command allows you to turn on or turn off a specific system      > v2.A4
option in the RIPscrip application.  The possible options that can    > v2.A4
be enabled or disabled are specified with the <name> parameter as     > v2.A3
follows:                                                              > v2.A3

  Name      Description                                               > v2.A3
  ───────────────────────────────────────────────────────────────     > v2.A3
  HOTKEY    Alter the status of Hotkey processing                     > v2.A4
  TAB       Alter the status of Tab mouse-field navigation            > v2.A3
  DOORWAY   Alter the status of Doorway (tm) mode                     > v2.A3
  STATBAR   Alter the status of the terminal program's status bar     > v2.A3
  LIST      Display a list of all options that can be toggled (see    > v2.A4
            below)                                                    > v2.A4

After the <name> parameter comes the <mode> parameter which specifies > v2.A3
whether to turn the option on or off.  The possible values for the    > v2.A4
<mode> parameter are "ON" and "OFF".                                  > v2.A3

The LIST keyword is designed to list out all options in the software  > v2.A4
that can be enabled or disabled.  This allows for extendibility for   > v2.A4
custom RIPscrip packages by other vendors - some vendors may have     > v2.A4
certain features, and others may not.  For example, if a specific     > v2.A4
terminal program doesn't support Doorway Mode, then the DOORWAY       > v2.A4
option wouldn't be available (and wouldn't show up if you did a       > v2.A4
$OPTION(LIST)$ directive).  The list is not carriage return           > v2.A4
delimited.  The text returned to the host is not terminated with any  > v2.A4
carriage returns or anything like that.  It's up to you to provide    > v2.A4
that kind of information in a button's host string or in a query      > v2.A4
string.  The LIST directive though returns a list of all recognized   > v2.A4
keywords for that terminal.  For example, RIPterm Pro returns the     > v2.A4
following for the $OPTION(LIST)$ expression:                          > v2.A4

     DOORWAY,HOTKEY,LIST,STATBAR,TAB                                  > v2.A4

Note, the list is comma (,) delimited between keywords, but not after > v2.A4
the last keyword.  In addition, the keywords are returned in          > v2.A4
alphabetical order, converted to all capitals.                        > v2.A4

You may ask the terminal to report the status of a particular option
with this command as well.  To do so, specify a <mode> of "QUERY" or
omit it altogether.  If the option is enabled, a "1" is returned to
the host.  If it is disabled, then "0" is returned.  Again, no
carriage returns or other delimiters are returned to the host.

     Example:  $OPTION(DOORWAY, ON)$
     Returns:  nothing - enabled doorway mode


     Example:  $OPTION(LIST)$
     Returns:  DOORWAY,HOTKEY,LIST,STATBAR,TAB

     Example:  $OPTION(DOORWAY, QUERY)$
     Returns:  0

     Example:  $OPTION(DOORWAY)$
     Returns:  0

     Example:  $OPTION(LIST, QUERY)$
     Returns:  $OPTION(LIST, QUERY)$    ... Syntax error


┌────────────────────────────────────────────────────────────┐
│ 5.8.12 ■ $REFRESH$ ... Forces terminal to Transmit Refresh │
└────────────────────────────────────────────────────────────┘

Format:  $REFRESH$
Syntax:  $REFRESH$                                                    > v2.A4

This text variable instructs the terminal to transmit the refresh     > v2.A1
host command to the remote host system if the refresh expression is   > v2.A1
non-NULL.  The host has the ability to set a refresh expression that  > v2.A1
will, when sent, redisplay the current screen.                        > v2.A1

     Example:  $REFRESH$                                              > v2.A1
     Returns:  ^m                                                     > v2.A1


┌────────────────────────────────────────────────┐
│ 5.8.13 ■ $SBAROFF$ ... Turn OFF the Status Bar │
└────────────────────────────────────────────────┘

Format:  $SBAROFF$
Syntax:  $SBAROFF$                                                    > v2.A4

This Active Text Variable turns OFF the Status Bar in the terminal.

     Example:  $SBAROFF$
     Returns:  nothing


┌──────────────────────────────────────────────┐
│ 5.8.14 ■ $SBARON$ ... Turn ON the Status Bar │
└──────────────────────────────────────────────┘

Format:  $SBARON$
Syntax:  $SBARON$                                                     > v2.A4

This Active Text Variable turns ON the Status Bar in the terminal.

     Example:  $SBARON$
     Returns:  nothing



┌──────────────────────────────────────────┐
│ 5.8.15 ■ $STATBAR$ ... Status Bar Status │
└──────────────────────────────────────────┘

Format:  $STATBAR$
Syntax:  $STATBAR$                                                    > v2.A4

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


┌──────────────────────────────────────────────────────────┐
│ 5.8.16 ■ $TABOFF$ ... Disable TAB key Mouse Field select │
└──────────────────────────────────────────────────────────┘

Format:  $TABOFF$
Syntax:  $TABOFF$                                                     > v2.A4

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


┌────────────────────────────────────────────────────────┐
│ 5.8.17 ■ $TABON$ ... Enable TAB key Mouse Field select │
└────────────────────────────────────────────────────────┘

Format:  $TABON$
Syntax:  $TABON$                                                      > v2.A4

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


┌───────────────────────────────────────────────────────┐
│ 5.8.18 ■ $VT102OFF$ ... Turn VT-102 keyboard mode OFF │
└───────────────────────────────────────────────────────┘

Format:  $VT102OFF$
Syntax:  $VT102OFF$                                                   > v2.A4

This Active Text Variable disables the VT-102 terminal emulation      > v2.A4
mode, returning your text windows to standard ANSI operation.         > v2.A4

     Example:  $VT102OFF$
     Returns:  nothing


┌─────────────────────────────────────────────────────┐
│ 5.8.19 ■ $VT102ON$ ... Turn VT-102 keyboard mode ON │
└─────────────────────────────────────────────────────┘

Format:  $VT102ON$
Syntax:  $VT102ON$                                                    > v2.A4

This Active Text Variable enables the VT-102 terminal emulation
option of the RIPscrip software.  This affects character placement    > v2.A4
and formatting of text in a text window, and also the way that the    > v2.A4
keyboard operates.                                                    > v2.A4

     Example:  $VT102ON$
     Returns:  nothing



╔═════════════════════════════════════════════╗
║ 5.9 ■ RIPSCRIP RESET RELATED TEXT VARIABLES ║
╚═════════════════════════════════════════════╝

These text variables reset particular aspects of the RIPscrip         > v2.A4
environment.                                                          > v2.A4


┌───────────────────────────────────────────────┐
│ 5.9.1 ■ $RESET$ ... Perform a reset operation │
└───────────────────────────────────────────────┘

Format:  $RESET(option,element,sub_element)$
Syntax:  $RESET(opt:OPTION, opt:ELEMENT, opt:SUB_ELEMENT)$            > v2.A4
                    ──────      ───────                               > v2.A4
                    SOFT        CUR:OPTION=TW,STYLE,BUT,PAL,PORT,ENV, > v2.A4
                                           VIEW                       > v2.A4
                    HARD        0-35:OPTION=TW,STYLE,BUT,PAL,PORT,    > v2.A4
                                            ENV,VIEW                  > v2.A4
                    MCURSOR     TBL:OPTION=TW,STYLE,BUT,PAL,PORT,ENV, > v2.A4
                                           MOUSE,VIEW                 > v2.A4
                    KEYBOARD    BASE:OPTION=TW,STYLE,BUT,PAL,PORT,    > v2.A4
                                            ENV,MOUSE,SCREEN          > v2.A4
                    SOUND       S0-S9:OPTION=TW,STYLE,BUT,PAL,PORT,   > v2.A4
                                             ENV,MOUSE,SCREEN         > v2.A4
                    TW          SLOTS:OPTION=TW,STYLE,BUT,PAL,PORT,   > v2.A4
                                             ENV,MOUSE,SCREEN         > v2.A4
                    STYLE       STACK:OPTION=TW,STYLE,BUT,PAL,PORT,   > v2.A4
                                             ENV,MOUSE,SCREEN         > v2.A4
                    BUT         BACKUP:OPTION=TW,STYLE,BUT,PAL,PORT,  > v2.A4
                                              ENV,MOUSE,SCREEN        > v2.A4
                    PAL         ALL:OPTION=TW,STYLE,BUT,PAL,PORT,     > v2.A4
                                           ENV,MOUSE,SCREEN,QUERY     > v2.A4
                    PORT        TW:OPTION=QUERY                       > v2.A4
                    ENV                   VIEW:OPTION=QUERY           > v2.A4
                    MOUSE       ───────                               > v2.A4
                    SCREEN  def=ALL:OPTION=QUERY                      > v2.A4
                    VIEW        <none>:OPTION=HARD,MCURSOR,KEYBOARD,  > v2.A4
                    QUERY                     SOUND,SCREEN            > v2.A4
                    ──────      CUR:OPTION=TW,STYLE,BUT,PAL,PORT,ENV, > v2.A4
                def=SOFT                   VIEW                       > v2.A4
                                TBL:OPTION=MOUSE                      > v2.A4

                opt:SUB_ELEMENT                                       > v2.A4
                    ───────────                                       > v2.A4
                    ALL:ELEMENT=TW,VIEW                               > v2.A4
                    CUR:ELEMENT=TW,VIEW                               > v2.A4
                    TBL:ELEMENT=TW,TBL                                > v2.A4
                    ───────────                                       > v2.A4
                def=ALL:OPTION=QUERY                                  > v2.A4
                    <none>:OPTION<>QUERY                              > v2.A4

The reset text variable is a general purpose reset command.  Without  > v2.A4
any parameters, the text variable adheres to the original 1.54        > v2.A4
RIPscrip command which performs the exact same operations as a        > v2.A4
RIP_RESET_WINDOWS command.  Some parameters used with the reset       > v2.A4
command require additional parameters to further specify what section > v2.A4
is to be reset (eg, if you specify "TW" to reset a text window, you   > v2.A4
need to specify what text window data table entry is to be reset).    > v2.A4
The possible reset "types" are as follows:                            > v2.A4


               Uses                                                   > v2.A4
  Reset type   Parms   Description                                    > v2.A4
  ─────────────────────────────────────────────────────────────────── > v2.A4
     SOFT       No     Performs a soft reset (like RIP_RESET_WINDOWS) > v2.A4
     HARD       No     Performs a hard reset (like RIP_HEADER)        > v2.A4
     MCURSOR    No     Reset mouse cursor to standard cursor shape    > v2.A4
     KEYBOARD   No     Reset keyboard state back to input status      > v2.A4
     SOUND      No     Stops any currently playing digitized sound    > v2.A4
     TW         Yes    Reset aspects of the text window system        > v2.A4
     STYLE      Yes    Reset aspects of the graphical style system    > v2.A4
     BUT        Yes    Reset aspects of the button style system       > v2.A4
     PAL        Yes    Reset aspects of the color palette system      > v2.A4
     PORT       Yes    Reset aspects of the drawing port system       > v2.A4
     ENV        Yes    Reset aspects of the environment system        > v2.A4
     MOUSE      Yes    Resets the mouse table (clears all entries)    > v2.A4
     SCREEN     Yes    Resets aspects of the screen system            > v2.A4
     VIEW       Yes    Resets aspects drawing port viewports          > v2.A4
     QUERY      Yes    Resets resident queries (clears them)          > v2.A4

The following paragraphs describe the purpose of each parameter and   > v2.A4
how each parameter operations:                                        > v2.A4

SOFT - This makes the reset command perform a soft reset.  This is    > v2.A4
identical in nature to the RIP_RESET_WINDOWS command.  See that       > v2.A4
RIPscrip command for a complete, detailed description of what a soft  > v2.A4
reset does.                                                           > v2.A4

HARD - This performs a hard reset command.  This is as if you issued  > v2.A4
the RIP_HEADER command with the "hard reset" flag enabled.  See the   > v2.A4
RIP_HEADER command for more details about a hard reset.               > v2.A4

MCURSOR - When this parameter is specified then the mouse cursor on   > v2.A4
the terminal is switched to its default, arrow shape.  If the mouse   > v2.A4
input is currently disabled (via a RIP_HEADER command), then it is    > v2.A4
once again re-enabled as if a RIP_NO_MORE command were received.      > v2.A4

KEYBOARD - When this parameter is specified, then keyboard input is   > v2.A4
once again enabled.  Keyboard input can only be disabled via the      > v2.A4
RIP_HEADER command, and typically is re-enabled by a RIP_NO_MORE      > v2.A4
sequence.  This allows you to explicitly re-enable the keyboard       > v2.A4
without a RIP_NO_MORE command being specified.                        > v2.A4

SOUND - This reset command stops any playing digitized sound (if      > v2.A4
any).  If the sound is currently in the process of playing, it is     > v2.A4
aborted immediately to where there's no sound playing anymore.        > v2.A4

TW - This parameter allows you to reset certain aspects of the text   > v2.A4
the text window system.  The exact operation depends on what text     > v2.A4
window is being acted upon.  If text window #0 is being reset,        > v2.A4
then it is set to full screen (no window clearing is performed).      > v2.A4
If it refers to a text window other than text window #0, then that    > v2.A4
window is formally deleted.  If the current text window is a          > v2.A4
window other than window #0 and it is reset, then the text window     > v2.A4
is automatically switched to text window #0.  If the reset affects    > v2.A4
a data backup area, then the data backup area in question is          > v2.A4
deleted entirely.  If you specify no parameters, then the current     > v2.A4
text window is reset.  You may specify one or more parameters with    > v2.A4
this command to specifically alter particular aspects of the text     > v2.A4
window system.  You may specify the following parameters:             > v2.A4


     CUR       Reset the current text window.                         > v2.A4
     0-35      Reset a specific text window data table entry.         > v2.A4
     TBL       Reset all text window data table entries.              > v2.A4
     BASE      Reset (clear) the text window base save area           > v2.A4
     S0-S9     Reset (clear) a specific text window data save slot    > v2.A4
     SLOTS     Reset (clears) all text window data save slots         > v2.A4
     STACK     Reset (clears) the text window data save stack.        > v2.A4
     BACKUP    Reset all text window backup areas (base area,         > v2.A4
               slots and stack.                                       > v2.A4
     ALL       Reset all text window data tables and backup areas     > v2.A4

  Example:  $RESET(TW, CUR, 30, BASE, S5)$                            > v2.A4

STYLE - This parameter resets a graphical style back to its default   > v2.A4
settings.  If you specify no parameters, then the current graphical   > v2.A4
style is reset to bootup defaults.  You may specify one or more       > v2.A4
parameters with this command to specifically alter particular aspects > v2.A4
of the graphics style system.  You may specify the following          > v2.A4
parameters:                                                           > v2.A4

     CUR       Reset the current graphical style to default values.   > v2.A4
     0-35      Reset a specific graphical style data table to         > v2.A4
               defaults.                                              > v2.A4
     TBL       Reset all graphical style data table entries to        > v2.A4
               defaults.                                              > v2.A4
     BASE      Reset (clear) the graphical style base save area       > v2.A4
     S0-S9     Reset (clear) a specific graphical style data save     > v2.A4
               slot                                                   > v2.A4
     SLOTS     Reset (clears) all graphical style data save slots.    > v2.A4
     STACK     Clears the graphical style data save stack.            > v2.A4
     BACKUP    Reset (clears) all graphical style backup areas (base  > v2.A4
               area, slots and stack.                                 > v2.A4
     ALL       Reset all graphical style data tables and backup areas > v2.A4

  Example:  $RESET(STYLE, CUR, 30, BASE, S5)$                         > v2.A4

BUT - This parameter resets a button style to basic button default    > v2.A4
values (see the RIP_BUTTON_STYLE command for more details).  If you   > v2.A4
specify no parameters, then the current button style is reset to      > v2.A4
bootup defaults.  You may specify one or more parameters with this    > v2.A4
command to specifically alter particular aspects of the button        > v2.A4
style system.  You may specify the following parameters:              > v2.A4

     CUR       Reset the current button style to default values.      > v2.A4
     0-35      Reset a specific button style data table to defaults.  > v2.A4
     TBL       Reset all button style data table entries to defaults. > v2.A4
     BASE      Reset (clear) the button style base save area          > v2.A4
     S0-S9     Reset (clear) a specific button style data save slot   > v2.A4
     SLOTS     Reset (clears) all button style data save slots.       > v2.A4
     STACK     Clears the button style data save stack.               > v2.A4
     BACKUP    Reset (clears) all button style backup areas (base     > v2.A4
               area, slots and stack.                                 > v2.A4
     ALL       Reset all button style data tables and backup areas    > v2.A4

  Example:  $RESET(BUT, CUR, 30, BASE, S5)$                           > v2.A4

PAL - Resets a color palette back to the default color palette.       > v2.A4
If you specify no parameters, then the current color palette is reset > v2.A4
to bootup defaults.  You may specify one or more parameters with this > v2.A4
command to specifically alter particular aspects of the color palette > v2.A4
system.  You may specify the following parameters:                    > v2.A4


     CUR       Reset the current color palette to default values.     > v2.A4
     0-35      Reset a specific color palette data table to defaults. > v2.A4
     TBL       Reset all color palette data table entries to          > v2.A4
               defaults.                                              > v2.A4
     BASE      Reset (clear) the color palette base save area.        > v2.A4
     S0-S9     Reset (clear) a specific color palette data save slot. > v2.A4
     SLOTS     Reset (clears) all color palette data save slots.      > v2.A4
     STACK     Clears the color palette data save stack.              > v2.A4
     BACKUP    Reset (clears) all color palette backup areas (base    > v2.A4
               area, slots and stack.                                 > v2.A4
     ALL       reset all color palette data tables and backup areas   > v2.A4

  Example:  $RESET(PAL, CUR, 30, BASE, S5)$                           > v2.A4

PORT - This variation on the reset command resets one or more ports   > v2.A4
in some way.  The exact way that one is reset varies depending on     > v2.A4
the type of port specified.  If no additional parameters are          > v2.A4
specified, then the current port is reset.  Otherwise, you may reset  > v2.A4
a specific port number in the port data table, or one (or all) of     > v2.A4
the port data backup areas.  If you reset a specific port in the      > v2.A4
port data table, what happens varies depending on what kind of port   > v2.A4
it is.  If it is port #0 (which cannot be deleted), then the only     > v2.A4
thing that happens is that any resident queries for that              > v2.A4
port/viewport are deleted, the viewport is made full screen and the   > v2.A4
viewport is erased to the background color (in that order).  If the   > v2.A4
port number (from 1-35) represents a screen port, then any resident   > v2.A4
query attached to that port/viewport is deleted and the port itself   > v2.A4
is deleted.  If it is an offscreen port, then that port is also       > v2.A4
deleted (offscreen ports cannot have resident queries).  In any       > v2.A4
event, if the port being deleted happens to be the current port,      > v2.A4
then the port is automatically switched to port #0 (the screen's      > v2.A4
port).  The following parameters are permitted with this reset        > v2.A4
port).  Whenever the current port is reset, the port is automatically > v2.A4
switched to port #0.  Beware of this when chaining multiple port      > v2.A4
resets together at the same time.  For example, if port #5 is current > v2.A4
and you issue the following command $RESET(PORT, 5, CUR)$, then port  > v2.A4
number 5 will be deleted, then it would switch back to port #0 which  > v2.A4

is the screen port and cannot be deleted, so only its viewport will   > v2.A4
be reset.  The following parameters are permitted with this reset     > v2.A4
command to control what type of reset operation is to be performed:   > v2.A4

     CUR       Reset (delete) the current port.                       > v2.A4
     0-35      Reset (delete) a specific port data table entry.       > v2.A4
     TBL       Reset (delete) all port data table entries.            > v2.A4
     BASE      Reset (clear) the port base save area.                 > v2.A4
     S0-S9     Reset (clear) a specific port data save slot.          > v2.A4
     SLOTS     Reset (clears) all port data save slots.               > v2.A4
     STACK     Reset (clears) the port data save stack.               > v2.A4
     BACKUP    Reset (clears) all port backup areas (base             > v2.A4
               area, slots and stack.                                 > v2.A4
     ALL       Reset all port data tables and backup areas            > v2.A4

  Example:  $RESET(PORT, CUR, 30, BASE, S5)$                          > v2.A4

ENV - This command resets an environment to either default values or  > v2.A4
to a status of "erased".  If you specify no parameters, then the      > v2.A4
current environment data table entry is reset to default bootup       > v2.A4
values.  If you do specify any parameters, then the following ones    > v2.A4
may be used:                                                          > v2.A4


     CUR       Reset the current environment to default values.       > v2.A4
     0-35      Reset a specific environment data table entry to       > v2.A4
               defaults.                                              > v2.A4
     TBL       Reset all environment data table entries to            > v2.A4
               defaults.                                              > v2.A4
     BASE      Reset (clear) the environment base save area           > v2.A4
     S0-S9     Reset (clear) a specific environment data save slot.   > v2.A4
     SLOTS     Reset (clears) all environment data save slots.        > v2.A4
     STACK     Clears the environment data save stack.                > v2.A4
     BACKUP    Reset (clears) all environment backup areas (base      > v2.A4
               area, slots and stack.                                 > v2.A4
     ALL       Reset all environment data tables and backup areas     > v2.A4

  Example:  $RESET(ENV, CUR, 30, BASE, S5)$                           > v2.A4


MOUSE - Resets (deletes) all mouse fields defined in the specified    > v2.A4
specified destination.  If no parameter is defined, then all current  > v2.A4
mouse definitions are reset.  If you specify one or more parameters,  > v2.A4
then they may be any of the following:                                > v2.A4

     TBL       Reset (clear) all existing mouse definitions in use    > v2.A4
     BASE      Reset (clear) the mouse field base save area           > v2.A4
     S0-S9     Reset a specific mouse field data save slot            > v2.A4
     SLOTS     Reset all mouse field data save slots                  > v2.A4
     STACK     Clears the data save stack pointer, but don't          > v2.A4
               reset slots                                            > v2.A4
     BACKUP    Reset all mouse field backup areas                     > v2.A4
     ALL       Reset all mouse field data tables and backup areas     > v2.A4

          Example:  $RESET(MOUSE, BASE, S5)$                          > v2.A4

SCREEN - When no parameters are specified, the entire video screen is > v2.A4
cleared to color #0 (usually black).  No viewports are modified, nor  > v2.A4
are any drawing ports, text windows, mouse fields or anything else.   > v2.A4
The following parameters are allowed, providing you with the ability  > v2.A4
to reset particular screen aspects:                                   > v2.A4

     BASE      Reset (clear) the screen base save area                > v2.A4
     S0-S9     Reset a specific screen data save slot area            > v2.A4
     SLOTS     Reset all screen data save slots                       > v2.A4
     STACK     Clears the data save stack pointer, but don't          > v2.A4
               reset slots                                            > v2.A4
     BACKUP    Reset all screen backup areas                          > v2.A4
     ALL       Reset the screen (erase) and all backup areas          > v2.A4

VIEW - When no parameters are specified, then the viewport of the     > v2.A4
current drawing port is reset to the full dimensions of the port      > v2.A4
itself, and activated.  Other possible parameters allow you to modify > v2.A4
other viewports of other ports.  The possible parameters are:         > v2.A4

     CUR       Reset the current viewport to full port size           > v2.A4
     0-35      Reset the viewport of specific port to full port size  > v2.A4
     TBL       Resets all viewports of all data table ports to full   > v2.A4
               port size                                              > v2.A4

QUERY - If no parameters are specified or a single parameter of "ALL" > v2.A4
is specified then all resident queries are reset (deleted).  If you   > v2.A4
specify any parameters, you may specify more than one.  You may       > v2.A4
specify the following as the first parameters:                        > v2.A4


     TW        Reset the text window based resident queries           > v2.A4
     VIEW      Reset the viewport based resident queries              > v2.A4

The next parameter(s) (if any) indicate the data table entry number   > v2.A4
that you wish to reset.  If no parameters are specified, then all     > v2.A4
queries for the given data type (text window or viewport) will be     > v2.A4
reset.  If you specify an actual data table entry number, then you    > v2.A4
are deleting the query for a specific text window or viewport (a      > v2.A4
fixed resident query).  You are allowed to use the following          > v2.A4
parameters after the TW or VIEW directives:                           > v2.A4

     ALL       Reset the current window query and all fixed queries   > v2.A4
     CUR       Reset the "current window" query for the given         > v2.A4
               reset type (ie, TW or VIEW)                            > v2.A4
     TBL       Reset all entry-specific queries (ie, reset all        > v2.A4
               resident queries for all specific text windows         > v2.A4
               or viewports.  The "current window" query isn't        > v2.A4
               reset.  0-35      Reset the resident query for         > v2.A4
               the specified data table entry for the given TW        > v2.A4
               or VIEW query type.                                    > v2.A4

See the RIP_QUERY command for more detailed information about the     > v2.A4
various possible resident query types.                                > v2.A4

     Example:  $RESET(QUERY, TW, CUR)$ ... Reset current text         > v2.A4
                                           window's query             > v2.A4
               $RESET(QUERY, TW, TBL)$ ... Reset all queries for      > v2.A4
                                           entries 0-35               > v2.A4
               $RESET(QUERY, TW, 5)$ ..... Reset resident query for   > v2.A4
                                           Text window #5             > v2.A4

It should be noted that if you attempt to reset something that        > v2.A4
cannot be reset (eg, drawing port #0, a protected data table entry,   > v2.A4
a stack that's empty, etc), then this command does nothing and does   > v2.A4
not generate a syntax error.  A syntax error can only be generated    > v2.A4
if an invalid parameter is encountered.  If even so much as a single  > v2.A4
parameter is invalid then the entire command is discarded as a syntax > v2.A4
error without any of the parameters being processed.                  > v2.A4



╔════════════════════════════════════════════════════════╗
║ 5.10 ■ SYSTEM ENVIRONMENT CONFIGURATION TEXT VARIABLES ║
╚════════════════════════════════════════════════════════╝

These text variables return information on, or manipulate the basic   > v2.A4
RIPscrip environment.                                                 > v2.A4


┌──────────────────────────────────────────────────────────┐
│ 5.10.1 ■ $BASEMATH$ ... Set/query base math for RIPscrip │
└──────────────────────────────────────────────────────────┘

Format:  $BASEMATH(env_no, setting)$
Syntax:  $BASEMATH(opt:ENV_NO, opt:SETTING)$                          > v2.A4
                       ──────      ───────                            > v2.A4
                       CUR         36                                 > v2.A4
                       0-35        64                                 > v2.A4
                       ──────      ───────                            > v2.A4
                   def=CUR     def=36                                 > v2.A4

This command allows you to set or query the setting of the RIPscrip   > v2.A4
Base Math configuration.  Valid base math settings are 36 (MegaNums)  > v2.A4
or 64 (UltraNums).                                                    > v2.A4

If you specify no parameters, then the base math of the current       > v2.A4
environment is returned ("36" or "64").                               > v2.A4

If you specify one parameter, then you are querying the base math     > v2.A4
of a specific environment.  You must specify the environment as a     > v2.A4
number from 0-35, or the value "CUR" to indicate the current          > v2.A4
environment.  If the environment isn't in use, then a value of "NONE" > v2.A4
is returned.                                                          > v2.A4

If you specify two parameters, then the first parameter must indicate > v2.A4
which environment you're about to set (see above), and the second     > v2.A4
parameter must be the value "36" or "64".  If the environment isn't   > v2.A4
in use then a syntax error is generated.  When setting the base math, > v2.A4
you are accomplishing the same thing as if you had used the           > v2.A4
RIP_SET_BASE_MATH command.                                            > v2.A4

     Example:  $BASEMATH(CUR, 36)$                                    > v2.A4
     Returns:  nothing                                                > v2.A4


┌─────────────────────────────────────────────────────────────────────┐
│ 5.10.2 ■ $CLS$ ... Clears the screen to background color (no reset) │
└─────────────────────────────────────────────────────────────────────┘

Format:  $CLS$
Syntax:  $CLS$                                                        > v2.A4

This command physically erases the entire screen to the current       > v2.A1
background color (color #0).  No resetting of anything is performed.  > v2.A1
All this does is simply clear the screen.                             > v2.A1

     Example:  $CLS$                                                  > v2.A1
     Returns:  nothing                                                > v2.A1



┌─────────────────────────────────────────────────────┐
│ 5.10.3 ■ $COLORMODE$ ... Query/alter the color mode │
└─────────────────────────────────────────────────────┘

Format:  $COLORMODE(env_no, mode, bits)$
Syntax:  $COLORMODE(opt:ENV_NO, opt:MODE, opt:BITS)$                  > v2.A4
                        ──────      ────      ────                    > v2.A4
                        CUR         PAL       1-8:MODE=RGB            > v2.A4
                        0-35        RGB                               > v2.A4
                        ──────      ────      ────                    > v2.A4
                    def=CUR     def=PAL   def=<none>                  > v2.A4

If this variable has no parameters, then it queries the color mode    > v2.A4
of the current environment.  It responds with a number that indicates > v2.A4
whether or not the terminal is in direct RGB encoding mode or if it   > v2.A4
is in color palette mapping mode.  If the value is 0, then it is      > v2.A4
palette mapping mode.  If it a value from 1-8, then it is in direct   > v2.A4
RGB encoding mode and the value indicates how many bits of precision  > v2.A4
are used for the red, green and blue color components separately in   > v2.A4
RGB encoded data (a value of 8 indicates that 3x8 bits are used, or   > v2.A4
that we will be working with 24-bit color numbers).                   > v2.A4

If only one parameter is supplied, then it must be the environment    > v2.A4
number to query (0-35), or the value CUR to query the current         > v2.A4
environment.  In either case, if the environment is in use, then the  > v2.A4
value returned is the same as if there were no parameters, based on   > v2.A4
the settings of that particular environment.  If that environment     > v2.A4
isn't in use, then a value of "-1" is returned.                       > v2.A4

If you supply two or more parameters, then you are indicating that    > v2.A4
you wish to change the color mode setting.  To set the color mode to  > v2.A4
color palette mapping mode, supply the <mode> parameter as the        > v2.A4
value "PAL".  No other parameters are needed in this case.  To set    > v2.A4
RGB encoding mode, specify the <mode> keyword of "RGB" and then you   > v2.A4
must supply a third parameter which indicates the number of bits of   > v2.A4
precision from 1-8 (see above).  If the specified environment isn't   > v2.A4
in use, then a syntax error will be generated.                        > v2.A4

     Example:  $COLORMODE$                                            > v2.A1
     Returns:  0 ... Request setting of current environment color     > v2.A4
               mode.  In this example, that one's in palette mode.

     Example:  $COLORMODE(CUR, PAL)$                                  > v2.A4
     Returns:  nothing ... Switch current environment to palette mode > v2.A4

     Example:  $COLORMODE(5, RGB, 8)$                                 > v2.A4
     Returns:  nothing ... Enabled direct RGB color mode (bits=8)     > v2.A4
               in environment #5                                      > v2.A4

     Example:  $COLORMODE(6)$                                         > v2.A4
     Returns:  NONE ... Returned if environment #6 isn't in use.      > v2.A4



┌──────────────────────────────────────────────────────────────────────┐
│ 5.10.4 ■ $COLORS$ ... Total number of colors of current video device │
└──────────────────────────────────────────────────────────────────────┘

Format:  $COLORS$
Syntax:  $COLORS$                                                     > v2.A4

This variable returns the total number of colors available on the     > v2.A1
destination video hardware device.  Typical results are 2, 16, 256,   > v2.A1
32768, 65536 and 16,777,216 (24 bit color).  These aren't the         > v2.A1
only possible values, but are typical ones.                           > v2.A1

     Example:  $COLORS$                                               > v2.A1
     Returns:  256                                                    > v2.A1


┌──────────────────────────────────────────────────────────────────┐
│ 5.10.5 ■ $COMPAT$ ... Sets environment to RIPscrip 1.54 settings │
└──────────────────────────────────────────────────────────────────┘

Format:  $COMPAT(env_no)$
Syntax:  $COMPAT(opt:ENV_NO)$                                         > v2.A4
                     ──────                                           > v2.A4
                     CUR                                              > v2.A4
                     0-35                                             > v2.A4
                     ──────                                           > v2.A4
                 def=CUR                                              > v2.A4

This text variable is designed to set an environment to older         > v2.A4
RIPscrip 1.54 settings for "backward compatibility".  If no           > v2.A4
parameters are specified, then the current environment will be        > v2.A4
modified to these settings.                                           > v2.A4

If you specify a parameter, then you can only set one and it must be  > v2.A4
an environment number 0-35, or the value "CUR" for the current        > v2.A4
environment.  If the destination environment isn't in use, then a     > v2.A4
syntax error will be generated.                                       > v2.A4
The following environment settigns are altered:                       > v2.A4

     ■ World Coordinate Frame is set to 640x350                       > v2.A4

     ■ Color mode is set to color palette mapping mode                > v2.A4

     ■ Coordinate sizes are set to 2 bytes                            > v2.A4

     ■ Base math is set to base-36 numbers (MegaNums)                 > v2.A4

     ■ Baud rate emualtion is set to full speed (0)                   > v2.A4

     Example:  $COMPAT(5)$                                            > v2.A4
     Returns:  nothing                                                > v2.A4



┌───────────────────────────────────────────────────────────┐
│ 5.10.6 ■ $COORDSIZE$ ... Set byte-size of X/Y coordinates │
└───────────────────────────────────────────────────────────┘

Format:  $COORDSIZE(env_no, size)$
Syntax:  $COORDSIZE(opt:ENV_NO, opt:SIZE)$                            > v2.A4
                        ──────      ────                              > v2.A4
                        CUR         2-5                               > v2.A4
                        0-35        ────                              > v2.A4
                        ──────  def=2                                 > v2.A4
                    def=CUR                                           > v2.A4

This command sets or queries the setting of the byte-width of         > v2.A4
RIPscrip coordinate parameters in raw RIPscrip code.  If no           > v2.A4
parameters are specified, then this command returns the setting       > v2.A4
of the coordinate size in the current environment.  The valid         > v2.A4
return values are "2" through "5".                                    > v2.A4

If you specify only one parameter, then it must be an environment     > v2.A4
number from 0-35, or it must be "CUR" to indicate the current         > v2.A4
environment.  If the environment isn't in use when querying it's      > v2.A4
coordinate size, then the value "-1" is returned.                     > v2.A4

If you intend to set the environment's coordinate size, then you      > v2.A4
must specify two parameters.  The first one is the environment        > v2.A4
number (see above), and the second one must be the coordinate size    > v2.A4
itself (2, 3, 4 or 5).  If you specify an environment that isn't      > v2.A4
in use, or an invalid coordinate size value then a syntax error is    > v2.A4
generated.                                                            > v2.A4

     Example:  $COORDSIZE(CUR, 2)$                                    > v2.A4
     Returns:  nothing                                                > v2.A4

     Example:  $COORDSIZE(5)$                                         > v2.A4
     Returns:  2                                                      > v2.A4


┌───────────────────────────────────────────────────────────────────┐
│ 5.10.7 ■ $ISPALETTE$ ... Reports if a color palette exists or not │
└───────────────────────────────────────────────────────────────────┘

Format:  $ISPALETTE$
Syntax:  $ISPALETTE$                                                  > v2.A4

If the destination terminal is operating with a video device that has > v2.A1
an actual color palette then this variable returns "1".  If           > v2.A4
however, the terminal is running on a device that's in 24-bit color   > v2.A1
mode where there is no color palette then this variable returns "0".  > v2.A4

     Example:  $ISPALETTE$                                            > v2.A1
     Returns:  1                                                      > v2.A4



┌──────────────────────────────────────────────────────────────┐
│ 5.10.8 ■ $RBS$ ... Restore a button style from a backup area │
└──────────────────────────────────────────────────────────────┘

Format:  $RBS(source)$
Syntax:  $RBS(opt:SOURCE)$                                            > v2.A4
                  ──────                                              > v2.A4
                  BASE                                                > v2.A4
                  0-9                                                 > v2.A4
                  POP                                                 > v2.A4
                  ──────                                              > v2.A4
              def=BASE                                                > v2.A4

This text variable restores the button style data table from a data   > v2.A4
backup area.  If the SOURCE parameter is omitted, then it is          > v2.A4
restored from the BASE save area of the backup data area.  Possible   > v2.A4
sources are "BASE" to restore from the base save area, the value      > v2.A4
0-9 to read from a specific data save slot, or the value "POP" to     > v2.A4
indicate that you wish to pop the color palette data table from the   > v2.A4
button style data backup area's save stack.                           > v2.A4

     Example:  $RBS(POP)$                                             > v2.A4
     Returns:  nothing                                                > v2.A4


┌───────────────────────────────────────────────────────────────┐
│ 5.10.9 ■ $RCP$ ... Restore a color palette from a backup area │
└───────────────────────────────────────────────────────────────┘

Format:  $RCP(source)$
Syntax:  $RCP(opt:SOURCE)$                                            > v2.A4
                  ───────────                                         > v2.A4
                  BASE                                                > v2.A4
                  0-9                                                 > v2.A4
                  POP                                                 > v2.A4
                  ───────────                                         > v2.A4
              def=BASE                                                > v2.A4

This text variable restores the color palette data table from a data  > v2.A4
backup area.  If the SOURCE parameter is omitted, then it is          > v2.A4
restored from the BASE save area of the backup data area.  Possible   > v2.A4
sources are "BASE" to restore from the base save area, the value      > v2.A4
0-9 to read from a specific data save slot, or the value "POP" to     > v2.A4
indicate that you wish to pop the color palette data table from the   > v2.A4
color palette data backup area's save stack.                          > v2.A4

     Example:  $RCP(POP)$                                             > v2.A4
     Returns:  nothing                                                > v2.A4



┌─────────────────────────────────────────────────────────────────────┐
│ 5.10.10 ■ $RENV$ ... Activates a previously snapshotted environment │
└─────────────────────────────────────────────────────────────────────┘

Format:  $RENV(source)$
Syntax:  $RENV(opt:SOURCE)$                                           > v2.A4
                   ──────                                             > v2.A4
                   BASE                                               > v2.A4
                   POP                                                > v2.A4
                   0-9                                                > v2.A4
                   ──────                                             > v2.A4
               def=BASE                                               > v2.A4

This command restores a previously saved environment data table back  > v2.A4
into the actual data table and puts it to use.  If you omit the slot  > v2.A4
parameter, then the environment is restored from the base save area   > v2.A4
of the environment data backup area.                                  > v2.A4

If the slot value is set to "POP", then the data table is popped off  > v2.A4
of the environment data backup area's stack.                          > v2.A4

If the slot value is set to "BASE", then the data table is restored   > v2.A4
from the base save area of the environment data backup area.          > v2.A4

If the slot value is set to a number from 0-9, then the environment   > v2.A4
data table is restored from a data save slot number in the            > v2.A4
environment data backup area.                                         > v2.A4

     Example:  $RENV(POP)$                                            > v2.A4
     Returns:  nothing                                                > v2.A4


┌──────────────────────────────────────────────────────────┐
│ 5.10.11 ■ $RESTOREALL$ ... Restore all screen attributes │
└──────────────────────────────────────────────────────────┘

Format:  $RESTOREALL(source)$
Syntax:  $RESTOREALL(opt:SOURCE)$                                     > v2.A4
                         ──────                                       > v2.A4
                         BASE                                         > v2.A4
                         POP                                          > v2.A4
                         0-9                                          > v2.A4
                         ──────                                       > v2.A4
                     def=BASE                                         > v2.A4

This Active Text Variable restores the Text Windows coordinates,      > v2.A4
restores the contents of the clipboard, restores all mouse fields,    > v2.A4
and restores the contents of the screen.  It is equal to the          > v2.A4
following operations (in this order):                                 > v2.A4

                    $RTW(slot)$                                       > v2.A4
                    $RCB(slot)$                                       > v2.A4
                    $RMF(slot)$                                       > v2.A4
                    $RGS(slot)$                                       > v2.A4
                    $RBS(slot)$                                       > v2.A4
                    $RESTORE(slot)$                                   > v2.A4
                    $RCP(slot)$                                       > v2.A4
                    $RENV(slot)$                                      > v2.A4


This command does not require any parameters.  If none are specified  > v2.A1
then the restore is slot-less and can be restored many times.  The    > v2.A1
ability to specify a slot gives you the ability to have restore one   > v2.A1
of many screen configurations.  You are allowed up to ten separate    > v2.A1
slots (0-9).                                                          > v2.A1

In place of a slot number, you can provide a parameter of "POP" to    > v2.A1
perform a stack-based pop operation to restore the last pushed        > v2.A1
SAVEALL (eg, $RESTOREALL(POP)$).                                      > v2.A1

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


┌────────────────────────────────────────────────────────────────────┐
│ 5.10.12 ■ $RESX$ ... Horizontal resolution of current video device │
└────────────────────────────────────────────────────────────────────┘

Format:  $RESX$
Syntax:  $RESX$                                                       > v2.A4

This variable returns the horizontal resolution of the video device   > v2.A1
in pixels.  Typical results for this might be 640, 800, 1024 or 1280. > v2.A1
But this might be different depending on the various possible video   > v2.A1
devices in existance.                                                 > v2.A1

     Example:  $RESX$                                                 > v2.A1
     Returns:  640                                                    > v2.A1


┌──────────────────────────────────────────────────────────────────┐
│ 5.10.13 ■ $RESY$ ... Vertical resolution of current video device │
└──────────────────────────────────────────────────────────────────┘

Format:  $RESY$
Syntax:  $RESY$                                                       > v2.A4

This variable returns the vertical resolution of the video device     > v2.A1
in scan lines.  Typical results for this might be 350, 480, 600,      > v2.A1
768 or 1024.  But this might be different depending on the various    > v2.A1
possible video devices in existance.                                  > v2.A1

     Example:  $RESY$                                                 > v2.A1
     Returns:  768                                                    > v2.A1


┌─────────────────────────────────────────────────────────────────┐
│ 5.10.14 ■ $RGS$ ... Restore a graphics style from a backup area │
└─────────────────────────────────────────────────────────────────┘

Format:  $RGS(source)$
Syntax:  $RGS(opt:SOURCE)$                                            > v2.A4
                  ──────                                              > v2.A4
                  BASE                                                > v2.A4
                  0-9                                                 > v2.A4
                  POP                                                 > v2.A4
                  ──────                                              > v2.A4
              def=BASE                                                > v2.A4


This text variable restores the graphics style data table from a data > v2.A4
backup area.  If the SOURCE parameter is omitted, then it is          > v2.A4
restored from the BASE save area of the backup data area.  Possible   > v2.A4
sources are "BASE" to restore from the base save area, the value      > v2.A4
0-9 to read from a specific data save slot, or the value "POP" to     > v2.A4
indicate that you wish to pop the color palette data table from the   > v2.A4
graphics style data backup area's save stack.                         > v2.A4

     Example:  $RGS(POP)$                                             > v2.A4
     Returns:  nothing                                                > v2.A4


┌───────────────────────────────────────────────────────┐
│ 5.10.15 ■ $PALENTRY$ ... Return RGB values of palette │
└───────────────────────────────────────────────────────┘

Format:  $PALENTRY(palno,start,stop)$
Syntax:  $PALENTRY(req:PALNO, req:START, opt:STOP)$                   > v2.A4
                       ─────      ─────      ────                     > v2.A4
                       CUR        0-255      START-255:START<>ALL     > v2.A4
                       0-35       ALL        ────                     > v2.A4
                                         def=START                    > v2.A4

This variable returns one or more RGB values stored in one of the     > v2.A4
drawing color palettes.  The <pal> parameter determines which palette > v2.A4
in the palette data table is to be inquired about, and its value can  > v2.A4
be from 0-35 to explicitly reference a specific color palette number, > v2.A4
or it can be CUR to indicate the current color palette.               > v2.A4

The <start> parameter must be specified, and indicates which palette  > v2.A4
entry in the palette is to be inquired about.  If the <stop>          > v2.A4
parameter is omitted, then only one entry will be queried, the        > v2.A4
<start> entry.  If <stop> is supplied, then it must be equal to or    > v2.A4
greater than <start> (not to exceed 255).  So if <start> is 5 and     > v2.A4
<stop> is 7 then three palette entries will be inquired about,        > v2.A4
starting with entry #5.                                               > v2.A4

If the palette isn't in use at all, then this variable returns the    > v2.A4
value "-1" to the host.  If it is in use, then the string will be     > v2.A4
a formatted block of text.  The format of the return string to the    > v2.A4
host is:                                                              > v2.A4

     <bits> ; <pal-entry> [, <pal-entry> ...]                         > v2.A4

The <bits> field is the total number of bits of precision for the     > v2.A4
red, green or blue fields.  If the <bits> is 8, then red values can   > v2.A4
range from 0-255, etc.  The <pal-entry> is a segmented response       > v2.A4
in the format:                                                        > v2.A4

     red:green:blue                                                   > v2.A4

where each of red, green and blue are decimal numbers from 0 up to    > v2.A4
the total number of values allowed based on the <bits> parameter.     > v2.A4

If more than one palette entry is requested, then eacch <pal-entry>   > v2.A4
field will be separated by a comma delimiter (,) as in the following  > v2.A4
example:                                                              > v2.A4



     Example:  $PALENTRY(CUR, 5, 7);                                  > v2.A4
     Returns:  6;42:0:42,42:21:0,42:42:42                             > v2.A4

Notice how the <bits> is specified as "6;".  RIPterm maintains its    > v2.A4
own internal palette with 6 bits of precision - this isn't the only   > v2.A4
way to do it, its just the way RIPterm does it currently.  With 6     > v2.A4
bits of precision, each red, green or blue component will never       > v2.A4
exceed 2 bytes of data (8 bits could occupy 3 bytes).                 > v2.A4

     Example: $PALENTRY(CUR, 15)$                                     > v2.A4
     Returns: 8;255:255:255                                           > v2.A4

Lastly, the <start> parameter could be specified as "ALL".  If this   > v2.A4
parameter is present, then <stop> isn't required.  If ALL is          > v2.A4
specified, then all palette entries from 0-255 are returned as in     > v2.A4
the the following:                                                    > v2.A4

     Example: $PALENTRY(CUR, ALL)$                                    > v2.A4
     Returns: 6;0:0:0,0:0:42, ... 63:63:42,63:63:63                   > v2.A4


┌────────────────────────────────────────────────────┐
│ 5.10.16 ■ $SAVEALL$ ... Save all screen attributes │
└────────────────────────────────────────────────────┘

Format:  $SAVEALL(destination)$
Syntax:  $SAVEALL(opt:DESTINATION)$                                   > v2.A4
                      ───────────                                     > v2.A4
                      BASE                                            > v2.A4
                      PUSH                                            > v2.A4
                      0-9                                             > v2.A4
                      ───────────                                     > v2.A4
                  def=BASE                                            > v2.A4

This Active Text Variable saves the Text Window coordinates, the      > v2.A2
contents of the entire clipboard, all mouse fields, and the contents  > v2.A4
of the entire screen.  It is the same as performing the following     > v2.A4
operations (in this order):                                           > v2.A4

                    $STW(slot)$                                       > v2.A4
                    $SCB(slot)$                                       > v2.A4
                    $SMF(slot)$                                       > v2.A4
                    $SGS(slot)$                                       > v2.A4
                    $SBS(slot)$                                       > v2.A4
                    $SAVE(slot)$                                      > v2.A4
                    $SCP(slot)$                                       > v2.A4
                    $SENV(slot)$                                      > v2.A4

This command does not require any parameters.  If none are specified  > v2.A1
then the saved information is slot-less and can be restored many      > v2.A1
times.  If you specify a slot number then that slot number is the     > v2.A2
slot that will be saved over.  You are allowed up to ten separate     > v2.A1
slots (0-9).                                                          > v2.A1

In place of a slot number, you can provide a parameter of "PUSH" to   > v2.A1
perform a push-type stack saving operation (eg, $SAVEALL(PUSH)$).     > v2.A1

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


┌────────────────────────────────────────────────────────────┐
│ 5.10.17 ■ $SBS$ ... Save a button style to the backup area │
└────────────────────────────────────────────────────────────┘

Format:  $SBS(destination)$
Syntax:  $SBS(opt:DESTINATION)$                                       > v2.A4
                  ───────────                                         > v2.A4
                  BASE                                                > v2.A4
                  0-9                                                 > v2.A4
                  PUSH                                                > v2.A4
                  ───────────                                         > v2.A4
              def=BASE                                                > v2.A4

This text variable saves the button style data table to a data        > v2.A4
backup area.  If the DESTINATION parameter is omitted, then it is     > v2.A4
saved to the BASE save area of the backup data area.  Possible        > v2.A4
destinations are "BASE" to save over the base save area, the value    > v2.A4
0-9 to overwrite a specific data save slot, or the value "PUSH" to    > v2.A4
indicate that you wish to push the color palette data table onto the  > v2.A4
button style data backup area's save stack.                           > v2.A4

     Example:  $SBS(PUSH)$                                            > v2.A4
     Returns:  nothing                                                > v2.A4


┌─────────────────────────────────────────────────────────────┐
│ 5.10.18 ■ $SCP$ ... Save a color palette to the backup area │
└─────────────────────────────────────────────────────────────┘

Format:  $SCP(destination)$
Syntax:  $SCP(opt:DESTINATION)$                                       > v2.A4
                  ───────────                                         > v2.A4
                  BASE                                                > v2.A4
                  0-9                                                 > v2.A4
                  PUSH                                                > v2.A4
                  ───────────                                         > v2.A4
              def=BASE                                                > v2.A4

This text variable saves the color palette data table to a data       > v2.A4
backup area.  If the DESTINATION parameter is omitted, then it is     > v2.A4
saved to the BASE save area of the backup data area.  Possible        > v2.A4
destinations are "BASE" to save over the base save area, the value    > v2.A4
0-9 to overwrite a specific data save slot, or the value "PUSH" to    > v2.A4
indicate that you wish to push the color palette data table onto the  > v2.A4
color palette data backup area's save stack.                          > v2.A4

     Example:  $SCP(PUSH)$                                            > v2.A4
     Returns:  nothing                                                > v2.A4



┌──────────────────────────────────────────────────────────┐
│ 5.10.19 ■ $SENV$ ... Records environmental configuration │
└──────────────────────────────────────────────────────────┘

Format:  $SENV(destination)$
Syntax:  $SENV(opt:DESTINATION)$                                      > v2.A4
                   ───────────                                        > v2.A4
                   BASE                                               > v2.A4
                   PUSH                                               > v2.A4
                   0-9
                   ──────────                                         > v2.A4
               def=BASE                                               > v2.A4

This command takes a snapshot of the RIPscrip configuration over the  > v2.A4
one of the data backup area's particular save regions.  This includes > v2.A4
recording the values of:                                              > v2.A4

     ■ Current graphics style entry number                            > v2.A4
     ■ Current button style entry number                              > v2.A4
     ■ Current drawing port entry number                              > v2.A4
     ■ Current text window entry number                               > v2.A4
     ■ Current color palette entry number                             > v2.A4
     ■ Current World coordinate dimensions (X and Y)                  > v2.A4
     ■ Current base math settings (36 or 64)                          > v2.A4
     ■ Current coordinate size (2 through 5)                          > v2.A4
     ■ Current color mode (color palette mode or direct RGB mode)     > v2.A4
     ■ Current mouse pointer number                                   > v2.A4
     ■ Current baud rate emulation value                              > v2.A4
     ■ Current environment data table entry currently active          > v2.A4

This command saves an environment data table over an actual data      > v2.A4
backup area for later retrieval.  If you omit the slot parameter,     > v2.A4
then the environment is stored into the base save area of the         > v2.A4
environment data backup area.                                         > v2.A4

If the slot value is set to "PUSH", then the data table is pushed     > v2.A4
onto the environment data backup area's stack.                        > v2.A4

If the slot value is set to "BASE", then the data table is stored     > v2.A4
into the base save area of the environment data backup area.          > v2.A4

If the slot value is set to a number from 0-9, then the environment   > v2.A4
data table is stored into a data save slot number in the environment  > v2.A4
data backup area.                                                     > v2.A4

     Example:  $SENV(PUSH)$                                           > v2.A4
     Returns:  nothing                                                > v2.A4



┌──────────────────────────────────────────────────────────────┐
│ 5.10.20 ■ $SGS$ ... Save a graphics style to the backup area │
└──────────────────────────────────────────────────────────────┘

Format:  $SGS(destination)$
Syntax:  $SGS(opt:DESTINATION)$                                       > v2.A4
                  ───────────                                         > v2.A4
                  BASE                                                > v2.A4
                  0-9                                                 > v2.A4
                  PUSH                                                > v2.A4
                  ───────────                                         > v2.A4
              def=BASE                                                > v2.A4

This text variable saves the graphics style data table to a data      > v2.A4
backup area.  If the DESTINATION parameter is omitted, then it is     > v2.A4
saved to the BASE save area of the backup data area.  Possible        > v2.A4
destinations are "BASE" to save over the base save area, the value    > v2.A4
0-9 to overwrite a specific data save slot, or the value "PUSH" to    > v2.A4
indicate that you wish to push the color palette data table onto the  > v2.A4
graphics style data backup area's save stack.                         > v2.A4

     Example:  $SGS(PUSH)$                                            > v2.A4
     Returns:  nothing                                                > v2.A4


┌────────────────────────────────────────────────────────┐
│ 5.10.21 ■ $WORLD$ ... Set/query World coordinate frame │
└────────────────────────────────────────────────────────┘

Format:  $WORLD(env_no,width,height)$
Syntax:  $WORLD(opt:ENV_NO, opt:WIDTH,  opt:HEIGHT)$                  > v2.A4
                    ──────      ─────       ──────                    > v2.A4
                    CUR         1-65535     1-65535                   > v2.A4
                    0-35        DEFAULT     DEFAULT                   > v2.A4
                    ──────      ─────       ──────                    > v2.A4
                def=CUR     def=<none>  def=<none>                    > v2.A4

This command allows you to set or query an environment's world        > v2.A4
coordinate frame.                                                     > v2.A4

If you specify no parameters, then you are querying the contents of   > v2.A4
the current environment's world coordinate frame.  The return value   > v2.A4
to the host will be a value similar to the following "1234:5678"      > v2.A4
where "1234" is the width of the coordinate frame in the horizontal   > v2.A4
X direction, and the value "5678" is the height of the coordinate     > v2.A4
frame in the vertical Y direction.                                    > v2.A4

If you specify one parameter, then you are querying the world         > v2.A4
coordinate frame of a specific environment from 0-35 or "CUR" for the > v2.A4
the current environment.  The result returned to the host is in the   > v2.A4
same format as if you specified no parameters (see above).  If the    > v2.A4
requested environment isn't in use, then the value "-1" is            > v2.A4
returned.                                                             > v2.A4

If you wish to set the world coordinate frame for an environment,     > v2.A4
you have two choices.  You can set it to some basic set of default    > v2.A4
values or you can set it to a specific height and width.              > v2.A4



If you wish to set the world coordinate frame to a set of default     > v2.A4
values then you specify two parameters - the environment number (0-35 > v2.A4
or CUR), and the second parameter must be the value "DEFAULT".  The   > v2.A4
default width and height values will depend on that environment's     > v2.A4
Base Math setting.  If MegaNums are in use in that environment, then  > v2.A4
the world frame is set to 1280x960.  If it is UltraNums, it is set to > v2.A4
4096x3072.                                                            > v2.A4

If you wish to manually set the width and height of the world         > v2.A4
coordinate frame, then you must specify all three parameters.  The    > v2.A4
first one is the environment (0-35 or CUR).  The second parameter is  > v2.A4
the width of the world coordinate frame and the third and final       > v2.A4
parameter is the height of the coordinate frame.  Both of these       > v2.A4
values can not exceed the value 65535.  If the specified environment  > v2.A4
isn't in use, then a syntax error is generated.  This variation of    > v2.A4
$WORLD is the same as using the RIP_SET_WORLD_FRAME RIPscrip          > v2.A4
command.                                                              > v2.A4

     Example:  $WORLD(CUR,1000,1000)$                                 > v2.A4
     Returns:  nothing ... Sets current environment world frame to    > v2.A4
                           1000x1000                                  > v2.A4

     Example:  $WORLD(5, DEFAULT)$                                    > v2.A4
     Returns:  nothing ... Sets environment 5's world frame to        > v2.A4
                           1280x960 if MegaNums, or 4096x3072 if      > v2.A4
                           it's in UltraNum mode.                     > v2.A4

     Example:  $WORLD(CUR)$                                           > v2.A4
     Returns:  640:350 ... Returns world frame of current environment > v2.A4


┌──────────────────────────────────────────────────────────────┐
│ 5.10.22 ■ $WORLDH$ ... Vert resolution of world coord system │
└──────────────────────────────────────────────────────────────┘

Format:  $WORLDH(env_no,height)$
Syntax:  $WORLDW(opt:ENV_NO, opt:HEIGHT)$                             > v2.A4
                     ──────      ─────                                > v2.A4
                     CUR         1-65535                              > v2.A4
                     0-35        ─────                                > v2.A4
                     ──────  def=<none>                               > v2.A4
                 def=CUR                                              > v2.A4

This function is used to either set or query the setting of the       > v2.A4
world coordinate system in the Y direction.  If no parameters are     > v2.A4
specified (eg, $WORLDY$) or a single "CUR" parameter is specified,    > v2.A4
then the current environment's world coordinate Y dimension is        > v2.A4
returned to the host.  If you would like to inquire about a specific  > v2.A4
environment's world Y setting, specify the environment table entry    > v2.A4
number as the only parameters (eg, $WORLDY(5)$ inquires about         > v2.A4
environment #5's world coordinate Y setting).                         > v2.A4

If you would like to alter the world coordinate system's Y setting,   > v2.A4
you need to specify two parameters.  The first parameter must be      > v2.A4
a table entry from 0-35 or the value CUR for the current environment. > v2.A4
The second parameter must be a world coordinate setting to set the    > v2.A4
Y dimension to.                                                       > v2.A4



Note, if you try to a value in an environment that is not in use,     > v2.A4
this command generates a syntax error.  If you attempt to query a     > v2.A4
value from an environment that is not in use, the value "-1" is       > v2.A4
returned to the host.                                                 > v2.A4

     Example:  $WORLDH$                                               > v2.A1
     Returns:  4096                                                   > v2.A1

     Example:  $WORLDH(CUR, 1000)$                                    > v2.A4
     Returns:  nothing                                                > v2.A4


┌───────────────────────────────────────────────────────────────┐
│ 5.10.23 ■ $WORLDW$ ... Horiz resolution of world coord system │
└───────────────────────────────────────────────────────────────┘

Format:  $WORLDW$(env_no,width)
Syntax:  $WORLDW(opt:ENV_NO, opt:WIDTH)$                              > v2.A4
                     ──────      ─────                                > v2.A4
                     CUR         1-65535                              > v2.A4
                     0-35        -----                                > v2.A4
                     ──────  def=<none>                               > v2.A4
                 def=CUR                                              > v2.A4

This function is used to either set or query the setting of the       > v2.A4
world coordinate system in the X direction.  If no parameters are     > v2.A4
specified (eg, $WORLDX$) or a single "CUR" parameter is specified,    > v2.A4
then the current environment's world coordinate X dimension is        > v2.A4
returned to the host.  If you would like to inquire about a specific  > v2.A4
environment's world X setting, specify the environment table entry    > v2.A4
number as the only parameters (eg, $WORLDX(5)$ inquires about         > v2.A4
environment #5's world coordinate X setting).                         > v2.A4

If you would like to alter the world coordinate system's X setting,   > v2.A4
you need to specify two parameters.  The first parameter must be      > v2.A4
a table entry from 0-35 or the value CUR for the current environment. > v2.A4
The second parameter must be a world coordinate setting to set the    > v2.A4
X dimension to.                                                       > v2.A4

Note, if you try to a value in an environment that is not in use,     > v2.A4
this command generates a syntax error.  If you attempt to query a     > v2.A4
value from an environment that is not in use, the value "-1" is       > v2.A4
returned to the host.                                                 > v2.A4

     Example:  $WORLDW$                                               > v2.A1
     Returns:  4096                                                   > v2.A1

     Example:  $WORLDW(CUR, 1000)$                                    > v2.A4
     Returns:  nothing                                                > v2.A4



╔═════════════════════════════════════════╗
║ 5.11 ■ CLIPBOARD RELATED TEXT VARIABLES ║
╚═════════════════════════════════════════╝

These text variables return information on, or manipulate the         > v2.A4
clipboard aspects of the port system.                                 > v2.A4


┌─────────────────────────────────────────────────────┐
│ 5.11.1 ■ $PCB$ ... Paste Clipboard at last location │
└─────────────────────────────────────────────────────┘

Format:  $PCB(portno)$
Syntax:  $PCB(opt:PORTNO)$                                            > v2.A4
                  ──────                                              > v2.A4
                  CUR                                                 > v2.A4
                  0-35                                                > v2.A4
                  ──────                                              > v2.A4
              def=CUR                                                 > v2.A4

This text variable copies a portion of the specified port onto the    > v2.A4
current drawing port (these ports may be the same).  The area on the  > v2.A4
specified port that is considered to be the source is "remembered"    > v2.A4
from the last rectangle of data that was put on this port.  What this > v2.A4
means is when you perform a RIP_PORT_COPY command, you copy a         > v2.A4
rectangle of data from one port to another.  The two rectangles of    > v2.A4
information are stored in the destination port of the copy operation. > v2.A4
If the original port were port 0 and the destination port were port   > v2.A4
5, then both rectangles of data are stored in port 5's definition.    > v2.A4
If you switch to port #0 and then perform a $PCB(5)$ operation, then  > v2.A4
the rectangle of data on port #5 is copied back to its original       > v2.A4
location in the current port.                                         > v2.A4

This variable is extremely useful for restoring graphics that were    > v2.A4
previously saved to an offscreen port.  It is typically used in       > v2.A4
dialog boxes when the user clicks on the "OK" button, where the       > v2.A4
dialog box should be erased and the original graphical screen would   > v2.A4
be restored.                                                          > v2.A4

If no parameters are specified, then the port that will be pasted     > v2.A4
from will be whatever port is associated with the clipboard pointer.  > v2.A4
See the RIP_GET_IMAGE command for more details on the clipboard       > v2.A4
pointer.                                                              > v2.A4

If you do specify a parameter, then it can be "CUR" to indicate the   > v2.A4
current port, or a value 0-35 to specify a specific port number to    > v2.A4
retrieve the data from.  Note that if the specified port doesn't      > v2.A4
exist, or if either the current port or the specified port are        > v2.A4
"deactivated", then this command is ignored.                          > v2.A4

It should be noted that the rectangles of information stored in the   > v2.A4
specified port are "viewport relative".  What this means is that the  > v2.A4
coordinates in those rectangles are based on viewports.  If you copy  > v2.A4
data from say port 0 to port 5, then change port 0's viewport before  > v2.A4
you perform a $PCB(5)$ operation, then when you actually perform the  > v2.A4
$PCB(5)$ command, the data will be pasted in a new location on the    > v2.A4
screen - not where it came from.  If you're going to be using this    > v2.A4
command, be careful how you manipulate your viewports.                > v2.A4


     Example:  $PCB(5)$ ... Paste port 5's data to the current port   > v2.A4
     Returns:  nothing                                                > v2.A4


┌──────────────────────────────────────┐
│ 5.11.2 ■ $RCB$ ... Restore Clipboard │
└──────────────────────────────────────┘

Format:  $RCB$(source)
Syntax:  $RCB(opt:SOURCE)$                                            > v2.A4
                  ──────                                              > v2.A4
                  BASE                                                > v2.A4
                  POP                                                 > v2.A4
                  0-9                                                 > v2.A4
                  ──────                                              > v2.A4
              def=BASE                                                > v2.A4

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

If you do not specify a slot parameter then the clipboard is restored > v2.A1
from a slot-less file.  It is not deleted so you can do multiple      > v2.A1
identical clipboard restorations.                                     > v2.A1

If you do specify a slot parameter then you may restore the clipboard > v2.A1
from any of ten different clipboard slots (0-9).  Once restored, the  > v2.A1
clipboard slot file is deleted.                                       > v2.A1

You may specify a slot number of "POP" to perform a stack-based pop   > v2.A1
operation (eg, $RCB(POP)$).                                           > v2.A1

     Example:  $RCB(4)$
     Returns:  nothing


┌───────────────────────────────────┐
│ 5.11.3 ■ $SCB$ ... Save Clipboard │
└───────────────────────────────────┘

Format:  $SCB(destination)$
Syntax:  $SCB(opt:DESTINATION)$                                       > v2.A4
                  ───────────                                         > v2.A4
                  BASE                                                > v2.A4
                  PUSH                                                > v2.A4
                  0-9                                                 > v2.A4
                  ───────────                                         > v2.A4
              def=BASE                                                > v2.A4

This Active Text Variable saves the Clipboard to disk for later
retrieval by a Query or Host Command.  If the clipboard is empty, the
temporary file is deleted so Restore Clipboard knows there shouldn't
be a clipboard active.

If you do not specify a slot parameter then the clipboard is saved to > v2.A1
a slot-less file.  When it is restored the file is not deleted so you > v2.A1
can do multiple identical clipboard restorations.                     > v2.A1


If you do specify a slot parameter then you may save the clipboard to > v2.A1
one of ten different clipboard slots (0-9).  When you restore a       > v2.A1
clipboard slot, the clipboard file is deleted.                        > v2.A1

You may specify a slot number of "PUSH" to perform a stack-based push > v2.A1
operation (eg, $SCB(PUSH)$).                                          > v2.A1

     Example:  $SCB(4)$
     Returns:  nothing



╔═══════════════════════════════════════════╗
║ 5.12 ■ MOUSE FIELD RELATED TEXT VARIABLES ║
╚═══════════════════════════════════════════╝

These text variables return information on, or manipulate the mouse   > v2.A4
field data table.                                                     > v2.A4


┌────────────────────────────────────────┐
│ 5.12.1 ■ $MKILL$ ... Kill Mouse Fields │
└────────────────────────────────────────┘

Format:  $MKILL(x0,y0,x1,y1,inout)$
Syntax:  $MKILL(opt:X0, opt:Y0, opt:X1, opt:Y1, opt:INOUT)$           > v2.A4

                opt:X0        opt:Y0                                  > v2.A4
                    ──            ──                                  > v2.A4
                    0-65535       0-65535                             > v2.A4
                    ──            ──                                  > v2.A4
                def=<none>    def=<none>                              > v2.A4


                opt:X1        opt:Y1         opt:INOUT                > v2.A4
                    ──            ──             ─────                > v2.A4
                    0-65535       0-65535        IN                   > v2.A4
                    ──            ──             OUT                  > v2.A4
                def=<none>    def=<none>         ─────                > v2.A4
                                             def=IN                   > v2.A4

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

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

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



┌─────────────────────────────────────────┐
│ 5.12.2 ■ $RMF$ ... Restore Mouse Fields │
└─────────────────────────────────────────┘

Format:  $RMF(source)$
Syntax:  $RMF(opt:SOURCE)$                                            > v2.A4
                  ──────                                              > v2.A4
                  BASE                                                > v2.A4
                  POP                                                 > v2.A4
                  0-9                                                 > v2.A4
                  ──────                                              > v2.A4
              def=BASE                                                > v2.A4

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

If no slot parameter is specified, then the non-slot specific mouse   > v2.A1
fields saved with a $SMF$ command is restored (the saved mouse field  > v2.A1
file is not deleted).  If a slot parameter is specified then the      > v2.A1
mouse fields saved with $SMF(slot)$ is restored then the disk file is > v2.A1
deleted.                                                              > v2.A1

If you specify a slot number of "POP" then you will be performing a   > v2.A1
stack-based pop operation (eg, $RMF(POP)$).                           > v2.A1

If you specify "BASE" instead of a slot number then you will be       > v2.A4
restoring the mouse fields from the mouse field data backup area's    > v2.A4
base save area.                                                       > v2.A4

NOTE:  You may restore slot-less saved Mouse Fields more than once    > v2.A1
       is you wish.  In other words, if you do a $SMF$ command, you   > v2.A1
       may execute $RMF$ one or more times.  But if you do a $SMF(1)$ > v2.A1
       you may only do a $RMF(1)$ once.                               > v2.A1

     Example:  $RMF(4)$
     Returns:  nothing


┌──────────────────────────────────────┐
│ 5.12.3 ■ $SMF$ ... Save Mouse Fields │
└──────────────────────────────────────┘

Format:  $SMF(destination)$
Syntax:  $SMF(opt:DESTINATION)$                                       > v2.A4
                  ───────────                                         > v2.A4
                  BASE                                                > v2.A4
                  PUSH                                                > v2.A4
                  0-9                                                 > v2.A4
                  ───────────                                         > v2.A4
              def=BASE                                                > v2.A4

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


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

If you specify a slot number of "PUSH" then you will be performing a  > v2.A1
stack-based push operation (eg, $SMF(PUSH)$).                         > v2.A1

If you specify "BASE" instead of a slot number then you will be       > v2.A4
storing the mouse fields into the mouse field data backup area's      > v2.A4
base save area.                                                       > v2.A4

     Example:  $SMF(4)$
     Returns:  nothing



╔══════════════════════════════════════╗
║ 5.13 ■ SCREEN RELATED TEXT VARIABLES ║
╚══════════════════════════════════════╝

These text variables return information on, or manipulate the screen. > v2.A4


┌────────────────────────────────────────────────┐
│ 5.13.1 ■ $RESTORE$ ... Restore graphics screen │
└────────────────────────────────────────────────┘

Format:  $RESTORE(source)$
Syntax:  $RESTORE(opt:SOURCE)$                                        > v2.A4
                      ──────                                          > v2.A4
                      BASE                                            > v2.A4
                      POP                                             > v2.A4
                      0-9                                             > v2.A4
                      ──────                                          > v2.A4
                  def=BASE                                            > v2.A4

If no slot parameter is specified, then the graphical screen stored   > v2.A1
in the file RIPTERM.SAV will be restored to the screen (the file will > v2.A1
not be deleted).                                                      > v2.A1

If you specify a slot number (0-9), then the file restored to the     > v2.A1
screen will be RIPTERM0.SAV through RIPTERM9.SAV based on the slot    > v2.A1
number.  These files are deleted after restoration is complete.       > v2.A1

If you specify "POP" instead of a slot number then a stack-based pop  > v2.A1
operation will be performed (eg, $RESTORE(POP)$).                     > v2.A1

If you specify "BASE" instead of a slot number than the screen is     > v2.A4
restored from the screen data backup area's base save area.           > v2.A4

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

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

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

     Example:  $RESTORE(3)$
     Returns:  nothing


┌─────────────────────────────────────────────────────────┐
│ 5.13.2 ■ $RESTOREx$ ... Restore graphics screen (x=0-9) │
└─────────────────────────────────────────────────────────┘

Format:  $RESTORE0$ - $RESTORE9$
Syntax:  $RESTORE0$ ... $RESTORE9$                                    > v2.A4

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


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

To restore the entire context of the graphics environment             > v2.A4
$RESTOREALL$.                                                         > v2.A4

Also saved are the graphical style slots and button style slots.      > v2.A1

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

     Example:  $RESTORE3$
     Returns:  nothing


┌──────────────────────────────────────────┐
│ 5.13.3 ■ $SAVE$ ... Save graphics screen │
└──────────────────────────────────────────┘

Format:  $SAVE(destination)$
Syntax:  $SAVE(opt:DESTINATION)$                                      > v2.A4
                   ───────────                                        > v2.A4
                   BASE                                               > v2.A4
                   PUSH                                               > v2.A4
                   0-9                                                > v2.A4
                   ───────────                                        > v2.A4
               def=BASE                                               > v2.A4

If no slot parameter is specified, then this command will save the    > v2.A1
contents of the entire graphics screen to a disk file called          > v2.A1
RIPTERM.SAV.  No mouse fields, text window locations or clipboard     > v2.A1
data is saved - just the graphics screen.                             > v2.A1

If you specify a slot parameter then that identifies a specific       > v2.A1
screen slot to overwrite (0-9).  The files that the screen is stored  > v2.A1
to are RIPTERM0.SAV through RIPTERM9.SAV allowing you up to ten       > v2.A1
separate screen slots saved simultaneously.                           > v2.A1

If you specify "PUSH" instead of a slot number then a stack-based     > v2.A1
save operation will be performed (eg, $SAVE(PUSH)$).                  > v2.A1

If you specify "BASE" instead of a slot number than you the screen    > v2.A4
will be stored in the base save area of the screen data backup area.  > v2.A4

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

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

Also saved are the graphical style slots and button style slots.      > v2.A1

     Example:  $SAVE(7)$
     Returns:  nothing



┌───────────────────────────────────────────────────┐
│ 5.13.4 ■ $SAVEx$ ... Save graphics screen (x=0-9) │
└───────────────────────────────────────────────────┘

Format:  $SAVE0$ - $SAVE9$
Syntax:  $SAVE0$ ... $SAVE9$                                          > v2.A4

If you choose the SAVE0 through SAVE9 variations, the filename that
is saved to files RIPTERM0.SAV through RIPTERM9.SAV, allowing you to
have multiple screens saved simultaneously.

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

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

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

     Example:  $SAVE7$
     Returns:  nothing



╔══════════════════════════════════════════════════╗
║ 5.14 ■ DATA TABLE AND BACKUP AREA TEXT VARIABLES ║
╚══════════════════════════════════════════════════╝

These text variables return information on, or manipulate the data    > v2.A4
backup system.                                                        > v2.A4


┌────────────────────────────────────────────────────────────────────┐
│ 5.14.1 ■ $BACKSTAT$ ... Return status information on a backup area │
└────────────────────────────────────────────────────────────────────┘

Format:  $BACKSTAT(type)$
Syntax:  $BACKSTAT(req:TYPE,  opt:MODE)$                              > v2.A4
                       ────       ────                                > v2.A4
                       TW         USE                                 > v2.A4
                       BUT        PROT                                > v2.A4
                       STYLE      ────                                > v2.A4
                       PORT   def=USE                                 > v2.A4
                       MOUSE                                          > v2.A4
                       PAL                                            > v2.A4
                       ENV                                            > v2.A4
                       SCREEN                                         > v2.A4

This function returns status information on the specified data backup > v2.A4
area.  The information returned provides a detailed breakdown of the  > v2.A4
specified data backup area.  The following data backup areas may be   > v2.A4
specified with the TYPE parameter:                                    > v2.A4

     Area      Description                                            > v2.A4
     ─────────────────────────────────────────                        > v2.A4
     TW        Text window backup area                                > v2.A4
     BUT       Button style backup area                               > v2.A4
     STYLE     Graphics style backup area                             > v2.A4
     PORT      Drawing port backup area                               > v2.A4
     MOUSE     Mouse field backup area                                > v2.A4
     PAL       Color palette backup area                              > v2.A4
     ENV       Environment backup area                                > v2.A4
     SCREEN    Screen backup area                                     > v2.A4

The MODE parameter defines what kind of backup area status            > v2.A4
information you are requesting.  If it is omitted, or specified as    > v2.A4
"USE", then the data returned is a composite string of values         > v2.A4
detailing which areas of the backup area are "in use".  The format    > v2.A4
of this string of text is:                                            > v2.A4

     base:stack:slots:free:s0:s1:s2:s3:s4:s5:s6:s7:s8:s9              > v2.A4

The "base" field is set to "0" if the base save area is not in use,   > v2.A4
or "1" if it is in use.  The "stack" field is set to the number of    > v2.A4
entries that are currently saved on the stack ("0" if its empty).     > v2.A4
The "slots" field states how many entries are saved in the data       > v2.A4
save slots.  The "free" field determines how many stack/slot areas    > v2.A4
are not in use (ie, how many more can hold data).  The final ten      > v2.A4
entries "s0" through "s9" are set to "0" or "1" indicating if that    > v2.A4
specific data save slot is currently in use or not.  If you add up    > v2.A4
the "stack" and "slots" value, you will get a total value of entries  > v2.A4
stored in the stack/slot system.  If you add this total value up      > v2.A4
with the value of "free", then you get the maximum number of entries  > v2.A4
allowed to be saved in the stack/slot system (currently this should   > v2.A4


be set not exceed 10).                                                > v2.A4

If the MODE parameter is set to "PROT", then you are requesting       > v2.A4
which data save slots in the data backup area are protected or not.   > v2.A4
The format returned to the host is:                                   > v2.A4

     s0:s1:s2:s3:s4:s5:s6:s7:s8:s9                                    > v2.A4

The contents of the "s0" through "s9" fields will be set to "0" to    > v2.A4
indicate that the data save slot is not protected, or "1" if it is    > v2.A4
protected.                                                            > v2.A4

     Example:  $BACKSTAT(TW, USE)$                                    > v2.A4
     Returns:  0:2:3:5:0:0:0:1:0:0:1:1:0:0                            > v2.A4

     Example:  $BACKSTAT(TW, PROT)$                                   > v2.A4
     Returns:  0:1:0:0:1:0:0:1:0:0                                    > v2.A4


┌─────────────────────────────────────────────────────┐
│ 5.14.2 ■ $COPY$ ... Copy object to 1/more locations │
└─────────────────────────────────────────────────────┘

Format:  $COPY(type,source,dest1,...)$
Syntax:  $COPY(req:TYPE, req:SOURCE, req:DEST1, ...)$
                   ────      ──────
                   TW        0-35:TYPE<>MOUSE,SCREEN,PORT
                   BUT       CUR:TYPE<>MOUSE,SCREEN,PORT
                   STYLE     TBL
                   PAL       BASE
                   PORT      S0-S9
                   MOUSE     POP
                   ENV
                   SCREEN

               req:DEST1
                   ─────
                   0-35:TYPE<>MOUSE,SCREEN,PORT
                   CUR:TYPE<>MOUSE,SCREEN,PORT
                   TBL
                   BASE
                   S0-S9
                   PUSH

This complex command embodies many different "data copy" operations.  > v2.A3
The basic types of copy operations allowed with this command are:     > v2.A3

Type <type> parameter defines what type of data object is to be       > v2.A4
copied from one location to another.  The following data types can    > v2.A4
be copied with the user of this command (these are the values that    > v2.A4
the <type> parameter can contain:                                     > v2.A4



          Keyword     Description                                     > v2.A4
          ─────────────────────────────────                           > v2.A4
          STYLE       Graphics style data                             > v2.A4
          BUT         Button style data                               > v2.A4
          TW          Text window data                                > v2.A4
          PAL         Color palette data                              > v2.A4
          PORT        Drawing port data                               > v2.A4
          MOUSE       Mouse field data                                > v2.A4
          SCREEN      Graphics screen data                            > v2.A4
          ENV         Environment data                                > v2.A4

      Data Table                                                      > v2.A4
    ╔════════════╗ 3         ╔═════════════════════════════════╗      > v2.A4
    ║            ║  ◄──────► ║         Base Save Area          ║      > v2.A4
    ╟────────────╢          1╚═════════════════════════════════╝      > v2.A4
    ║            ║                                5▲    12▲           > v2.A4
    ╟────────────╢                                 │      │           > v2.A4
    ║            ║                                 ▼6     │           > v2.A4
    ╟────────────╢           ╔═══╤═══╤═══╤═══╤═══╤═══╗    │           > v2.A4
    ║   14▲      ║ 4         ║   │   │   │   │ 7 │   ║    │           > v2.A4
    ╟──── │ ─────╢  ◄──────► ║   │   │ ────────► │   ║    │           > v2.A4
    ║     │      ║          2║   │   │   │   │   │   ║    │           > v2.A4
    ╟──── │ ─────╢           ╚═══╧═══╧═══╧═══╧═══╧═══╝    │           > v2.A4
    ║     │      ║            Data Save Slots    13▲      │           > v2.A4
    ╟────────────╢                                 │      │           > v2.A4
    ║            ║                                 ▼11    ▼10         > v2.A4
    ╟────────────╢ 9         ╔═════════════════════════════════╗      > v2.A4
    ║            ║  ◄──────► ║         Data Save Stack         ║      > v2.A4
    ╟────────────╢          8╚═════════════════════════════════╝      > v2.A4
    ║            ║                                                    > v2.A4
    ╚════════════╝                                                    > v2.A4

   Copying entire Data Tables around (inter-table copying)            > v2.A3
   ─────────────────────────────────────────────────────────────────  > v2.A3
   1.  Copy the actual Data Table into the data backup area's Base    > v2.A3
       Data Save Area.                                                > v2.A3

               Copy table -> Base area                                > v2.A4

   2.  Copy the actual Data Table into a specific backup area's Data  > v2.A3
       Save Slot (via a slot index number from 0-9).                  > v2.A3

               Copy table -> Save slot                                > v2.A4

   3.  Copy the Base Data Save Area to the actual Data Table          > v2.A3

               Copy Base area -> Table                                > v2.A4

   4.  Copy a Data Save Slot (specified with an index number)         > v2.A3
       directly into the actual Data Table.                           > v2.A3

               Copy Save slot -> Table                                > v2.A4

   5.  Copy a Data Save Slot (specified with an index number) into    > v2.A3
       the Base Data Save Area.                                       > v2.A3

               Copy Save slot -> Base area                            > v2.A4

   6.  Copy the Base Data Save Area into a specific Data Save Slot    > v2.A3
       (specified by a slot index number from 0-9).                   > v2.A3


               Copy Base area -> Save slot                            > v2.A4

   7.  Copy one Data Save Slot to another Data Save Slot (both slots  > v2.A3
       are specified with slot index numbers).                        > v2.A3

               Copy Save slot -> Save slot                            > v2.A4

   8.  Push an actual Data Table onto the Data Save Slot "stack" via  > v2.A3
       the stack pointer.                                             > v2.A3

               Copy data table -> Stack (push)                        > v2.A4

   9.  Pop an actual Data Table off of the Data Save Slot "stack"     > v2.A3
       via the stack pointer.                                         > v2.A3

               Copy Stack (pop) -> table                              > v2.A4

   10. Push the Base Save Area onto the "stack" via the stack         > v2.A4
       pointer.                                                       > v2.A4

               Copy Base area -> Stack (push)                         > v2.A4

   11. Push a Data Save Slot onto the "stack" via the stack pointer   > v2.A4

               Copy Save slot -> Stack (push)                         > v2.A4

   12. Pop an actual Data Table off of the "stack" and place it into  > v2.A4
       the Base Save Area.                                            > v2.A4

               Copy Stack (pop) -> Base area                          > v2.A4

   13.  Pop an actual Data Table off of the "stack" and place it into > v2.A4
        a specific Save slot.                                         > v2.A4

               Copy Stack (pop) -> Save slot                          > v2.A4

   Copying Data Table Entries around (intra-table copying)            > v2.A3
   ─────────────────────────────────────────────────────────────────  > v2.A3
   14. Copy one entry in an actual Data to one or more other entries  > v2.A3
       inside the same Data Table                                     > v2.A3

               Copy Table[index1] -> Table[index2]                    > v2.A4

When you are referring to a copy operation that involves the entire   > v2.A3
data table, you use the keyword "TBL".  When referring to the Base    > v2.A3
Data Save Area, the keyword "BASE" is used.  A Data Save Slot number  > v2.A3
is specified with the letter "S" followed by the slot index number    > v2.A3
(eg, S0, S3, S5, etc).  An actual data table entry number is          > v2.A3
specified simply as an actual number from 0 to the total number of    > v2.A3
entries in the data table minus one.                                  > v2.A3

Destinations for entire data tables can be the BASE save area, a      > v2.A4
Data Save Slot (S0-S9) or you can PUSH it onto the stack.             > v2.A4

You can also specify the source as POP to indicate that you are       > v2.A4
copying (popping) data from the stack to some other destination       > v2.A4
(TBL, BASE or S0-S9).  If you specify only one destination location,  > v2.A4
then the contents of the stack are copied to that location, then the  > v2.A4
stack is "popped", which basically deletes the top item on the stack  > v2.A4
(the one that was just copied).  If you have multiple destinations,   > v2.A4
then the stack item is copied to each of those locations, then it is  > v2.A4


finally deleted from the stack after all of the copy operations are   > v2.A4
complete.                                                             > v2.A4

If the source refers to an entry in a data table (not the entire      > v2.A4
data table), then the destination(s) must also be individual data     > v2.A4
table entry numbers.                                                  > v2.A4
                                                                     > v2.A4
Some data tables allow you to directly access individual data entries > v2.A3
inside the data table (ie, text window tables, graphical style        > v2.A3
tables, color palette tables, button style tables and drawing port    > v2.A3
tables).  You cannot directly access data table entries for the Mouse > v2.A3
Field data table, and you cannot directly access the data table       > v2.A3
entries for the screen data table.  In these two cases, copying one   > v2.A3
data table entry over another entry in the same data table entry is   > v2.A3
not allowed.                                                          > v2.A3

Some data tables allow you to have a specific entry selected as the   > v2.A3
current table entry.  For example, the text window data table has one > v2.A3
data table entry selected as the current text window at any one       > v2.A3
time.  When a data table allows an entry to be the current entry,     > v2.A3
then the keyword "CUR" may be used to specify the current table entry > v2.A3
when performing copy operations from one data table entry to another  > v2.A3
entry.  The following list describes which data tables have a current > v2.A3
entry allowed:                                                        > v2.A3

                                            Total      Entry          > v2.A3
   Table Name        Allows current entry?  Entries    Access         > v2.A3
   ──────────────────────────────────────────────────────────         > v2.A3
   Text window table          Yes              36       Yes           > v2.A3
   Drawing port table         No               36       No            > v2.A4
   Graphical style table      Yes              36       Yes           > v2.A3
   Button style table         Yes              36       Yes           > v2.A4
   Color palette table        Yes              36       Yes           > v2.A3
   Environment                Yes              36       Yes           > v2.A4
   Mouse field table          No              128       No            > v2.A3
   Graphics screen table      No                1       No            > v2.A3

You cannot copy a data table over itself, and you cannot copy a data  > v2.A4
table entry on top of itself.  All destination parameters are checked > v2.A4
for validity before any actual copy operations are performed.  If any > v2.A4
of them fail a syntax check then the entire $COPY$ expression is      > v2.A4
rejected as a syntax error.                                           > v2.A4

Our of all six data tables that have 36 separate entries, one of      > v2.A4
them doesn't permit direct copying from one entry to another within   > v2.A4
the same data table.  That table is the drawing port table.  The      > v2.A4
reason for this is because of how complicated the subject of          > v2.A4
performing port copying from one entry to another.  Do you copy over  > v2.A4
just the graphical data, and if so, do you stretch it to fit in the   > v2.A4
destination port if the dimensions of the ports don't match?  On the  > v2.A4
other hand do you duplicate the port definition entirely, potentially > v2.A4
copying over the bitmap data?  If so, how do you handle copying to    > v2.A4
port #0 which cannot be deleted or re-defined?  With all of these     > v2.A4
complicated issues involved, it was decided not to allow for ports to > v2.A4
be copied from one entry to another.  Perhaps in the future we will   > v2.A4
allow for this kind of operation when more research on the issues can > v2.A4
be performed.                                                         > v2.A4



Note that copying individual text window table entries, or individual > v2.A4
drawing port entries around also copies around the resident query     > v2.A4
associated with that particular text window or port!                  > v2.A4

The following sections describe the various combinations of copy      > v2.A3
parameters:                                                           > v2.A3

  Copy actual Data Table into the data backup area's Base Save Area   > v2.A3
  ─────────────────────────────────────────────────────────────────   > v2.A3
          $COPY(TW, TBL, BASE)$                                       > v2.A3

  Copy actual Data Table into a specific backup area's Data Save Slot > v2.A3
  ─────────────────────────────────────────────────────────────────── > v2.A3
          $COPY(TW, TBL, S3)$                                         > v2.A3

  Copy the Base Data Save Area to the actual Data Table               > v2.A3
  ─────────────────────────────────────────────────────               > v2.A3
          $COPY(TW, BASE, TBL)$                                       > v2.A3

  Copy a Data Save Slot directly into the actual Data Table           > v2.A3
  ─────────────────────────────────────────────────────────           > v2.A3
          $COPY(TW, S3, TBL)$                                         > v2.A3

  Copy a Data Save Slot into the Base Data Save Area                  > v2.A3
  ──────────────────────────────────────────────────                  > v2.A3
          $COPY(TW, S3, BASE)$                                        > v2.A3

  Copy the Base Data Save Area into a specific Data Save Slot         > v2.A3
  ───────────────────────────────────────────────────────────         > v2.A3
          $COPY(TW, BASE, S3)$                                        > v2.A3

  Copy one Data Save Slot to another Data Save Slot                   > v2.A3
  ─────────────────────────────────────────────────                   > v2.A3
          $COPY(TW, S3, S5)$                                          > v2.A3

  Push an actual Data Table onto the Data Save Slot "stack"           > v2.A3
  ─────────────────────────────────────────────────────────           > v2.A3
          $COPY(TW, TBL, PUSH)$                                       > v2.A3

  Pop an actual Data Table off of the Data Save Slot "stack"          > v2.A3
  ──────────────────────────────────────────────────────────          > v2.A3
          $COPY(TW, POP, TBL)$                                        > v2.A3

  Copy one entry in an actual Data Table to one or more other entries > v2.A3
  ─────────────────────────────────────────────────────────────────── > v2.A3
          $COPY(TW, 3, 5)$                                            > v2.A3

You can also combine various copy operations into one copy command    > v2.A3
like this:                                                            > v2.A3

          $COPY(TW, TBL, S3, BASE, S5)$                               > v2.A3

     Copies the entire data table into data save slot #3, #5 and      > v2.A3
     into the base data save area.                                    > v2.A3

          $COPY(TW, CUR, 5, 7, 9)$                                    > v2.A3

     Copies the current data table entry into data table entry        > v2.A3
     numbers 5, 7 and 9 (overwriting those entries with the data      > v2.A3
     inside the current data table entry).                            > v2.A3


┌──────────────────────────────────────────────────────────┐
│ 5.14.3 ■ $CUR$ ... Select/query current data table entry │
└──────────────────────────────────────────────────────────┘

Format:  $CUR(type,which)$
Syntax:  $CUR(req:TYPE,  opt:WHICH)$                                  > v2.A4
                  ────       ─────                                    > v2.A4
                  TW         0-35                                     > v2.A4
                  PORT       ─────                                    > v2.A4
                  STYLE  def=<none>                                   > v2.A4
                  PAL                                                 > v2.A4
                  BUT                                                 > v2.A4
                  ENV                                                 > v2.A4

This variable sets or inquires about the current data table entry     > v2.A4
number associated with a specific data table indicating by the TYPE   > v2.A4
parameter (which must be specified).  The possible TYPE parameters    > v2.A4
are as follows:                                                       > v2.A4

     Name      Description                                            > v2.A4
     ───────────────────────────────────────────                      > v2.A4
     TW        Text window data table                                 > v2.A4
     PORT      Drawing port data table                                > v2.A4
     STYLE     Graphics style data table                              > v2.A4
     PAL       Color palette data table                               > v2.A4
     BUT       Button style data table                                > v2.A4
     ENV       Environment data table                                 > v2.A4

The WHICH parameter is only used when setting the current entry for   > v2.A4
the given data table.  If you omit the WHICH parameter, then you are  > v2.A4
asking the terminal "which entry in the specified data table is the   > v2.A4
current one?".  In situations like this, this text variable will      > v2.A4
return a value from "0" to "35".                                      > v2.A4

If the WHICH parameter is specified, then you are not inquiring about > v2.A4
the current entry in that data table, you are setting it.  Possible   > v2.A4
values for WHICH are numbers from 0-35 to indicate which data table   > v2.A4
entry you wish to make the current one.  If the entry you specify     > v2.A4
isn't defined, then it is set to some suitable defaults based on the  > v2.A4
following table:                                                      > v2.A4

       Data Table     Description of Defaults                         > v2.A4
       ─────────────────────────────────────────────────────────────  > v2.A4
       TW             The text window is made full screen in the      > v2.A4
                      user's default font.                            > v2.A4

       PORT           The port is defined as a screen port occupying  > v2.A4
                      the entire screen.  The viewport is made the    > v2.A4
                      full size of the port.                          > v2.A4

       STYLE          The basic graphics style used upon a $RESET$    > v2.A4
                      operation is activated.                         > v2.A4

       PAL            The standard 256 color lookup table is          > v2.A4
                      established and activated.                      > v2.A4

       BUT            The basic button style used upon a $RESET$      > v2.A4
                      operation is activated.                         > v2.A4



       ENV            A basic environment is established.  640x350    > v2.A4
                      world coordinates, 2-byte coordinates, color    > v2.A4
                      palette mapping mode, mouse cursor 0, etc.      > v2.A4

     Example:  $CUR(TW, 5)$                                           > v2.A4
     Returns:  nothing                                                > v2.A4

     Example:  $CUR(TW)$                                              > v2.A4
     Returns:  5                                                      > v2.A4


┌───────────────────────────────────────────────┐
│ 5.14.4 ■ $INUSE$ ... Is a data object in use? │
└───────────────────────────────────────────────┘

Format:  $INUSE(data_object,element)$
Syntax:  $INUSE(req:DATA_OBJECT, req:ELEMENT)$                        > v2.A4
                    ───────────      ───────                          > v2.A4
                    PORT             1-35:DATA_OBJECT<>SCREEN,MOUSE   > v2.A4
                    TW               ALL:DATA_OBJECT<>SCREEN          > v2.A4
                    STYLE            ANY:DATA_OBJECT<>SCREEN          > v2.A4
                    BUT              S0-S9                            > v2.A4
                    PAL              BASE                             > v2.A4
                    MOUSE            ALLSLOTS                         > v2.A4
                    ENV              ANYSLOTS                         > v2.A4
                    SCREEN           STACK                            > v2.A4
                                     BACKUP                           > v2.A4

This command determines if a specific data object is currently in use > v2.A4
or not (ie, defined).  The type of data table that the DATA_OBJECT    > v2.A4
parameter refers to may be set to the following:                      > v2.A4

     Data Object    Description                                       > v2.A4
     ─────────────────────────────────────────────────────────        > v2.A4
     TW             Text window data object                           > v2.A4
     PORT           Drawing port data object                          > v2.A4
     STYLE          Graphics style data object                        > v2.A4
     BUT            Button style data object                          > v2.A4
     PAL            Color palette data object                         > v2.A4
     ENV            Environment data object                           > v2.A4
     MOUSE          Mouse field data object                           > v2.A4
     SCREEN         Graphics screen data object                       > v2.A4

The exact aspect of the data object in question which is being        > v2.A4
inquired about is defined by the ELEMENT parameter, which must also   > v2.A4
be specified.  The possible values for ELEMENT and their meanings     > v2.A4
are as follows:                                                       > v2.A4

     Elements       Description                                       > v2.A4
     ───────────────────────────────────────────────────────────────  > v2.A4
     1-35           A data table entry number from 1-35 (this is not  > v2.A4
                    valid for MOUSE or SCREEN data objects which do   > v2.A4
                    not directly addressable data table entries).     > v2.A4

     ALL            Are all data table entries from 1-35 in use?      > v2.A4
                    Entry 0 is always in use so it is not included    > v2.A4
                    in this element.  SCREEN data objects do not      > v2.A4
                    have a data table associated with them so you     > v2.A4
                    cannot specify ALL for them.                      > v2.A4


     ANY            Are any data table entries from 1-35 in use?      > v2.A4
                    Entry 0 is always in use so it is not included    > v2.A4
                    in this element otherwise it would always be      > v2.A4
                    in use.                                           > v2.A4

     S0-S9          This specifies a data save slot number from 0-9   > v2.A4
                    in the specified data object's data backup area.  > v2.A4

     BASE           Is the base save area of the data object's        > v2.A4
                    backup data area in use?                          > v2.A4

     ALLSLOTS       Are all data save slots in the data object's      > v2.A4
                    backup data area in use?                          > v2.A4

     ANYSLOTS       Are any data save slots in the data object's      > v2.A4
                    backup data area in use?                          > v2.A4

     STACK          Is the data save stack in the data object's       > v2.A4
                    backup data area in use?                          > v2.A4

If the specified data ELEMENT in the DATA_OBJECT is in use, then this > v2.A4
command returns "1".  It returns "0" if the specified condition is    > v2.A4
not met.                                                              > v2.A4

     Example:  $INUSE(TW, BASE)$                                      > v2.A4
     Returns:  FALSE                                                  > v2.A4


┌───────────────────────────────────────────────────┐
│ 5.14.5 ■ $ISPROT$ ... Is a data object protected? │
└───────────────────────────────────────────────────┘

Format:  $ISPROT(data_object,element)$
Syntax:  $ISPROT(req:DATA_OBJECT, req:ELEMENT)$                       > v2.A4
                     ───────────      ────────                        > v2.A4
                     TW               CUR:DATA_OBJECT<>SCREEN,MOUSE   > v2.A4
                     PORT             1-35:DATA_OBJECT<>SCREEN,MOUSE  > v2.A4
                     BUT              ALL:DATA_OBJECT<>SCREEN,MOUSE   > v2.A4
                     STYLE            ANY:DATA_OBJECT<>SCREEN,MOUSE   > v2.A4
                     PAL              S0-S9                           > v2.A4
                     MOUSE            ALLSLOTS                        > v2.A4
                     ENV              ANYSLOTS                        > v2.A4
                     SCREEN                                           > v2.A4

This command returns a value indicating if the specified element in   > v2.A4
the desired data object is protected or not.  If it is protected,     > v2.A4
then it returns a "1".  "0" is returned if it is not protected.  If   > v2.A4
the specified data object element is not in use (ie, not defined),    > v2.A4
then this command returns "-1".  The type of data object that can be  > v2.A4
specified in the DATA_OBJECT parameter may be set to the following:   > v2.A4



     Data Object    Description                                       > v2.A4
     ─────────────────────────────────────────────────────────        > v2.A4
     TW             Text window data object                           > v2.A4
     PORT           Drawing port data object                          > v2.A4
     STYLE          Graphics style data object                        > v2.A4
     BUT            Button style data object                          > v2.A4
     PAL            Color palette data object                         > v2.A4
     ENV            Environment data object                           > v2.A4
     MOUSE          Mouse field data object                           > v2.A4
     SCREEN         Graphics screen data object                       > v2.A4

What is element of the data object that is to inquired about is       > v2.A4
defined by the ELEMENT parameter.  This parameter must be specified   > v2.A4
and may be set to the following values:                               > v2.A4

     Elements       Description                                       > v2.A4
     ───────────────────────────────────────────────────────────────  > v2.A4
     CUR            Is the current data table entry in the            > v2.A4
                    specified data object data table protected?       > v2.A4
                    MOUSE and SCREEN's cannot have their entries (if  > v2.A4
                    any) protected, so this not permitted for the CUR > v2.A4
                    element (it would always return "0").  If the     > v2.A4
                    current data table entry is a value of 0, then    > v2.A4
                    this element will return the value "0" because    > v2.A4
                    this entry in a data table can never be           > v2.A4
                    protected.                                        > v2.A4

     1-35           A data table entry number from 1-35 (this is not  > v2.A4
                    valid for MOUSE or SCREEN data objects which do   > v2.A4
                    not directly protectable data table entries).     > v2.A4

     ALL            Are all data table entries from 1-35 protected?   > v2.A4
                    All of these entries would also have to be "in    > v2.A4
                    use" for this to be true.  Entry 0 cannot be      > v2.A4
                    protected so it is not included in this element.  > v2.A4
                    SCREEN and MOUSE data objects cannot have their   > v2.A4
                    table entries (if any) protected so these data    > v2.A4
                    objects are not permitted with the ALL element.   > v2.A4

     ANY            Are any defined data table entries in the data    > v2.A4
                    object's data table protected?                    > v2.A4

     S0-S9          Is the specified data save slot (0-9) for the     > v2.A4
                    data object protected?                            > v2.A4

     ALLSLOTS       Are all data save slots protected?                > v2.A4

     ANYSLOTS       Are any data save slots protected?                > v2.A4

     Example:  $UNPROT(TW, S7)$                                       > v2.A4
     Returns:  nothing                                                > v2.A4



┌────────────────────────────────────────────────┐
│ 5.14.6 ■ $PROT$ ... Protect data from deletion │
└────────────────────────────────────────────────┘

Format:  $PROT(data_object,element1,...)$
Syntax:  $PROT(req:DATA_OBJECT, req:ELEMENT1, ...)$                   > v2.A4
                   ───────────      ────────                          > v2.A4
                   TW               CUR:DATA_OBJECT<>SCREEN,MOUSE     > v2.A4
                   PORT             1-35:DATA_OBJECT<>SCREEN,MOUSE    > v2.A4
                   BUT              ALL:DATA_OBJECT<>SCREEN,MOUSE     > v2.A4
                   STYLE            S0-S9                             > v2.A4
                   PAL              ALLSLOTS                          > v2.A4
                   ENV                                                > v2.A4
                   MOUSE                                              > v2.A4
                   SCREEN                                             > v2.A4

This command protects a specific element of a given data object.      > v2.A4
The type of data object that can be specified in the DATA_OBJECT      > v2.A4
parameter may be set to the following:                                > v2.A4

     Data Object    Description                                       > v2.A4
     ─────────────────────────────────────────────────────────        > v2.A4
     TW             Text window data object                           > v2.A4
     PORT           Drawing port data object                          > v2.A4
     STYLE          Graphics style data object                        > v2.A4
     BUT            Button style data object                          > v2.A4
     PAL            Color palette data object                         > v2.A4
     ENV            Environment data object                           > v2.A4
     MOUSE          Mouse field data object                           > v2.A4
     SCREEN         Graphics screen data object                       > v2.A4

What is element of the data object that is to be protected is defined > v2.A4
by the ELEMENT parameter.  This parameter must be specified (you may  > v2.A4
specify more than one to protect multiple elements in one command).   > v2.A4
ELEMENT may be set to the following values:                           > v2.A4

     Elements       Description                                       > v2.A4
     ───────────────────────────────────────────────────────────────  > v2.A4
     CUR            Protect the current data table entry in the       > v2.A4
                    specified data object data table.  MOUSE and      > v2.A4
                    SCREEN's cannot have their entries (if any)       > v2.A4
                    protected, so this is not permitted for the CUR   > v2.A4
                    element.  If the current data table entry is a    > v2.A4
                    value of 0, then this element is ignored because  > v2.A4
                    entry 0 cannot be protected in any data table.    > v2.A4

     1-35           A data table entry number from 1-35 (this is not  > v2.A4
                    valid for MOUSE or SCREEN data objects which do   > v2.A4
                    not directly protectable data table entries).     > v2.A4

     ALL            Protect all data table entries from 1-35 that     > v2.A4
                    are currently in use.  Entry 0 cannot be          > v2.A4
                    protected so it is not included in this element.  > v2.A4
                    SCREEN and MOUSE data objects cannot have their   > v2.A4
                    table entries (if any) protected so these data    > v2.A4
                    objects are not permitted with the ALL element.   > v2.A4

     S0-S9          This protects a data save slot number from 0-9    > v2.A4
                    in the specified data object's data backup area.  > v2.A4


     ALLSLOTS       Protect all data save slots in the data object's  > v2.A4
                    data backup area that are currently in use.       > v2.A4

If a data object element is attempted to be protected, but it is not  > v2.A4
in use then this command does nothing for that parameter.             > v2.A4

     Example:  $PROT(TW, S7)$                                         > v2.A4
     Returns:  nothing                                                > v2.A4


┌─────────────────────────────────────────┐
│ 5.14.7 ■ $UNPROT$ ... Unprotects object │
└─────────────────────────────────────────┘

Format:  $UNPROT(data_object,element1,...)$
Syntax:  $UNPROT(req:DATA_OBJECT, req:ELEMENT1, ...)$                 > v2.A4
                     ───────────      ────────                        > v2.A4
                     TW               CUR:DATA_OBJECT<>SCREEN,MOUSE   > v2.A4
                     PORT             1-35:DATA_OBJECT<>SCREEN,MOUSE  > v2.A4
                     BUT              ALL:DATA_OBJECT<>SCREEN,MOUSE   > v2.A4
                     STYLE            S0-S9                           > v2.A4
                     PAL              ALLSLOTS                        > v2.A4
                     MOUSE                                            > v2.A4
                     ENV                                              > v2.A4
                     SCREEN                                           > v2.A4

This command unprotects a specific element of a given data object.    > v2.A4
The type of data object that can be specified in the DATA_OBJECT      > v2.A4
parameter may be set to the following:                                > v2.A4

     Data Object    Description                                       > v2.A4
     ─────────────────────────────────────────────────────────        > v2.A4
     TW             Text window data object                           > v2.A4
     PORT           Drawing port data object                          > v2.A4
     STYLE          Graphics style data object                        > v2.A4
     BUT            Button style data object                          > v2.A4
     PAL            Color palette data object                         > v2.A4
     ENV            Environment data object                           > v2.A4
     MOUSE          Mouse field data object                           > v2.A4
     SCREEN         Graphics screen data object                       > v2.A4

What is element of the data object that is to be unprotected is       > v2.A4
defined by the ELEMENT parameter.  This parameter must be specified   > v2.A4
(you may specify more than one to unprotect multiple elements in one  > v2.A4
command).  ELEMENT may be set to the following values:                > v2.A4

     Elements       Description                                       > v2.A4
     ───────────────────────────────────────────────────────────────  > v2.A4
     CUR            Unprotect the current data table entry in the     > v2.A4
                    specified data object data table.  MOUSE and      > v2.A4
                    SCREEN's cannot have their entries (if any)       > v2.A4
                    unprotected, so this is not permitted for the CUR > v2.A4
                    element.  If the current data table entry is a    > v2.A4
                    value of 0, then this element is ignored because  > v2.A4
                    entry 0 cannot be unprotected in any data table.  > v2.A4

     1-35           A data table entry number from 1-35 (this is not  > v2.A4
                    valid for MOUSE or SCREEN data objects which do   > v2.A4
                    not directly protectable data table entries).     > v2.A4


     ALL            Unprotect all data table entries from 1-35 that   > v2.A4
                    are currently in use.  Entry 0 cannot be          > v2.A4
                    protected so it is not included in this element.  > v2.A4
                    SCREEN and MOUSE data objects cannot have their   > v2.A4
                    table entries (if any) protected so these data    > v2.A4
                    objects are not permitted with the ALL element.   > v2.A4

     S0-S9          This unprotects a data save slot number from 0-9  > v2.A4
                    in the specified data object's data backup area.  > v2.A4

     ALLSLOTS       Unprotect all data save slots in the data         > v2.A4
                    object's data backup area that are currently in   > v2.A4
                    use.                                              > v2.A4

If a data object element is attempted to be unprotected, but it is    > v2.A4
not in use then this command does nothing for that parameter.         > v2.A4

     Example:  $UNPROT(TW, S7)$                                       > v2.A4
     Returns:  nothing                                                > v2.A4



╔═════════════════════════════════════════════╗
║ 6 ■ RIPscrip ICON FILE FORMAT SPECIFICATION ║
╚═════════════════════════════════════════════╝

The following section describes the exact file format specification   > v2.A1
of the RIPscrip Icon File.  This format differs from the older RIP    > v2.A1
v1.54 icon file format which used the Borland getimage() and          > v2.A1
putimage() formats.  That format was completely inadequate to         > v2.A1
resolution independent and color independent environments.  With that > v2.A1
in mind, we have changed to a Device Independent Bitmap (DIB).  A DIB > v2.A1
is a file that can be shown at any resolution, in any color           > v2.A1
configuration.  There are no actual DIB files out there in the world  > v2.A1
that conform to the raw DIB format.  The Microsoft Windows BMP format > v2.A1
is a DIB though, with a little more header information thrown in to   > v2.A1
give some added flexibility for future expandability.  In the         > v2.A1
interests of not inventing a completely new file format, we will be   > v2.A1
using BMP files for the icon format for future RIPscrip revisions.    > v2.A1



┌────────────────────────────────────────────────────┐
│ 6.1 ■ DEVICE INDEPENDENT BITMAP (DIB) FILE FORMAT) │
└────────────────────────────────────────────────────┘

The DIB file format, originally pioneered by Microsoft for their      > v2.A1
Windows product provides a device-independent method of storing       > v2.A1
bitmap data in a universally accessible way.                          > v2.A1

The file format has a more elaborate header structure than does the   > v2.A1
RIPscrip Icon file format.  In addition, color palette information is > v2.A1
stored in the file so that color approximation or dithering methods   > v2.A1
may be used to make image appear correct no matter what color palette > v2.A1
is in use.                                                            > v2.A1

The file format accomodates 1 bit per pixel (monochrome images), 4    > v2.A1
bits per pixel (16 color images), 8 bits per pixel (256 color images) > v2.A1
and 24 bit images.                                                    > v2.A1



┌─────────────────────────┐
│ 6.1.1 ■ DIB FILE HEADER │
└─────────────────────────┘

At the beginning of the file (at offset 0) is the bitmap information  > v2.A1
header.  Immediately following this is a color table (for all formats > v2.A1
except for 24 bit images).  The size of the color table is dependent  > v2.A1
on the number of bits per pixel and also on some other fields in the  > v2.A1
header.  After the color table is the actual raw bitmap data.  The    > v2.A1
format of the bitmap data varies depending on the number of bits per  > v2.A1
pixel.                                                                > v2.A1

The structure of the bitmap header is as follows:                     > v2.A1

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


The biSize parameter is the size of the actual header in the file.    > v2.A1
This should be set to 40 for this structure.  In the future, this     > v2.A1
value may change to accomodate larger headers.  To properly read in   > v2.A1
the header, you should examine the first four bytes of the header to  > v2.A1
find out the actual header's size then read in the remaining bytes of > v2.A1
the header into your program.                                         > v2.A1

The biWidth and biHeight parameter define the pixel dimensions of the > v2.A1
actual image in the raw bitmap data block.                            > v2.A1

The biPlanes field defines how many "bit planes" are used in the      > v2.A1
bitmap data.  This value should be set to 1 - meaning one bit plane.  > v2.A1

The biBitCount field determines the number of bits per pixel used in  > v2.A1
this image.  Valid values for this field are 1, 4, 8 and 24.          > v2.A1

The biCompression field determines the type of image compression used > v2.A1
on this image.  A value of 0 means no compression.  Microsoft defines > v2.A1
several nonzero values for the BMP files (basically a DIB with a bit  > v2.A1
more header information) that use a byte-oriented RLE encoding        > v2.A1
scheme.  After some research, it was found that no applications       > v2.A1
actually use this mode and the one vendor that we discovered that     > v2.A1
supported this form of compression did not do it correctly. As a      > v2.A1
result of this, we will formally declare that this field should be    > v2.A1
set to zero to indicate no compression.  In the future, we may alter  > v2.A1
this for something like internal JPEG data compression, TIFF, GIF,    > v2.A1
etc.                                                                  > v2.A1

The biSizeImage indicates the size of the compressed image in bytes.  > v2.A1
This is actually the size of the file (including all header           > v2.A1
information).                                                         > v2.A1


The biXPelsPerMeter and biYPelsPerMeter values are used for dots per  > v2.A1
inch calculations.  The formal definition of these fields are the     > v2.A1
horizontal and vertical resolution in pixels per meter.  It does not  > v2.A1
appear that any applications that use DIB formats actually take       > v2.A1
advantage of these fields, so they could easily be set to zero, or    > v2.A1
the width and height of the image.                                    > v2.A1

The biClrUsed field defines how many colors out of the maximum        > v2.A1
available are actually used by this image.  For example, if you have  > v2.A1
an 8 bit per pixel image (256 colors), but the image only uses 200    > v2.A1
colors, you could set this value to 200 to indicate that the color    > v2.A1
table only has 200 entries in it. Set this field to 0 to indicate     > v2.A1
that the maximum number of colors are in the color table.  We will    > v2.A1
set this value to 0 for all RIP bitmaps.                              > v2.A1

The biClrImportant field is used to specify how many of the colors in > v2.A1
the color table are actually important to the image.  For example, if > v2.A1
you had a 256 color bitmap, but only 16 colors of the image were      > v2.A1
critically important to the reproduction of the image, you would set  > v2.A1
this field to 16 and make sure that the first 16 colors in the color  > v2.A1
table were those important colors. This makes conversion to a 16      > v2.A1
color environment easier.  We formally will set this value to 0 to    > v2.A1
indicate that all colors are equally important.                       > v2.A1



┌────────────────────────────┐
│ 6.1.2 ■ COLOR TABLE FORMAT │
└────────────────────────────┘

For 1, 4 and 8 bits per pixel images, a color table immediately       > v2.A1
follows the bitmap file header.  If the biClrUsed field is set to     > v2.A1
zero in the header, then the number of entries is 2^bits where "bits" > v2.A1
is the number of bits per pixel (1, 4, or 8).  This yields color      > v2.A1
table sizes of 2, 16 or 256 entries.  If the biClrUsed field is       > v2.A1
non-zero, then it defines the actual number of color table entries    > v2.A1
actually present.                                                     > v2.A1

Each entry in the color table consists of an RgbQuad structure.  This > v2.A1
structure stores information for the Red, Green and Blue components   > v2.A1
of the corresponding color table entry.  All values are full 8-bit    > v2.A1
unsigned characters, representing values from 0-255.  If displaying   > v2.A1
colors in video sub-systems that are not 8 bits for these components, > v2.A1
some bit shifting may be necessary to convert to the proper target    > v2.A1
color system.                                                         > v2.A1

Here is the structure definition for the RgbQuad structure:           > v2.A1

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

Notice that the values are in reverse order (Blue, Green then Red).   > v2.A1
For some obscure reason, this was the way that it was originally      > v2.A1
designed.  Also note that there is a reserved parameter.  This should > v2.A1
be set to zero for future compatibility.                              > v2.A1

For 24 bit images, there is no color table.  Color table values are   > v2.A1
actually stored in the raw bitmap data block itself (see below).      > v2.A1



┌──────────────────────────────────┐
│ 6.1.3 ■ BITMAP DATA BLOCK FORMAT │
└──────────────────────────────────┘

The format for the bitmap data block varies depending on the number   > v2.A1
of bits per pixel actually defined in the header.  The reason for     > v2.A1
this is optimal data storage without compression.                     > v2.A1

All bitmap image data blocks are stored in horizontal rows of data.   > v2.A1
Each row is padded to an even four byte boundary with zeros.  The     > v2.A1
first row of raw data is actually the bottom-most scan line of the    > v2.A1
bitmap.  Every subsequent row is progressively closer to the top of   > v2.A1
the bitmap in one line increments.                                    > v2.A1

The four storage methods are described in the next sub-sections.      > v2.A1


     1 BIT PER PIXEL                                                  > v2.A1
     ───────────────                                                  > v2.A1
     Information is stored as one pixel per bit.  The high-order      > v2.A1
     bit in a byte is the left-most pixel in a group of eight         > v2.A1
     pixels.  For bits that represent pixels beyond the right         > v2.A1
     side of the image, zero bits are used as padding.                > v2.A1

     For example, if you had the following pixel values:              > v2.A1

          1 0 0 1 1 1 0 1 1 0 1 0 1 1 1 1 0 1 1 1                     > v2.A1

     They would be encoded as the following:                          > v2.A1

            In Binary: 10011101 10101111 01110000                     > v2.A1
          Hexadecimal: 9D AF 70 00                                    > v2.A1

     Note how four zero bits are added to the last byte, and          > v2.A1
     another zero byte is added to pad the row out to an even         > v2.A1
     four-byte boundary.  If image data stops exactly on a four       > v2.A1
     byte boundary, no padding is necessary.                          > v2.A1


     4 BITS PER PIXEL                                                 > v2.A1
     ────────────────                                                 > v2.A1
     Information is stored as two pixels per byte.  Each pixel's      > v2.A1
     color value is stored in its own nibble inside the byte.         > v2.A1
     The left-most pixel is stored in the high-order nibble, and      > v2.A1
     the right-most pixel is stored in the low-order nibble.          > v2.A1

     For example, if you had the following pixel values:              > v2.A1

           In decimal:  12 0 7 8 4 15 11 10 9                         > v2.A1
          Hexadecimal:  C  0 7 8 4 F  B  A  9                         > v2.A1

     This would result in the following 4 bit encoding values:        > v2.A1

          Hexadecimal:  C0 78 4F BA 90 00 00 00                       > v2.A1

     Note that an extra 0 nibble was added to the last valid dat      > v2.A1
     byte and three zero bytes were added to round the row out        > v2.A1
     to an even four byte boundary.                                   > v2.A1



     8 BITS PER PIXEL                                                 > v2.A1
     ────────────────                                                 > v2.A1
     This is the most straightforward encoding scheme.  Each          > v2.A1
     pixel is stored as exactly one pixel per byte.  All eight        > v2.A1
     bits of the byte are used to store the pixel color values.       > v2.A1
     No bit shifting or color encoding is necessary.                  > v2.A1

     The above example (4 bits per pixel) would be encoded as         > v2.A1
     follows:                                                         > v2.A1

          Hexadecimal: 0C 00 07 08 04 0F 0B 0A 09 00 00 00            > v2.A1

     Notice that three extra zero bytes were added to round the       > v2.A1
     row out to an even four byte boundary.                           > v2.A1


     24 BITS PER PIXEL                                                > v2.A1
     ─────────────────                                                > v2.A1
     This format does not use a color table.  The actual RGB          > v2.A1
     values used for colors is actually stored in the raw bitmap      > v2.A1
     data blocks.  Each pixel's worth of data in the data block       > v2.A1
     consists of three bytes.  The first byte represents the          > v2.A1
     BLUE component, then the GREEN component, then the RED           > v2.A1
     component in the third byte.  Each one of these values can       > v2.A1
     range from 0 to 255.  Some bit shifting may be necessary         > v2.A1
     depending on your target video sub-system.  Again, every         > v2.A1
     row of information is padded to an even four byte boundary       > v2.A1
     like all the above methods do.                                   > v2.A1



┌─────────────────────────────┐
│ 6.1.4 ■ MISCELLANEOUS NOTES │
└─────────────────────────────┘

Any of the fields in the header that are LONGs or INTs use Intel byte > v2.A1
ordering of its values.  For IBM-PC based software, this should pose  > v2.A1
no problems at all.  On Motorola based processors though, the data in > v2.A1
these fields will have to have some bit shifting done on them to      > v2.A1
ensure that they are represented correctly.  In no cases will these   > v2.A1
fields in the header represent negative values.                       > v2.A1

                                # # #



