Carapace Emulator

The Carapace Emulator is a lightweight ActiveX control which displays Videotex. As an ActiveX control, the Emulator must be embedded in an OLE container before it can be used. For example, the Emulator can be placed on a web page and viewed using InternetExplorer -- Microsoft's web browser. For details, see Embedding the Emulator.

Carapace provides a stand-alone executable which contains the emulator ActiveX control.

The Emulator itself does not do any data communications. Instead, the Emulator uses a different object for its comms. See Emulator Communications Agent for details.

The Emulator is a simple character grid -- it contains rows and columns of cells where each cell:

holds a single character
has foreground and background colours (which can be 'bright' or 'dim')
has certain boolean flags ie. flashing, doubleHeight, hidden, mosaic

The Emulator displays this character grid to the user taking into account the particular cell attributes.

Emulator Creation

The Carapace Emulator is accessed using COM (or OLE as it used to be called!). The important identifiers for the Emulator are as follows:

ActiveX control name	`Carapace Emulator Control`
program id (progId)	`Carapace.Emulator`
class id (CLSID)	`E3F52F18-C297-11D3-81CA-0050048C7269`

An example showing Emulator creation when embedding in a web page is given here.

Emulator Properties

The following properties are accessible on the Emulator's primary dispatch interface:

property name	property type	description
`protocol`	String	name of the current protocol displayed by the Emulator -- currently, the only legal value is `Videotex`
`commsAgentId`	String	progId or CLSID of the agent used for the Emulator's communications -- default: `Carapace.EmulatorCommsAgent`. See Emulator Communications Agent for further details.
`commsAgent`	Dispatch	the dispatch interface of the Emulator Communications Agent
`flashInterval`	Integer	interval (milli-seconds) between flashing any appropriate screen cells -- the default is 500 milli-seconds
`cursorFormat`	String	the format for the cursor -- legal values are: `invert` - invert the colours for the cell containing the cursor `flash` - invert and flash the cell containing the cursor
`fontName`	String	the name of the font used by the emulator. The default value is `Courier New`. Another suitable font might be `Times New Roman` for instance. Look in the Window's Control Panel to see the names of fonts which you have installed.
`fontWeight`	Integer	the weight of the font used by the emulator. This is an integer between 0 and 1000. For example, 400 is normal and 700 is bold. If this value is zero, a default weight is used.
`printQuality`	String	the type of printing to perform on request -- legal values are: `draft` - basic black foreground/white background printing with no grey-scales `mono` - for use on a monochrome printer which supports grey scales `colour` - for use on colour printers

Emulator Methods

The methods offered by the Emulator can be partitioned as follows:

displaying information	displaying information 'on screen'
communications	managing the communications with the host
cursor control	moving the cursor around the screen
utility methods	various support methods

Display Methods

The following methods relate to the display of information on the Emulator's screen.

method name	description
`display`	display the supplied characters at the current cursor position -- the characters are assumed to be in the current protocol
`setText`	put text on screen at a given location
`setMosaics`	put a simple pattern on screen at a given location
`clearScreen`	clear the entire screen
`setColour`	set the colour attributes for the supplied cell
`setRowColour`	set the colour attributes for the remainder of the supplied row starting at the given column
`setRowOption`	set the boolean attributes for the remainder of the supplied row starting at the given column
`setAttributes`	set the attributes at the supplied position from the supplied encoding
`flash`	flash (ie. invert the colours of) all cells which have their 'flashing' attribute set

Communication Methods

The following methods relate to the communication with the host via the Emulator Communications Agent.

method name	description
`connect`	connect to the supplied host using the installed comms agent
`connectionState`	return the state of the current connection
`disconnect`	disconnect from the current host using the installed comms agent

Cursor Methods

The following methods relate to the screen cursor.

method name	description
`setCursor`	set the cursor position
`cursorOn`	enable the cursor - so it will be displayed to the user
`cursorOff`	disable the cursor - so it will not be displayed to the user
`up`	move the cursor up a row
`down`	move the cursor down a row
`left`	move the cursor back a column
`right`	move the cursor forward a column

Utility Methods

method name	description
`encode`	encode the entire display into a string form
`decode`	decode the entire display from the supplied string form
`execScript`	use the comms agent to execute the supplied Carapace script
`AboutBox`	display the standard dialog box which gives name and version information for the Emulator

`display`

Display the supplied characters at the current cursor position -- the characters are assumed to be in the current protocol.

Arguments:

characters String

Return type: the empty List ()

`setText`

Put text on screen at a given location. This does not affect the cursor position.

Arguments:

text	`String`
row	`Integer`
column	`Integer`

Return type: the empty List ()

`setMosaics`

Put a simple pattern on screen at a given location. Each screen cell can hold a simple pattern made of rectangular tiles -- a mosaic. A mosaic is 3 tiles high, and 2 tiles wide. The mosaic can be represented as 6 bits where a bit set means 'colour that tile'.

To make it easy to define the mosaic, this function setMosaics takes a string representation of a 6-bit binary number eg. "101011" which represents the following mosaic:


    10
    10
    11

Arguments:

bitPattern	`String`
row	`Integer`
column	`Integer`
length	`Integer`

Return type: the empty List ()

`clearScreen`

Clear the entire screen.

Arguments: none

Return type: the empty List ()

`setColour`

Set the colour attributes for the supplied cell.

The first argument (flag) defines which colour attributes are to be set as follows:

`0`	background
`1`	foreground
`2`	mosaic foreground

The second argument (colour) is the colour code as follows:

`0`	Black
`1`	Blue
`2`	Green
`3`	Cyan
`4`	Red
`5`	Magenta
`6`	Yellow
`7`	White
`8`	DarkGrey
`9`	Grey
`10`	LightGrey

Arguments:

flag	`Integer`
colour	`Integer`
row	`Integer`
column	`Integer`

Return type: the empty List ()

`setRowColour`

Set the colour attributes for the remainder of the supplied row starting at the given column.

The first argument (flag) defines which colour attributes are to be set as follows.

The second argument (colour) is the colour code.

Arguments:

flag	`Integer`
colour	`Integer`
row	`Integer`
column	`Integer`

Return type: the empty List ()

`setAttributes`

Set the attributes at the supplied position from the supplied encoding.

The attributes for a single cell are encoded as a 3-character string according to the following rules (where bits are numbered 0-7, with bit 7 being the most significant bit):

1st byte:

bit 0 - 3 holds the background colour
bit 4 is set if the cell background is 'bright'
bit 5 is set if the cell is a 'mosaic'
bit 6 is set if the cell is 'hidden'
bit 7 is set only if all the other bits are zero -- this just ensures the byte is non-null so that it does not terminate the string

2nd byte:

bit 0 - 3 holds the foreground colour
bit 4 is set if the cell foreground is 'bright'
bit 5 is set if the cell is 'double-height'
bit 6 is set if the cell is 'flashing'
bit 7 is set only if all the other bits are zero -- this just ensures the byte is non-null so that it does not terminate the string

3rd byte:

bit 0 is set if the cell text is 'bold'
bit 1 is set if the cell is not 'obscured'
bit 2 - 6 are not currently used
bit 7 is set only if all the other bits are zero -- this just ensures the byte is non-null so that it does not terminate the string

Arguments:

encodedAttributes	`String`
row	`Integer`
column	`Integer`

Return type: the empty List ()

`flash`

flash (ie. invert the colours of) all cells which have their 'flashing' attribute set.

Arguments: none

Return type: the empty List ()

`setCommsAgent`

Install the supplied object (dispatch interface) to act as the Emulator Communications Agent.

Arguments:

agent Dispatch

Return type: the empty List ()

`connect`

Connect to the supplied host using the installed comms agent. The address must be in a format which the agent understands.

Arguments:

address String

Return type: the empty List ()

`connectionState`

Return the state of the current connection. Possible return values are:

Disconnected
Connecting
Connected
Disconnecting

Arguments: none

Return type: String

`disconnect`

Disconnect from the current host using the installed comms agent.

Arguments: none

Return type: the empty List ()

`setCursor`

Set the cursor position.

Arguments:

row	`Integer`
column	`Integer`

Return type: the empty List ()

`cursorOn`

Enable the cursor - so it will be displayed to the user.

Arguments: none

Return type: the empty List ()

`cursorOff`

Disable the cursor - so it will not be displayed to the user.

Arguments: none

Return type: the empty List ()

`up`

Move the cursor up a row.

Arguments: none

Return type: the empty List ()

`down`

Move the cursor down a row.

Arguments: none

Return type: the empty List ()

`left`

Move the cursor back a column.

Arguments: none

Return type: the empty List ()

`right`

Move the cursor forward a column.

Arguments: none

Return type: the empty List ()

`encode`

Encode the entire display into a string form.

Arguments: none

Return type: the empty List ()

`decode`

Decode the entire display from the supplied string form.

Arguments:

data String

Return type: the empty List ()

`AboutBox`

Display the standard dialog box which gives name and version information for the Emulator.

Arguments: none

Return type: the empty List ()

`execScript`

Use the comms agent to execute the supplied Carapace script. An error is raised if no such agent is currently installed.

Arguments:

scriptCommands String

Return type: Object

Contents

Index

Current topic: communications

Related topics: communications classes, objects