Why and how?
"Escape sequence" is another of those phrases which cause a nervous drying-up of computer users' comprehension... which is a pity, since this is the key to all Apricot screen control beyond the simplest line-by-line text display. When you send text characters to the screen, they're displayed and that's that. For suave effects you must send special control codes, and the most powerful of these is "Escape". Once you've grasped its rules, you can make the Apricot display sing, dance and cook Brown Windsor Soup.
The boring historical background is that the Apricot screen, like that of its ancestor the Sirius, has been set up to resemble something called a VT52 terminal... via software control. As with the famous editable keyboards and fonts, Apricot display handling isn't "hard-wired". Programmers don't need to know anything about how the video memory is arranged: the BIOS screen driver will handle all the fiddly details if sent the correct command via an escape sequence. (Incidentally, there are many more commands available to Apricot users than were defined in the old VT52 standard.)
"Sending" something to the screen simply means displaying it, as with BASIC's command PRINT, or Pascal's Write, or such MS-DOS commands as ECHO and TYPE. Sending special control characters is a legal fiction: you pretend you're displaying them, but in fact the BIOS nobbles them en route to the screen, and takes appropriate action rather than simply showing the relevant font character.
This is why the font characters with ASCII codes from 0 to 31 [hex 0 to 1F] -- the funny faces, playing-card symbols, musical notes, arrows, etc. -- are something of a snare. Normally, all are intercepted and treated as control characters, though only a few actually "do things":
Selected Control Characters
NAME ASCII FUNCTION beep or BEL 7 sound internal beeper backspace or BS 8 move cursor one space left tab 9 move cursor to next tab stop linefeed or LF 10 [0A] move cursor one line down return or CR 13 [0D] move cursor to left-hand column escape or ESC 27 [1B] signal escape sequenceNotes: A backspace at the beginning of a screen line will "reverse wrap" to the end of the previous line, except at the beginning of the screen. Tab stops fall at 8-space intervals, in columns 9, 17, 25, etc.; the tab code itself will not wrap to the next line at a line-ending, despite MS-DOS's misleading response to it. A linefeed on the last line of the screen will cause the whole screen to scroll up. Remember that a return alone doesn't move the cursor to a new line... but see the ESC x8 and ESC x9 controls under "Environment" below.
More esoterically, I find that characters 11 [0B] and 12 [0C] -- vertical tab and formfeed -- behave just like linefeeds on the Apricot. One possible relic of the Sirius is that on the Xi until the coming of BIOS 3.1, characters 14 [0E] and 15 [0F], otherwise known as SO and SI, feebly imitated their Sirius function of switching in and out a second character set: SO caused subsequent text output to appear as blanks until SI restored sanity.
Note the treatment of ASCII character code numbers: throughout this piece I'm giving the decimal value followed by the hexadecimal value in square brackets. Let's clarify the phrase "control character", too: character 7, BEL, is also known as Control-G or ^G, BS as Control-H or ^H, and so on. The ASCII codes correspond to letters of the alphabet (and even beyond: the ASCII character after Z is [, so we get ^[ for Escape), and special characters are traditionally generated by holding down the CONTROL key plus a letter key, so it makes a sort of sense.
But holding down CONTROL and pressing G in MS-DOS or a program does not send ^G to the screen and cause a beep. It merely sends ^G to the MS-DOS command interpreter or your program, which will have its own interpretation (many word processors including SuperWriter and WordStar take ^G to mean "delete current character", for example). Only when a program sends ^G to the screen does the beep occur. In MS-DOS you can achieve this with ECHO ^G, where the ^G is entered with CONTROL plus G as above.
This distinction also explains why I have not listed the famous Control-P which when typed at the DOS prompt turns on "echoing" to the printer. ^P is a command sent from the keyboard to the MS-DOS operating system (by holding down CONTROL and typing P). Screen controls are commands sent from a program (including MS-DOS itself) to the BIOS screen driver, and as a rule cannot just be typed in.
Getting ESC sequences to the Apricot screen
To invoke the special screen driver functions, we send Escape to the screen. This is straightforward except at the MS-DOS command line level, where the ESC key itself introduces some "special editing functions" which can be quite handy. They're buried deep in the MS-DOS manual: the most useful is ESC U (it must be a capital U), which repeats the previous command line. Keying ESC R inserts an ESC character: type ECHO followed by a space, then hit ESC and R to put in the ESC character ^[, and finally add the rest of your escape sequence....
As an example, let's take the simple escape sequence which when "displayed" clears the screen: ESC E. The ESC is received by the Apricot screen driver, and interpreted as meaning "Don't print the next character but execute the screen driver routine corresponding to its ASCII code."
From MS-DOS you could do it with the CLS command, but ESC E has an extra advantage over Apricot MS-DOS 2 -- it "homes" the cursor to top left. (This is standard in the COMMAND.COM supplied with MS-DOS 3.) ECHO ^[E, where the ^[ can be inserted by ESC R as above, or by your word processor's "insert control character" function, is a suitable batch file line for doing this.
(Note that ESC sequences involving the characters <, > or | -- the MS-DOS redirection operators -- cannot be sent to the screen using ECHO. But they can be put into a small text file and the file sent with TYPE.)
In MSBASIC programming it's worth defining a string to provide the ESC character: ESC$=CHR$(27). Then PRINT ESC$+"E"; will clear the screen. Since this is such a common function, you might as well simplify it further by defining a special string: CLS$=ESC$+"E", allowing you to PRINT CLS$; whenever you like.
GWBASIC doesn't permit you to use ESC sequences, alas: its graphics screen merely displays the font equivalents of control characters, such as a little left-pointing arrow for ESC.
Turbo Pascal allows much the same approach as MSBASIC: put "Escape=#27;" or "Escape=^[;" among the Constants, and in the main program "Write(Escape,'E');"... or define "ClearScreen = ^['E';" and Write that as required. This is a rotten example since Turbo has its own "ClrScr" function, but never mind.
In Assembler the temptation is to define sequences with such lines as "CLRSCR DB 27,'E$', and use the MS-DOS "print string" function call. Beware, though, the fact that the $ sign marks the end of a string! Not only is ESC $ an escape sequence in its own right, but we'll be meeting sequences which can include $ in their data parameters. It could be safer to send them character by character or to write your own simple string display routine. Here's a tiny Assembler screen-clear procedure:
CLR_SCREEN PROC NEAR ESC EQU 1BH ; define ESC CHAR_OUT EQU 29H ; MS-DOS "display character" interrupt ; (use Apricot's F1H if this needn't ; run on Xi BIOS 2.4 or earlier) MOV AL,ESC INT CHAR_OUT ; send ESC from AL MOV AL,'E' INT CHAR_OUT ; send E from AL RET ; return from procedure CLR_SCREEN ENDPAfter all those preliminaries, it's time to tackle the actual vast table of ESC sequences and their functions. The best approach seems to be to group them under logical headings rather than leave you to ferret through a listing in arbitrary order of ASCII number. I'll put in cross- references where they seem needed. Always consult the "Notes" before rashly inserting anything into a program... there are many variations and traps to watch for!
References to the Xi include the PC and Xen, and references to the F series include the Portable, except where specifically mentioned.
Several ESC sequences expect additional characters of data after the initial ESC and its single-character function code. I've represented data parameters by appropriate letters where possible: n or m for plain numbers, x and y for row and column co-ordinates, c for colour settings. There are opportunities for confusion here. Normally any following characters are interpreted as numbers, but must be sent as ASCII character codes. For example, ESC Qn scrolls the screen left by (n-32) columns. To scroll the screen left by 1 column we send ESC Q followed by 33... not two threes but the ASCII character whose code is 33 [21], being the exclamation mark. ESC Q! is the needed sequence.
But there are a few cases where a code needs to be sent "in ASCII form", whereby 1 refers not to character 1 but to character 49 [31], being the ASCII code for the digit 1. See for example the "program key" and "set screen mode" sequences. In these cases I've distinguished "ASCII-form" parameters with the letter a.
Remember that the first character of an ESC sequence (the second if you count ESC itself) will always be shown exactly as it should be sent. ESC n means ESC followed by "n" (ASCII character 110 [6E]), but ESC /n means ESC followed by "/" (47 [2F]) followed by any number n represented by the appropriate ASCII code.
Controlling the Cursor Position
See also the table of Control Characters, above. There are no ESC sequences which duplicate Backspace, Tab, Linefeed or Return.
ESC ; 59 [3B] move cursor to status line ESC A 65 [41] cursor up one line ESC B 66 [42] cursor down one line ESC C 67 [43] cursor right one space ESC D 68 [44] cursor left one space ESC H 72 [48] home cursor (to top left of screen) ESC I 73 [49] cursor up one line; scroll at top line (reverse line feed) ESC Yyx 89 [59] move cursor to position designated by y (row+32) and x (column+32): a 3-character sequence ESC h 104 [68] reverse tab, to previous tab stop ESC j 106 [6A] save current cursor position ESC k 107 [6B] restore previously saved positionNotes: The point of the status line, the 25th line of the Apricot screen, is that it isn't affected by other screen operations: it doesn't scroll out of sight, ordinary screen-clear commands don't affect it unless the cursor has previously been moved to the status line, and so on. It's the place to put semi-permanent information.
The ESC A-D codes are normally generated by the Apricot cursor keys (and ESC H by the HOME key). ESC A and B will not scroll the screen as do their counterparts ESC I and LF; ESC C and D will not "wrap" to the next or last lines. ESC C offers one oddity on certain F series BIOS versions -- it won't go all the way to the right-hand edge of a screen window (including the default screen) but stops one space short. Indeed, if the cursor is otherwise positioned at the right-hand edge and ESC C issued, it moves you one space left!
The normal status line is usually referred to as line 25 of the screen, but for the sake of logical consistency it seems wise to think like programmers and count from zero. Thus we number the screen rows from 0 to 24, the columns from 0 to 79. This makes the format for the ESC Y command easier to understand: we don't send the actual row and column number but add 32 to each, presumably to avoid the possible confusion of having to send control characters (0 to 31) as data. So ESC Y followed by two spaces (character 32 [20]) would move the cursor to row 0, column 0... the "Home" position. ESC Y will not move the cursor to the status line unless this line has previously been "enabled" -- see below, under "Environment".
As noted above, ESC Y commands which move the cursor to row and/or column 4 require the sending of character 36 [24], which is $. Beware of the MS-DOS "display string" function in Assembler.
ESC h should have no effect when issued at the beginning of a line, but does weird and wonderful things on certain F series graphics screens (e.g. F10 BIOS R1.6): the cursor can actually move to a position between lines.
"Home" is where ESC k will put the cursor if no previous position has been saved with ESC j. Each new ESC j saving of cursor position wipes out the previous one; only one can be stored. A useful multiple sequence: ESC j ESC ;Message ESC k will put the Message text on the status line without messing up the main screen cursor position. (But see the caveat under "Windows".)
Erasure and Deletion
The difference here is that erasing text equates to overwriting it with spaces, while deletion implies "closing up" the surrounding text. There is no "erase current character" escape sequence: sending a space to the screen performs this service. (Send a space followed by a backspace if you want the cursor position to be unchanged.)
ESC + 43 [2B] erase all high intensity characters (not F series) ESC - 45 [2D] erase all low intensity characters (not F series) ESC E 69 [45] clear screen and home cursor ESC J 74 [4A] erase from cursor position to end of screen ESC K 75 [4B] erase from cursor position to end of line ESC M 76 [4D] delete current line and scroll up any below ESC N 77 [4E] delete current character and close up from right ESC b 98 [62] erase from start of screen to cursor position ESC l 108 [6C] erase current line, preserve cursor position ESC o 111 [6F] erase from start of line to cursor position ESC z 122 [79] reset screen to "power-on" state and home cursorNotes: ESC + has a bug in BIOS 3.1 as supplied for MS-DOS 2.11, and clears low rather than high-intensity characters. (This bug reportedly vanished in BIOS versions supplied with MS-DOS 3.20.) It and ESC - are generally to be avoided, since their use requires that your program be completely rewritten for the F series.
ESC E has an important variation on the Xen: on other models, ESC E issued while the cursor is on the status line will simply clear the status line, but on the Xen it clears the main screen, leaving the status line untouched. This sequence is generated by the CLEAR key on an unmodified Apricot keyboard.
ESC M is supposed to reset the cursor to the left margin, but in BIOS 3.1 and most of the oddly-numbered F series BIOS variants doesn't: it's advisable to follow this sequence with a return for complete cross- compatibility. As with ESC E, ESC M fails when you try to use it to clear the Xen status line (a main-screen line vanishes instead). ESC l is the safest "generic" way to clear the status line once you're there.
ESC J, ESC K, ESC b and ESC o include the character at the cursor position in their destructive work, and do not move the cursor.
All these sequences work within the bounds of the current screen window only (see below), with the exceptions of ESC +, ESC - and of course ESC z. ESC z not only blanks the screen but homes the cursor, turns all special "attributes" off (see below) and generally clears everything you've done except for any saved "environment" (again, see below). Colour settings provide further exceptions: the overall display mode is unaffected, and likewise the "palette".
Inserting Text Characters and Lines
These functions are generally less useful than deletion and erasure, although ESC L is occasionally handy. The Apricot's normal "overwrite" mode is much easier to keep track of, especially since careless insertion of characters into a text line may mean the loss of characters at the right.
ESC @ 64 [40] set insert mode: text is henceforth shuffled right to make a space for each new character sent to the screen ESC L 76 [4C] insert blank line (scrolling rest of screen down) ESC O 79 [4F] turn off ESC @ insert mode ESC P 80 [50] insert character at cursor positionNotes: The ESC @ insert mode slows the display badly -- even when you're writing text into a "blank" line, the BIOS wastes time conscientiously moving spaces to the right and off the edge of the screen.
All About Text Attributes
Attributes refer to the way screen characters are presented: bright/dim, underlined, reverse video, etc. Thus when the "underline" attribute is set, all characters appear underlined until further notice. One pair of escape sequences I wish were included in the BIOS would be to save and restore the current attributes....
ESC ( 40 [28] set high intensity display ESC ) 41 [29] set low intensity display ESC 0 48 [30] set underline mode ESC 1 49 [31] turn off underline mode ESC 9 57 [39] set strikeout mode ESC : 58 [3A] turn off strikeout mode ESC _ 95 [5F] set current attributes over entire screen (see note) ESC p 112 [70] set reverse video mode ESC q 113 [71] turn off reverse video modeNotes: all these fail when "full-colour" display mode has been set on an F series monitor, but can be made available by switching to 2-colour "Xi monochrome compatibility"... see below, under "Colour". For the F series, "high" and "low" intensity mean not "bright" and "dim" but "thick" and "thin" characters, with the former usually being rather illegible.
Strikeout mode, with a horizontal line running through the text characters, is a concession to some American legal oddity whereby documents sometimes need to show supposedly struck-out text. Underline and strikeout on the Xi are dependent on the character font: the positions of these lines is separately set for each character via undisplayed font-cell bits, leading to messiness if (as in certain Apricot "Black Hole" fonts) these bits are misaligned or omitted.
ESC _ worked on the Xi only, was never very useful, and has been dropped as of BIOS 3.1. (Flipping the whole screen into reverse video with a single command was fun, but this effect was cocked up as soon as the screen was scrolled.)
The ESC z screen reset cancels all current attributes and leaves the display "dim"; ESC E and partial screen-clear functions leave attributes unchanged.
Windows, Scrolling, and Wrapping
ESC ,yYxX 44 [2C] set screen window size (top row y-32, bottom row Y-32, left column x-32, right column X-32) and home the cursor within the window ESC . 46 [2E] restore screen to default 80 columns and 24 rows (plus status line) and home cursor ESC Qn 81 [51] scroll current screen window LEFT by (n-32) columns ESC Rn 82 [52] as ESC Qn, but scroll RIGHT (n-32) columns ESC Sn 83 [53] as ESC Qn, but scroll UP (n-32) rows ESC Tn 84 [54] as ESC Qn, but scroll DOWN (n-32) rows ESC v 118 [76] wrap text at end of each line (default mode) ESC w 119 [77] don't wrap at the end of a lineNotes: When a window is set, the defined area of the screen is treated as being the whole screen for all purposes of display, scrolling, clearing, etc. An ESC z reset or (F series) ESC 7 colour mode change will however restore the default full-screen window. Only one window is allowed, though multiple non-overlapping windows can be handled by adroit juggling of ESC , commands. Neither the setting nor the resetting of windows erases any screen text, provided ESC z isn't used for resetting.
I've found ESC , one of the more dangerous screen controls in which to place your trust. In some BIOS versions, silly values for the parameters can hang up the computer... though the system is tolerant of over-large values for the right and bottom window edges, and will quietly set column 79 and/or row 23 when thus provoked (counting from zero, remember). Xi BIOS 2.4 (presumably along with earlier versions) gets the right-hand edge of the window wrong, making it one column narrower than specified. Some F series BIOS versions, like F10 R1.6, will not allow the setting of windows only 1 or 2 units either high or wide: the command merely homes the cursor in the existing screen.
Those parts of the screen outside the current window are generally inaccessible and inviolate: ESC E will clear only the interior of the window, ESC H will home the cursor to top left of the window, and so on. (See "Erasure and Deletion" above for some exceptions.) The BIOS tries to provide a status line for any window, accessible with ESC ; as usual, though such ad-hoc status lines can sometimes appear in odd places. Mark Fisher points out a bug here: if the window doesn't begin at the left edge of the screen, the command ESC ;Message tends to put the word "Message" at the left edge of the screen rather than of the status line (which is aligned with the window). This is curable by sending a Return to the screen immediately after the ESC ; command.
When using ESC Y to move the cursor within a window, you should still use "absolute" row and column numbers, counting from the true top-left corner of the screen -- not of the window. Attempts to position the cursor outside a window tend to leave it at the window's edge.
ESC Q/R/S/T: some Apricot documentation incorrectly states that the screen is scrolled by (n-31) rather than (n-32) units. Nothing at all happens when the character for n is a space (ASCII 32 [20]). These four functions scroll text harmlessly off one edge of the screen and introduce new, blank rows or columns at the opposite edge. See "Environment" for an additional control over the appearance of F series scrolling.
(Some of these Scroll commands can also gives effects which are off by a column or so, when older BIOS versions are used. Be wary.)
ESC v/w: "Wrapping" means that when a character has been printed at the end of a line, normally column 79, the cursor moves to the start of the next line (with screen scrolling if need be). With this feature turned off, the cursor "sticks" when it reaches the end of the line, and subsequent characters overwrite each other until a return and linefeed are issued, or wrapping is turned on again, or whatever.
Keyboard and Printer Specials
That "sending an ESC sequence to the screen" is merely a legal fiction can be most clearly seen from the fact that, at the whim of the BIOS, keyboard and printer functions can also be activated. Taking the keyboard first, we'll include all those ESC sequences which pop characters into the keyboard buffer, to be read by your program as though you'd typed them in yourself.
ESC $ 36 [24] put character at cursor position into keyboard buffer ESC 4anm 52 [34] program a key: 4-character sequence where a is "1", "2" or "3" to select normal, shift or control setting; n is the key code number; and m is the new character. ESC Z 90 [5A] "identify as VT52 terminal" by putting the enigmatic sequence ESC / K into the keyboard buffer so programs can read it ESC \n 92 [5C] put character n into keyboard buffer ESC n 110 [6E] report current cursor position to keyboard buffer in the format ESC Y yx (compare the "move cursor" sequence above) where y is row+32, x is column+32Notes: ESC 4 has been found particularly difficult by users. Two minor pitfalls: the first parameter "a" is not ASCII code value 1, 2 or 3 but ASCII character 1, 2 or 3 (49, 50 or 51 decimal), and the new character "m" may not be a control character in the ASCII range 0-31 [0-1F].
The major pitfall is the obscurity of Apricot's key numbering, which makes sense only on the Xi with MicroScreen. For the purposes of this command the keys are numbered as follows: HELP, UNDO, REPEAT, CALC, PRINT, INTR (alias INT), MENU and FINISH are numbered from 0 to 7. The six MicroScreen keys are 8 to 13. The rows of the keyboard proper go from 14 to 32 (\ to the calculator's +), 33 to 50 (TAB to 9), 51 to 68 (CAPS LOCK to 6: RETURN is counted in this group), 69 to 85 (SHIFT to 3) and 86 to 95 (ESC to ENTER). Later machines' VOICE key, though logically one of the function keys, had to be squeezed in at the end of this numbering as key 96: TIME/DATE, where present, is not part of the logical keyboard and cannot be programmed.
So to program the SHIFT position of the ENTER key to generate, say, an asterisk, you'd send ESC, then 4, then 2, then ASCII character 95 (underline) to indicate key number 95, and finally *.
To check the current cursor position with ESC n, you first send that sequence to the screen, then immediately read four characters from the keyboard buffer: the first two (ESC Y) can be discarded, while the third and fourth, after subtracting 32 from each, give row and column numbers respectively -- counting from 0,0 at top left.
The printer has fewer complications....
ESC & 38 [26] send whole screen to printer ESC ' 39 [27] send current screen line to printerNotes: ESC & is generated by the famous Apricot PRINT key, which should be used with SHIFT in BIOS 3.1 and later versions. Every character on the screen goes to the printer... but annoyingly, a formfeed character is sent first, so that if you're hand-feeding the printer, the paper will scroll out before printing begins. Hang on to it grimly, or try one of the BIOS patches suggested in my Apricot File Release 1.9 column.
ESC ' omits the formfeed and automatically starts a new line on the printer after sending the text.
Graphics, Fonts and Funny Characters
ESC *a 42 [2A] select font 0 (ESC *0), 1 (ESC *1) or 2 (ESC *2) ESC 8n 56 [38] ignore any control function of character n and print the appropriate font character ESC F 70 [46] turn on "VT52 graphics" mode ESC G 71 [47] turn off "VT52 graphics" mode ESC iyx 105 [69] display logo at stated position (see note) ESC } 125 [7D] set Xi graphics mode (50x25-cell screen)Notes: ESC *a (not on F series) allows instant swapping between two other fonts besides the default font 0 loaded at 0:800H. You need a bit of programming skill to take advantage of this, since Apricot has provided no explicit means of loading font 1 at 0:2800H, let alone font 2.
ESC 8n can be used to show any character but its only real point is to allow display of the normally inaccessible control characters in the ASCII code range 0-31. "VT52 graphics" (a misnomer -- not graphics at all) also allows oddball characters to be displayed, but mucks up the entire character set: ordinary text letters become unavailable, a high price to pay for the accessibility of characters 1 to 31 -- which in this mode appear when you try to display characters 95 to 125.
(Note that there's no displayable character in the default font corresponding to ASCII codes 0 (null) and 255.)
ESC iyx (not F series) displayed the attractive "Apricot" logo, or any other that you might have installed in the dear dead days of LOGOEDIT and SETUP, with its top left corner at a position calculated by interpreting the y and x parameters exactly as in ESC Y cursor positioning. The function being nifty, popular, and good for impressing punters, it was naturally dropped from BIOS 3.1.
I looked further into the possibilities of ESC } in an APRICOT FILE column subtitled "Graphics without GSX": see Release 1.6. Used alone, it makes a right dog's dinner of the Xi screen (MS-DOS doesn't sense that lines are now 50 rather than 80 columns wide, and puts its prompts in all sorts of weird places). A mildly interesting point is that the wider display cells allow you to see the normally invisible "underline" and "strikeout" position marker bits at the right of each character, looking like a slightly skewed colon.
Cursor Appearance, Environment Flags, and Twiddly Bits
ESC 2 50 [32] set flashing cursor on Xi (not F series) ESC 3 51 [33] turn off Xi flashing cursor ESC ` 96 [60] save "environment" (see below) ESC a 97 [61] restore saved environment ESC xa 120 [78] set environment flag a, where a is: G (71 [47]) reset screen palette (F series only) $ (36 [24]) set Apricot compatible mode (F series only) 1 (49 [31]) enable status line for ESC Y access 4 (52 [34]) set block cursor (Xi only) 5 (53 [35]) turn cursor off 8 (56 [38]) set auto LF on receipt of CR 9 (57 [39]) set auto CR on receipt of LF D (68 [44]) smooth screen scrolling (F series only) E (69 [45]) LCD contrast up (Portable) F (70 [46]) bell volume up (F series only) ESC ya 121 [79] reset environment flag a, where a is: 1 (49 [31]) disable status line for ESC Y access 4 (52 [34]) set underline cursor (Xi prior to BIOS 3.1) 5 (53 [35]) cursor on (cancels flashing cursor, if any) 8 (56 [38]) cancel auto LF on receipt of CR 9 (57 [39]) cancel auto CR on receipt of LF D (68 [44]) fast screen scrolling (F series only) E (69 [45]) LCD contrast down (Portable) F (70 [46]) bell volume down (F series only)Notes: ESC 2 has the side effect, on machines where it works at all, of turning the cursor on should it have been off.
ESC ` is supposed to save "the first three environment flags" for later restoration by ESC a. In theory these are Screen Palette, Xi Compatibility Status (F series only: see under "Colour") and Status Line Enable/Disable (all machines): this is why ESC xG "palette" appears oddly out of sequence in the above, because that's where Apricot's documentation puts it. In practice I find that some details of cursor appearance are also saved (whether it's on or off, and its "flashing" or "underline" status on the Xi prior to BIOS 3.1) and that the information is, unusually, preserved even through an ESC z screen reset.
ESC a can produce odd effects if invoked before ESC ` has been issued: the cursor may unexpectedly vanish, or become a flashing underline cursor where the machine and BIOS allow this....
The ESC x8 end ESC x9 sequences are occasionally useful when listing text files in offbeat formats (e.g. lines separated only with linefeeds and paragraph ends marked with solitary returns, as in SuperWriter). By forcing the screen to insert an automatic LF when it receives a CR, or vice versa, we can be sure of getting both (i.e. a properly set-up new line) even if only one is present.
ESC xD allows you to take advantage of the F series machines' graphics display, when particularly posh and leisurely effects are required: with "smooth scrolling" the screen will scroll by much tinier vertical steps, individual graphics lines rather than whole text lines. Horizontal scrolling isn't affected.
ESC xE and ESC yE are produced by the Portable key combinations which let you adjust the liquid crystal display contrast from the keyboard.
ESC xF and ESC yF don't seem to make the slightest change to the bell volume of my F10, and I can't help wondering whether this facility is restricted to, say, the Portable.
The Calculator and PC/Xi/Xen MicroScreen
ESC /n 47 [2F] turn on MicroScreen LED lights in pattern "n" ESC < 60 [3C] display date and time on MicroScreen ESC ? 63 [3F] activate built-in calculator ESC U 85 [55] turn on dual output to MicroScreen ESC V 86 [56] turn off dual output to MicroScreen ESC W 87 [57] send display output to MicroScreen only ESC c 99 [63] disable MicroScreen scrolling ESC d 100 [64] enable MicroScreen scrolling ESC e 101 [65] turn MicroScreen cursor on ESC f 102 [66] turn MicroScreen cursor off ESC g 103 [67] disable MicroScreen time/date display ESC r 114 [72] enable MicroScreen echoing of main display output ESC s 115 [72] disable MicroScreen echoing (restores date/time)Notes: ESC /n turns on a pattern of LEDs corresponding to the binary representation of the character x. For example, ESC /? will turn all six lights on: character 63 (?) is 111111 in binary. ESC /@ will turn them all off again: character 64 (@) is 1000000, and only the last six binary digits are important....
ESC ? is generated as a "local" -- sent straight to the display -- sequence by the CALC key (SHIFTed position in later BIOS versions). Apricot have thoughtfully not provided an explicit ESC sequence for turning the calculator off again.
ESC U and ESC r slow main screen handling disastrously.
The Colour Supplement (F series, mostly)
To begin with, here's the basic table of colours. Although ASCII decimal and hex codes are given, these aren't escape sequences -- just values which can be used in ESC 5, 6 and ] sequences below. The palette and colour codes may look just the same, but read on....
DEFAULT COLOUR COLOUR COLOUR PALETTE CODE ASCII INDEX VALUE 0 Black 0 48 [30] 1 Blue 1 49 [31] 2 Green 2 50 [32] 3 Cyan 3 51 [33] 4 Red 4 52 [34] 5 Magenta 5 53 [35] 6 Brown 6 54 [36] 7 Light Grey 7 55 [37] 8 Dark Grey 8 56 [38] 9 Light Blue 9 57 [39] : Light Green : 58 [3A] ; Light Cyan ; 59 [3B] < Light Red < 60 [3C] = Light Magenta = 61 [3D] > Yellow > 62 [3E] ? White ? 63 [3F]In ESC ]ac below, "c" for "colour" can be any of the 16 available colour codes from the table. But there is a complication. "Set foreground colour" and "set background colour" do not directly set a colour code: they set a palette index, as shown on the left of the table. The foreground colour is normally palette code 1 and the background is palette code 0.
The codes for colour values are reliable, but the palette index values are dodgy in the extreme. They can be reset as explained below; different background and foreground defaults may well have been read from your boot disk's "label" sector; and the sixteen apparently available palette codes are in fact telescoped down to the number of colours currently allowed. For example, in the normal 80-column, 2-colour display (Xi compatible) with black and white as palette codes 0 and 1 (background and foreground), then attempting to use palette codes 2, 4, 6 etc. will give black while 3, 5, 7 etc. give white. You can change the palette setting with ESC ] but are limited to two on-screen colours... or more if multi-colour display is set with ESC 71.
The overall message: don't rely on default palette codes, and always use ESC ] to ensure that the colours you want are available.
ESC 5a 53 [35] set foreground colour to palette code a ESC 6a 54 [36] set background colour to palette code a ESC 7a 55 [37] set screen colour mode according to a: 0 (ASCII 48 [30]) 80 column 2-colour display on F machines, 80 column liquid crystal display on Portable, both with Xi monochrome compatibility 1 (ASCII 49 [31]) 80 column 4-colour display on F machines, 8 colour on Portable 2 (ASCII 50 [32]) 40 column 4-colour display on F machines, 40-column LCD on Portable 3 (ASCII 51 [33]) 80 column 2-colour display as mode 0 on F machines, 80 column 2-colour display on Portable ESC ]ac 93 [5D] set palette code a -- an ASCII from 0 (ASCII 48 [30]) to ? (63 [3F]) -- to colour value c: e.g., in a default 2-colour screen ESC ]01 could set a blue background, ESC ]18 a light grey foreground, and so on depending on the number of colours available in the paletteNotes: As with Attribute settings, the foreground and background selected with ESC 5 and ESC 6 will be the default for future character output until further notice. Changing foreground and background this way requires the setting of multi-colour mode with ESC 71: it's more reliable to control foreground and background by changing palette indexes 0 and 1 with ESC ]. Example: ESC ]04 sets a red background by changing palette colour 0 to red.
ESC 7 can cope with Portables having two monitors, both LCD and colour -- it seems that ESC 70 selects LCD and turns off the colour display cursor, ESC 72 selects 40-column LCD similarly, and ESC 73 allows a dual LCD and colour display with the LCD cursor turned off. "Turning off the cursor" here means, euphemistically, turning off screen output.
ESC 7 commands also reset screen windowing and home the cursor.
Note that the ESC 71 multi-colour display setting disables the Xi- compatible attribute controls: underline, bright/dim, inverse video, etc.
Interesting effects can be obtained from "grey-scale" colour selection on many monochrome F series machines. It's fun to experiment with this: pretend it's a colour monitor and see what effects colour change controls produce. You can find background/foreground combinations which are easier on the eye than the default setting.
ESC ] palette changes will retrospectively alter the screen colour appearance, very quickly: without changing the palette codes which have been set in various parts of the screen (like character attributes), it lets you instantly change their meaning.
ESC xG -- from "Environment" above -- instantly restores a standard default palette.
ESC z screen resetting doesn't change the palette, nor the current screen colour mode as set with ESC 7, but it does reset the background and foreground colours to those set in palette codes 0 and 1 (if they've been changed with ESC 5 and/or ESC 6).
Miscellaneous
ESC [ 91 [5B] lead-in for ANSI escape sequence ESC | 124 [7C] not officially used, but turns on the compressed text mode of the "Black Hole" 132-column screen driver when this is installed on the XiNotes: ANSI escape codes are not covered here because the article is too long already. (But see my last Apricot File column.) Essentially they are cumbersome (having been devised by an American committee) ways of doing some of the things the VT52 codes do more efficiently. For example, "clear screen" translates from ESC E to the ANSI ESC [2J. More recent versions of the Apricot BIOS support ANSI codes with a vague eye to "IBM compatibility"... but Peter Norton's authoritative books on IBM programming strongly discourage use of these codes because (a) such programs will only run when the optional ANSI.SYS device driver has been installed on the IBM, an extra and intimidating setting-up step for inexperienced users; (b) ANSI.SYS operations are terribly slow. IBM programmers tend to use specialist BIOS interrupts or direct hardware access even for simple things like screen clearing: hence the general non-portability of major IBM programs to Apricot format, and the very limited success of Apricot's "IBM emulator". (On the other hand, it's quite possible to write an Apricot emulator for IBM compatibles: I know this because I've written one.)
Finally, some snares, delusions and officially inoperative sequences:
ESC # 35 [23] once documented as "send screen to keyboard buffer" ESC % 37 [25] originally documented for Xi as "send current line", but has never worked ESC X 88 [58] Sirius line-moving command, never available for the Apricot: swapped the current screen line for one held in an internal buffer ESC ] 93 [5D] originally documented for Xi as "send status line" but never actually worked (see under "Colour" above) ESC _ 95 [5F] originally documented for Xi as "toggle debug mode" whereby "hex codes for print stream" were supposed to appear as if by magic on the status line -- but see "Attributes" above for what it actually did ESC manm 109 [6D] originally documented for Xi as "set size": if a was "1", n-32 and m-32 supposedly set width and height for individual character cells; if a was "2", n-32 and m-32 set top and bottom lines for the screen; neither seems ever to have worked, though the second function is available in ESC , windowing ESC { 123 [7B] originally documented for Xi as "disable keyboard" ESC } 125 [7D] originally documented for Xi as "enable keyboard" ESC £ 156 [9C] representative of several ESC n codes (where n was a character with ASCII value above 127 [7F]) which used to crash the Xi: as of BIOS 3.1 they tend merely to make the cursor vanish until another character is sentNotes: In earlier, bug-ridden versions of David Langford, ESC # was said to crash the Xi. While checking ESC sequences for this article, I found that this must have been one of those common keyboard/printer confusions: the black spot should have been handed to ESC £.
"Originally documented for Xi" codes are often Sirius controls which never got implemented on the Apricot. Inoperative escape sequences are generally harmless, and this also applies to those not applicable to the current machine: for example, you can try to program a MicroScreen key on an F series machine and there will be no effects or complaints.
Final Credits
DIRECTOR: Dennis Jarrett of Apricot File mercilessly bullied me into writing this. GAFFER: Friedman Wagner-Dobler wrote the aeons-old "Complete Escape Codes" article in 16 BIT COMPUTING, a good survey but now partly superseded by countless, increasingly horrible, Apricot hardware and BIOS releases. CHIEF GRIP: I suppose Roger Gann has to get a mention somewhere. BEST BOY: Mark Fisher and John O'Harrow of Gateway Users gave freely of their wisdom. ADDITIONAL DIALOGUE: several hundred Ansible Information customers gleefully pointed out program bugs caused by my early failure to research all the BIOS variations noted above; there are doubtless more, still lurking in ambush....