Introduction:
The TermCanvas (later just called 'canvas') widget is the actual screen 
output / keyboard input section of emu. 
It manages a virtual screen (later just called 'screen') of configurable 
size plus a area where text which scrolls off the top of the screen is stored 
(the 'save area').
The canvas supplies a text cursor (the 'cursor') of configurable size and
blink rate.

-------------------------------------------------------------------------
Actions:
The canvas supports the following actions:

focus-in()
Should be called when the widget gets the input focus. 
The cursor shape changes to solid, it optionally starts blinking.

focus-out()
Should be called when the widget loses the input focus. 
The cursor shape changes to outline, optionally blinking stops.

key-input([<string>])
Called without argument it will translate the KeySym that caused the
action to a Latin-1 String. If Mod1 is pressed with the Key, the highest
Bit of each character of the resulting string gets set to allow traditional
recognition of the Meta Key. The resulting string is sent to the reverse
parser. With a argument use this string instead.

select-start()
Start selecting at the position of the mouse cursor.

select-extend()
Extend the selection to the current mouse cursor position.

select-end()
End selecting and transform the selection into a string for later retrieval.

insert-selection()
Retrieve the selection and send it to the reverse parser

call-parser(<opcode>, <buffer>, [<register>, <value>], ...)
Calls the reverse parser with the specified opcode and buffer (if you don't
need the buffer just provide '""'). If register - value pairs are provided
it sets the registers accordingly.

call-canvas(<opcode>, <buffer>, [<register>, <value>], ...)
Executes the specified opcode in the canvas. The buffer and any supplied
registers are set accordingly.

-------------------------------------------------------------------------
Character Attributes:
The following character attributes are defined in 'include/xt_ops.h'.
They can be ored together:

ATT_NONE	normal text - using 'screen.font'
ATT_BOLD	bold text - using 'screen.boldFont'
ATT_UNDERL	underlined - 
		underline width can be set via 'screen.underlineWidth',
		default: 1 pixel wide
ATT_BLINK	blinking - 
		blink rate can be set via 'textBlinkInterval', default: 500 ms
ATT_REVERSE	reverse text - background and text colors are exchanged.


-------------------------------------------------------------------------
List of supported functions:
The following functions are recognized by the canvas. The constants are
defined in 'include/xt_ops.h'.
Data is exchanged via the given com-block.

Basic character insertion:
OP_INSERT		buffer = String to insert

Cursor movement:
OP_MOVE_ABS		x = column, y = line
OP_MOVE_REL		x = delta column, y = delta line
OP_MOVE_ABS_COLUMN	x = column
OP_MOVE_ABS_ROW		y = line
OP_MOVE_REL_COLUMN	x = delta column
OP_MOVE_REL_ROW		y = delta line
OP_MOVE_REL_ROW_SCROLLED y = delta line

Write modes:
OP_INSERT_MODE		no args
OP_OVERWRITE_MODE	no args

Deleting and erasing:
OP_DELETE_CHARS		a = number of characters to delete
OP_DELETE_TO_EOL	no args
OP_DELETE_LINES		a = number of lines to delete
OP_DELETE_TO_EOSCR	no args
OP_ERASE_CHARS		a = number of characters to erase
OP_ERASE_LINE_LEFT	no args
OP_ERASE_LINES		a = number of lines to erase
OP_ERASE_FROM_TOSCR	no args
OP_CLEAR_SCREEN		no args

Inserting:
OP_INSERT_LINESS	a = number of lines to insert

Define the scrolling region:
OP_SET_SCROLL_REGION	a = start line, b = end line

Ring the bell:
OP_RING_BELL		no args

Tab handling:
OP_HOR_TAB		no args
OP_SET_TAB_CUR_COL	no args
OP_SET_TAB_COL		x = column
OP_SET_TABS_EQ_WIDTH	a = distance
OP_CLEAR_TAB_CUR_COL	no args
OP_CLEAR_TAB_COL	x = column
OP_CLEAR_ALL_TABS	no args

Character Attributes:
OP_SET_ATTRIBUTE	a = attribute(s)
OP_CLEAR_ATTRIBUTE	b = attribute(s)

Changing the Keyboard Translations e.g. for different Codes on the
Cursor Keys and Number Keys depending on the Keyboard mode:
OP_OVERRIDE_TRANSLATIONS a = number

Change the FLUT e.g. for different character set:
OP_CHANGE_FLUT		a = number

Reports from the canvas to the parser for further use in the parser.
They all have no arguments, the canvas however fills the comblock with data:
OP_CANVAS_SIZE		return x = columns, y = lines
OP_CANVAS_CURSOR_POS	return x = column, y = line
OP_CANVAS_ATTRIBS	return a = attributes
OP_CANVAS_SCROLL_REGION	return a = start line, b = end line
OP_CANVAS_WRAP_MODE	return a = boolean flag
OP_CANVAS_REVERSE_MODE	return a = boolean flag
OP_CANVAS_CURSOR_ON	return a = boolean flag
OP_CANVAS_CURSOR_BLINKING return a = boolean flag
OP_CANVAS_CURSOR_SIZE	return x = width, y = height in pixels

Redraw the screen:
OP_REDRAW_SCREEN	no args

Change the current fonts:
OP_CHANGE_FONTS		a = normal font, b = bold font

Scrolling the screen and the saved area:
OP_SCROLL_SCREEN_ABSOLUTE a = save line to scroll to
OP_SCROLL_SCREEN_RELATIVE a = number of lines to scroll

General mode settings:
OP_CURSOR_OFF		no args
OP_CURSOR_ON		no args
OP_SET_SCREEN_SIZE	no args
OP_WRAP_AROUND		no args
OP_DONT_WRAP		no args
OP_CURSOR_POS_REL_TO_SCR_REG no args
OP_CURSOR_POS_ABSOLUTE	no args
OP_REVERSE_VIDEO	no args
OP_NORMAL_VIDEO	no args
OP_SAVE_FLUT		no args
OP_RESTORE_FLUT		no args
OP_SET_CURSOR_BLINK	no args
OP_SET_CURSOR_SIZE	x = width, y = height in pixels


-------------------------------------------------------------------------
Explanation of the canvas functions:

OP_INSERT		buffer = String to insert
The text in the combolck's buffer is inserted at the current cursor position 
with the current attributes.
If insert mode is on, characters to the right and including the cursor 
position get shifted to the right.
If line-wrap mode is on characters exceeding the right border of the screen 
get wrapped to the next line.

OP_MOVE_ABS		x = column, y = line
Move the cursor to the absolute position given in register x and y. 
If the relative-positioning flag is set, the start line of the scroll-region 
is added to y and the cursor can't leave the scroll region. With the flag off 
the cursor CAN leave the scroll region.

OP_MOVE_REL		x = delta column, y = delta line
Move the cursor relative to the current position by the amount of rows and 
columns given in register x and y. 
The cursor CANNOT leave the scroll region.

OP_MOVE_ABS_COLUMN	x = column
Move the cursor to the absolute column given in register x on the current line.
		
OP_MOVE_ABS_ROW		y = line
Move the cursor to the absolute row given in register y on the current column.
Rules for positioning relative to the scroll region and leaving the region 
apply as in OP_MOVE_ABS.

OP_MOVE_REL_COLUMN	x = delta column
Move the cursor relative to the current position in the current row. 
The delta is given in register x.

OP_MOVE_REL_ROW		y = delta line
Move the cursor relative to the current position in the current column. 
The delta is given in register y. The cursor CANNOT leave the scroll region.

OP_MOVE_REL_ROW_SCROLLED y = delta line
Move the cursor relative to the current postion in the current column.
The delta is given in register y. If the cursor would leave the scroll region,
the text inside the region gets scrolled accordingly.

OP_INSERT_MODE		no args
Turn insert mode on (no args).

OP_OVERWRITE_MODE	no args
Turn overwrite mode on - insert mode off (no args).

OP_DELETE_CHARS		a = number of characters to delete
Delete characters in the current line starting at the cursor position. 
The number of characters to be deleted is specified in register a. 
Characters to the right of the deleted ones get shifted to the left.

OP_DELETE_TO_EOL	no args
Delete characters in the current line from the cursor position up to the 
end of the line (no args).

OP_DELETE_LINES		a = number of lines to delete
Delete the number of lines specified in register a. The deleted area starts 
at the current line. Lines under the deleted area get scrolled up. 
This action is restricted to the scrolling region. 
The cursor is set to the left border of the screen.

OP_DELETE_TO_EOSCR	no args
Deletes all characters after the cursor till the end of the screen (no args).

OP_ERASE_CHARS		a = number of characters to erase
Erase characters in the current line starting at the cursor position. 
The number of characters to be erased is specified in register a.

OP_ERASE_LINE_LEFT	no args
Erases characters from the beginning of the current line to and including 
the cursor position (no args).
		
OP_ERASE_LINES		a = number of lines to erase
Erases the number of lines specified in register a.

OP_ERASE_FROM_TOSCR	no args
Erases characters from the top of the screen to and including the 
cursor position (no args).

OP_CLEAR_SCREEN		no args
Clears the whole screen (no args).

OP_INSERT_LINESS	a = number of lines to insert
Inserts the number of lines specified in register a at the current line.
This operation is restricted to the scroll region.
The cursor is set to the left border of the screen.

OP_SET_SCROLL_REGION	a = start line, b = end line
Sets the scoll region to start at the line specified in register a, 
and end at the one specified in register b.

OP_RING_BELL		no args
Calls 'XBell' with the volume specified in the resource bellVolume 
(default is 100%) - no args.

OP_HOR_TAB		no args
Move the cursor to the rightnext tab in the current line. 
If there is no tab right of the cursor puts it to the right border of 
the screen (no args).

OP_SET_TAB_CUR_COL	no args
Sets a tab stop at the current column (no args).

OP_SET_TAB_COL		x = column
Sets a tab stop at the column specified in register x.

OP_SET_TABS_EQ_WIDTH	a = distance
Sets up tabs with a distance specified in register a.

OP_CLEAR_TAB_CUR_COL	no args
Clears a tab stop at the current column (no args).

OP_CLEAR_TAB_COL	x = column
Clears a tab stop at the column specified in register x.

OP_CLEAR_ALL_TABS	no args
Clears all tabs (no args).

OP_SET_ATTRIBUTE	a = attribute(s)
Sets the attributes given in register a (more than one can be ored together).

OP_CLEAR_ATTRIBUTE	b = attribute(s)
Clears the attributes given in register b (more than one can be ored together).

OP_OVERRIDE_TRANSLATIONS a = number
Retrieves the resource '<term-type>-auxTrans-<number> and overrides the 
current translations with the resource. <number> is given in register a.

OP_CHANGE_FLUT		a = number
Retrieves the resource '<term-type>-flut-<number> and changes the flut 
according to the info found there. <number> is given in register a, 
register b specifies the offset in the flut to use.	

OP_CANVAS_SIZE		return x = columns, y = lines
The canvas sends back its size in registers x and y.

OP_CANVAS_CURSOR_POS	return x = column, y = line
The canvas sends back the current cursor position in registers x and y.

OP_CANVAS_ATTRIBS	return a = attributes
Send back the current attribues in register A (all ored together).

OP_CANVAS_SCROLL_REGION	return a = start line, b = end line
Send back start- and end line of the scroll region in registers a and b.

OP_CANVAS_WRAP_MODE	return a = boolean flag
Report in register a whether line wrap mode is on.

OP_CANVAS_REVERSE_MODE	return a = boolean flag
Report in register a whether the canvas screen is in reverse video.

OP_CANVAS_CURSOR_ON	return a = boolean flag
Report in register a whether the cursor is visible.

OP_CANVAS_CURSOR_BLINKING return a = boolean flag
Report in register a whether the cursor is blinking.

OP_CANVAS_CURSOR_SIZE	return x = width, y = height in pixels
Send back the current cursor size in register x and y.

OP_REDRAW_SCREEN	no args
Clears the screen and totally redraws it.

OP_CHANGE_FONTS		a = normal font, b = bold font
Changes the current fonts to the names given in registers a - normal, 
and b - bold. The fonts only get installed when they are both of the same size.

OP_SCROLL_SCREEN_ABSOLUTE a = save line to scroll to
Viewing the save area and the actual screen as continuous lines with line 0
being the beginning of the actual screen, numbering the save area negative
upwards, this function places line -a at the top of the screen (0 thus re-
presenting the normal case with only the actual screen showing).

OP_SCROLL_SCREEN_RELATIVE a = number of lines to scroll
Scrolls save area and actual screen a lines down (negative a results in
scrolling upwards).

OP_CURSOR_OFF		no args
Switches cursor off (no args).

OP_CURSOR_ON		no args
Switches cursor on (no args).

OP_SET_SCREEN_SIZE	no args
Sets the screen size to the values given in registers x and y.

OP_WRAP_AROUND		no args
Turns line wrap around on (no args).

OP_DONT_WRAP		no args
Turns line wrap around off (no args).

OP_CURSOR_POS_REL_TO_SCR_REG no args
Makes cursor positioning relative to the scroll region (no args).

OP_CURSOR_POS_ABSOLUTE	no args
Makes cursor positioning absolute (no args).

OP_REVERSE_VIDEO	no args
Puts canvas in reverse video (no args).

OP_NORMAL_VIDEO	no args
Puts canvas in normal video (no args).

OP_SAVE_FLUT		no args
Saves the current flut. Only one flut can be saved at a time, subsequent 
calls will overwrite the previous saved flut (no args).

OP_RESTORE_FLUT		no args
Restores flut to the last saved value (no args).

OP_SET_CURSOR_BLINK	no args
Depending on the value in register a, cursor blinking gets turned on or off.

OP_SET_CURSOR_SIZE	x = width, y = height in pixels
Sets the cursor size to the values in registers x and y.
