Up: Classes   [Index]

ANSITerminalStream

ANSITerminalStream Class

ANSITerminalStream objects and their methods provides basic I/O capabilities for consoles that use standard input and output input, as well as serial terminals.

ANSITerminalStream also provides basic input translation and output formatting for ANSI, VT100, XTerm, and similar terminal types.

ANSITerminalStream does not provide curses-like screen buffering methods. The class’s output methods output characters correctly whether the terminal is in canonical or raw mode.

If a program sets the terminal to raw mode (either with the rawMode or getCh methods), it should also output characters with printOn, and restore the terminal before exiting, as this example illustrates. 

int main () {
  ANSITerminalStream new term;
  Character new c;

  term rawMode;
  term clear;
  term gotoXY 1, 1;

  while ((c = term getCh) != EOF)
    term printOn "%c", c;

  term restoreTerm;
}

If a program needs to handle cursor and other non-alphanumeric keys, then it must open the TerminalStream input queue (with the openInputQueue method) and read input events. See TerminalStream.

At present, Ctalk recognizes the following input event classes. 

KBDCHAR        # ASCII Characters
KBDCUR         # Cursor Keys.

When reading an InputEvent (with nextInputEvent in TerminalStream class), the event class is stored in the eventClass instance variable of the InputEvent object.

Here is an example of a program that opens a terminal input queue and reads characters by retrieving input event objects from the queue. 

int main () {
  ANSITerminalStream new term;
  Character new c;
  InputEvent new iEvent;

  term rawMode;
  term clear;
  term cursorPos 1, 1;
  term openInputQueue;

  while ((c = term getCh) != EOF) {
    iEvent become (term nextInputEvent);
    if (iEvent eventClass == KBDCHAR) {
      term printOn "<KEY>%c", iEvent eventData;
    }
    if (iEvent eventClass == KBDCUR) {
      term printOn "<CURSOR>%c", iEvent eventData;
    }
  }
}

Because ANSITerminalStream objects wait until the user has typed a key, programs can read input events synchronously, but programs that use other input stream classes may read the input queue asynchronously.

Newly created ANSITerminalStream objects use standard input and standard output as their file streams. Programs that read and write to serial terminals can open the terminal’s serial line with openOn, and set the communication parameters with setTty, as in this example. 

int main () {
  ANSITerminalStream new term;
  SystemErrnoException new s;

  term openOn "/dev/ttyS1";
  if (s pending)
    s handle;

  term setTty 9600, 8, N, 1;
  term printOn "Hello, world!\r\nHello, world!\r\n";
  term closeStream;
}

However, programs also need to take note of the differences between xterms, console displays, and serial terminals. For example, some serial terminals won’t send an ‘ESC’ (0x1b hex) character until another character is typed at the terminal to flush the terminal’s output. Also, programs should not depend on a particular terminal’s newline translation protocol, and some terminals echo tab characters without special configuration. Some terminal parameters are tunable in the ANSITerminalStrea class, but if a program needs special character handling, you may need to write a subclass of ANSITerminalStream for a particular terminal.

Instance Variables

inputHandle

A ReadFileStream object that contains the terminal’s input stream. The handle is initialized to standard input when the ANSITerminalStream object is created. Also refer to the information for outputHandle, below.

outputHandle

A WriteFileStream object that contains the terminal’s output stream. The handle is initialized to standard output when the ANSITerminalStream object is created. Programs can use the methods openOn and setTty (below), to open and configure handles for serial terminals.

In practice, objects that are instances of ANSITerminalPane and its subclasses use the inputHandle stream for both input and output with serial terminals, but programs can configure ouputHandle independenly if necessary.

queueInput

True if queueing input events.

rawModeFlag

True if the terminal stream parameters are set to raw mode.

termioCIFlag
termioCOFlag
termioCLFlag
termioCCFlag

Terminal settings. These variables are set with the current terminal parameters when creating an ANSITerminalStream object with new, and restored by the restoreTerm method.

ttyDevice

A String containing the path terminal’s device file, if different than stdinStream and stdoutStream. This variable is currently unused.

Instance Methods

clear (void)

Clear the terminal stream.

closeStream (void)

Close a terminal stream that was previously opened with openOn, below.

cursorPos (int row, int column)

Set the cursor position to row, column. The upper left-hand corner of screen is 1,1.

getCh (void)

Get a character from the terminal without echoing it. This method handles C-c, C-d, and C-z control characters by exiting. This method calls rawMode, so the application must call restoreTerm before exiting.

gotoXY (int row, int column)

Set the cursor position to row, column. The upper left-hand corner of screen is 1,1. This method is a synonym for cursorPos, above.

new (stream1, stream2, ... streamN; )

Create one or more new ANSITerminalStream objects and initialize their input and output handles to stdinStream. See ReadFileStream, and stdoutStream. See WriteFileStream. For example, 


ANSITerminalStream new stream1, stream2;
openInputQueue (void)

Begin queueing input events. See InputEvent.

openOn (char *tty_device_name)

Open a tty device for the receiver.

printOn (char *fmt, ...)

Print the formatted output to the receiver’s output stream.

rawMode (void)

Set the terminal input and output streams to raw mode.

readChar (void)

Read a character from the receiver’s input stream.

readLine (void)

Read a line of text from the receiver’s input stream and return a String object with the text.

restoreTerm (void)

Restore the terminal parameters to the values when the ANSITerminalStream object was created. Applications must call this method after using the getCh and rawMode methods, or the terminal may be unusable after the the application exits.

setGraphics (char attribute)

Set the graphics attribute for the following characters. The attribute argument can be one of the following characters. 

0       Attributes Off
1       Bold
4       Underscore
5       Blink
7       Reverse
setTty (int speed, int data_bits, char parity, int stop_bits)

Set the communication parameters of a terminal device opened with openOn, above.

Up: Classes   [Index]