jackpal.androidterm.emulatorview
Class TermSession

java.lang.Object
  extended by jackpal.androidterm.emulatorview.TermSession

public class TermSession
extends Object

A terminal session, consisting of a VT100 terminal emulator and its input and output streams.

You need to supply an InputStream and OutputStream to provide input and output to the terminal. For a locally running program, these would typically point to a tty; for a telnet program they might point to a network socket. Reader and writer threads will be spawned to do I/O to these streams. All other operations, including processing of input and output in processInput and write, will be performed on the main thread.

Call setTermIn(java.io.InputStream) and setTermOut(java.io.OutputStream) to connect the input and output streams to the emulator. When all of your initialization is complete, your initial screen size is known, and you're ready to start VT100 emulation, call initializeEmulator(int, int) or updateSize(int, int) with the number of rows and columns the terminal should initially have. (If you attach the session to an EmulatorView, the view will take care of setting the screen size and initializing the emulator for you.)

When you're done with the session, you should call finish() on it. This frees emulator data from memory, stops the reader and writer threads, and closes the attached I/O streams.


Nested Class Summary
static interface TermSession.FinishCallback
          Callback to be invoked when a TermSession finishes.
 
Constructor Summary
TermSession()
           
 
Method Summary
protected  void appendToEmulator(byte[] data, int offset, int count)
          Write something directly to the terminal emulator input, bypassing the emulation client, the session's InputStream, and any processing being done by processInput.
 void finish()
          Finish this terminal session.
 InputStream getTermIn()
          Get the InputStream associated with this session.
 OutputStream getTermOut()
          Get the OutputStream associated with this session.
 String getTranscriptText()
          Retrieve the terminal's screen and scrollback buffer.
 boolean getUTF8Mode()
          Get whether the terminal emulator is currently in UTF-8 mode.
 void initializeEmulator(int columns, int rows)
          Set the terminal emulator's window size and start terminal emulation.
 boolean isRunning()
           
protected  void notifyUpdate()
          Notify the UpdateCallback registered by setUpdateCallback that the screen has changed.
protected  void processInput(byte[] data, int offset, int count)
          Process input and send it to the terminal emulator.
 void reset()
          Reset the terminal emulator's state.
 void setColorScheme(ColorScheme scheme)
          Set the terminal emulator's color scheme (default colors).
 void setDefaultUTF8Mode(boolean utf8ByDefault)
          Set whether the terminal emulator should be in UTF-8 mode by default.
 void setFinishCallback(TermSession.FinishCallback callback)
          Set a TermSession.FinishCallback to be invoked once this terminal session is finished.
 void setTermIn(InputStream termIn)
          Set the InputStream associated with this session.
 void setTermOut(OutputStream termOut)
          Set the OutputStream associated with this session.
 void setUpdateCallback(UpdateCallback notify)
          Set an UpdateCallback to be invoked when the terminal emulator's screen is changed.
 void setUTF8ModeUpdateCallback(UpdateCallback utf8ModeNotify)
          Set an UpdateCallback to be invoked when the terminal emulator goes into or out of UTF-8 mode.
 void updateSize(int columns, int rows)
          Change the terminal's window size.
 void write(byte[] data, int offset, int count)
          Write data to the terminal output.
 void write(int codePoint)
          Write the UTF-8 representation of a single Unicode code point to the terminal output.
 void write(String data)
          Write the UTF-8 representation of a String to the terminal output.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

TermSession

public TermSession()
Method Detail

initializeEmulator

public void initializeEmulator(int columns,
                               int rows)
Set the terminal emulator's window size and start terminal emulation.

Parameters:
columns - The number of columns in the terminal window.
rows - The number of rows in the terminal window.

write

public void write(byte[] data,
                  int offset,
                  int count)
Write data to the terminal output. The written data will be consumed by the emulation client as input.

write itself runs on the main thread. The default implementation writes the data into a circular buffer and signals the writer thread to copy it from there to the OutputStream.

Subclasses may override this method to modify the output before writing it to the stream, but implementations in derived classes should call through to this method to do the actual writing.

Parameters:
data - An array of bytes to write to the terminal.
offset - The offset into the array at which the data starts.
count - The number of bytes to be written.

write

public void write(String data)
Write the UTF-8 representation of a String to the terminal output. The written data will be consumed by the emulation client as input.

This implementation encodes the String and then calls write(byte[], int, int) to do the actual writing. It should therefore usually be unnecessary to override this method; override write(byte[], int, int) instead.

Parameters:
data - The String to write to the terminal.

write

public void write(int codePoint)
Write the UTF-8 representation of a single Unicode code point to the terminal output. The written data will be consumed by the emulation client as input.

This implementation encodes the code point and then calls write(byte[], int, int) to do the actual writing. It should therefore usually be unnecessary to override this method; override write(byte[], int, int) instead.

Parameters:
codePoint - The Unicode code point to write to the terminal.

getTermOut

public OutputStream getTermOut()
Get the OutputStream associated with this session.

Returns:
This session's OutputStream.

setTermOut

public void setTermOut(OutputStream termOut)
Set the OutputStream associated with this session.

Parameters:
termOut - This session's OutputStream.

getTermIn

public InputStream getTermIn()
Get the InputStream associated with this session.

Returns:
This session's InputStream.

setTermIn

public void setTermIn(InputStream termIn)
Set the InputStream associated with this session.

Parameters:
termIn - This session's InputStream.

isRunning

public boolean isRunning()
Returns:
Whether the terminal emulation is currently running.

setUpdateCallback

public void setUpdateCallback(UpdateCallback notify)
Set an UpdateCallback to be invoked when the terminal emulator's screen is changed.

Parameters:
notify - The UpdateCallback to be invoked on changes.

notifyUpdate

protected void notifyUpdate()
Notify the UpdateCallback registered by setUpdateCallback that the screen has changed.


updateSize

public void updateSize(int columns,
                       int rows)
Change the terminal's window size. Will call initializeEmulator(int, int) if the emulator is not yet running.

You should override this method if your application needs to be notified when the screen size changes (for example, if you need to issue TIOCSWINSZ to a tty to adjust the window size). If you do override this method, you must call through to the superclass implementation.

Parameters:
columns - The number of columns in the terminal window.
rows - The number of rows in the terminal window.

getTranscriptText

public String getTranscriptText()
Retrieve the terminal's screen and scrollback buffer.

Returns:
A String containing the contents of the screen and scrollback buffer.

processInput

protected void processInput(byte[] data,
                            int offset,
                            int count)
Process input and send it to the terminal emulator. This method is invoked on the main thread whenever new data is read from the InputStream.

The default implementation sends the data straight to the terminal emulator without modifying it in any way. Subclasses can override it to modify the data before giving it to the terminal.

Parameters:
data - A byte array containing the data read.
offset - The offset into the buffer where the read data begins.
count - The number of bytes read.

appendToEmulator

protected final void appendToEmulator(byte[] data,
                                      int offset,
                                      int count)
Write something directly to the terminal emulator input, bypassing the emulation client, the session's InputStream, and any processing being done by processInput.

Parameters:
data - The data to be written to the terminal.
offset - The starting offset into the buffer of the data.
count - The length of the data to be written.

setColorScheme

public void setColorScheme(ColorScheme scheme)
Set the terminal emulator's color scheme (default colors).

Parameters:
scheme - The ColorScheme to be used (use null for the default scheme).

setDefaultUTF8Mode

public void setDefaultUTF8Mode(boolean utf8ByDefault)
Set whether the terminal emulator should be in UTF-8 mode by default.

In UTF-8 mode, the terminal will handle UTF-8 sequences, allowing the display of text in most of the world's languages, but applications must encode C1 control characters and graphics drawing characters as the corresponding UTF-8 sequences.

Parameters:
utf8ByDefault - Whether the terminal emulator should be in UTF-8 mode by default.

getUTF8Mode

public boolean getUTF8Mode()
Get whether the terminal emulator is currently in UTF-8 mode.

Returns:
Whether the emulator is currently in UTF-8 mode.

setUTF8ModeUpdateCallback

public void setUTF8ModeUpdateCallback(UpdateCallback utf8ModeNotify)
Set an UpdateCallback to be invoked when the terminal emulator goes into or out of UTF-8 mode.

Parameters:
utf8ModeNotify - The UpdateCallback to be invoked.

reset

public void reset()
Reset the terminal emulator's state.


setFinishCallback

public void setFinishCallback(TermSession.FinishCallback callback)
Set a TermSession.FinishCallback to be invoked once this terminal session is finished.

Parameters:
callback - The TermSession.FinishCallback to be invoked on finish.

finish

public void finish()
Finish this terminal session. Frees resources used by the terminal emulator and closes the attached InputStream and OutputStream.