Position the "text" cursor and optionally print a string on the active display screen.

 

CHAR is intended for printing text on a bitmap.  This is needed in BASIC because the KERNAL can only render to a text screen. However, CHAR can be used with the text screen too.  Although PRINT is more versatile for the text screen, the advantage of CHAR is you can position the cursor anywhere in the active window.  In fact, it is common to use CHAR soley to re-position the text cursor and then use PRINT to display desired text.

 

If any bitmap is displayed, CHAR will render to the bitmap.  This is true even if the active editor is the 80-column text display.  Otherwise CHAR will render to the active text display.

 

If colorSource is omitted, it defaults to one.  The colorSource is ignored in text mode, but it still must be a Legal Value (0 or 1).

 

In bitmap mode, colorSource selects which logical color (see COLOR) will be used for plotting bitmap pixels from the foreground pixels of the font.  The background pixels of the font are also plotted but the color on the bitmap is not updated.  This means CHAR will draw the active pixels in a font using the current chipColor assigned to colorSource and the background pixels of the font will also be written to bitmap, but the current chipColor assigned to the background will not be used; the bitmap will have the same background color as before.  Because CHAR draws the background pixels of the font, you can not merge two characters.  For example, drawing an "S" and a "|" to the same location will not produce a "$" but the last character drawn (a "|" in this example).

 

The column and row are required.  They are 0-based character ordinates and set the location of the "text" cursor where printString will start.  When rendering to a bitmap, the values still (unfortunately) specify a character coordinate (instead of a more versatile pixel coordinate).  In this case, the position of the real text cursor is not changed.  Unlike other bitmap-drawing commands, CHAR does not update the pixel-cursor and SCALE has no effect.

 

In v7.0 text mode, the values of column and row are logical ordinates; that is, they are relative to the active window (if no window is currently defined, these are full-screen physical ordinates).

 

When rendering to a bitmap, physical text coordinates are used (as if the bitmap were actually a text screen); any active window is ignored (all verisions).

 

The printString is required in version 3.5.  You may use an empty string if you only want to re-position the text cursor.

 

CHAR will display the printString almost exactly like PRINT.  The main differences are:

Additional differences occur when rendering to a bitmap:

When rendering to a bitmap, the only control codes that work (and only in v7.0) are CHR$(14) to select the lower/upper (PETSCII) font, and CHR$(142) to select the upper/graphic (ASCII-X) font.  Using other control codes (or any control code in v3.5) will render the same character you would see in a quoted string in text mode, except the font will not be reversed.  For example, including the clear-screen character in printString would not clear the bitmap but display a heart (♥) instead.  On the C128, you can POKE secret variables to define where the default and alternate font definitions may be found (in BANK 14).

 

When rendering to a multi-color bitmap, the results won't look very pretty.  This is because the font ROM was not designed for multi-color mode.  I think BASIC does about the best that is possible with one color (whatever colorSource you select).  However using multiple colors (for example white, light gray, and dark gray) can give better results, but BASIC does not (directly) allow this.  If you could generate an optimized multi-color font somehow (like a paint program), then you could use GSHAPE to draw characters on the bitmap screen.  It would be much slower, but would look better.

 

The final parameter, reverse, will complement all bits in each byte plotted on a bitmap if reverse is an odd number.  The default value is zero.  Only values of 0 and 1 should be used; although other values work, they are an undocumented feature and are likely to cause problems with compilers, emulators, or expanded versions of BASIC.  In version 3.5, reverse has no effect in text mode.  In version 7.0, an odd reverse value when begin rendering printString in reverse font and set the font to normal (non-reverse) after rendering printString.

 

The original ROMs of the C128 (startup message says copyright 1985) contain a bug that can corrupt high BASIC RAM when plotting to the 80-column text screen.  Unless you can guarantee updated ROMs are in use, you should only use CHAR to position the text cursor when using the 80-column text screen.  However the corruption is harmless unless the program is very large (the end of the program is at/beyond $d600).

 

If any required parameter is omitted or an invalid expression, SYNTAX ERROR occurs.  If any parameter except printString is not numeric, TYPE MISMATCH ERROR occurs; you can use VAL to convert a string to numeric format.  If any parameter except printString is floating-point, it will automatically be converted with INT.  If the result is not a Legal Value (see table above) then an ILLEGAL QUANTITY ERROR occurs.  If printString is not a string expression, TYPE MISMATCH ERROR occurs; you can use STR$ to convert a number into a string.

  

Examples (text mode):

CHAR ,10,5,""   : REM position cursor to column 10, row 5
CHAR ,10,5      : REM same as above in v7.0 (error in v3.5) 
CHAR 1,0,0,"HI" : REM print "HI" at top-left corner
CHAR 0,0,0,"HI" : REM same as above (colorSource is ignored)
CHAR ,0,0,"HI",1 :REM in v7.0, "HI" will be in reverse font (normal in v3.5)

 

GSHAPE, LOCATE, MOVSPR, PRINT, TAB 

 

GET, GETKEY, EL, INPUT, INSTR, POS, RECORD, RDOT, RSPPOS, SSHAPE

 

CHR$, CMD, COLOR, GRAPHIC, SCALE, STR$, WINDOW