GNU Octave  6.2.0
A high-level interpreted language, primarily intended for numerical computations, mostly compatible with Matlab
Emulation Class Referenceabstract

Base class for terminal emulation back-ends. More...

#include "Emulation.h"

Inheritance diagram for Emulation:
Collaboration diagram for Emulation:

Public Slots

void receiveData (const char *buffer, int len)
 Processes an incoming stream of characters. More...
 
virtual void sendKeyEvent (QKeyEvent *)
 Interprets a key press event and emits the sendData() signal with the resulting character stream. More...
 
virtual void sendMouseEvent (int buttons, int column, int line, int eventType)
 Converts information about a mouse event into an xterm-compatible escape sequence and emits the character sequence via sendData() More...
 
virtual void sendString (const char *string, int length=-1)=0
 Sends a string of characters to the foreground terminal process. More...
 
virtual void sendText (const QString &text)=0
 Interprets a sequence of characters and sends the result to the terminal. More...
 
virtual void setImageSize (int lines, int columns)
 Change the size of the emulation's image. More...
 

Signals

void changeTabTextColorRequest (int color)
 Requests that the color of the text used to represent the tabs associated with this emulation be changed. More...
 
void imageSizeChanged (int lineCount, int columnCount)
 Emitted when the program running in the terminal changes the screen size. More...
 
void lockPtyRequest (bool suspend)
 Requests that sending of input to the emulation from the terminal process be suspended or resumed. More...
 
void outputChanged ()
 Emitted when the contents of the screen image change. More...
 
void profileChangeCommandReceived (const QString &text)
 Emitted when the terminal program requests to change various properties of the terminal display. More...
 
void programBracketedPasteModeChanged (bool bracketedPasteMode)
 
void programUsesMouseChanged (bool usesMouse)
 This is emitted when the program running in the shell indicates whether or not it is interested in mouse events. More...
 
void sendData (const char *data, int len)
 Emitted when a buffer of data is ready to send to the standard input of the terminal. More...
 
void stateSet (int state)
 Emitted when the activity state of the emulation is set. More...
 
void titleChanged (int title, const QString &newTitle)
 Emitted when the program running in the terminal wishes to update the session's title. More...
 
void useUtf8Request (bool)
 Requests that the pty used by the terminal process be set to UTF 8 mode. More...
 

Public Member Functions

 Emulation ()
 Constructs a new terminal emulation. More...
 
 ~Emulation ()
 
virtual void clearEntireScreen ()=0
 Copies the current image into the history and clears the screen. More...
 
void clearHistory ()
 Clears the history scroll. More...
 
const QTextCodec * codec ()
 Returns the codec used to decode incoming characters. More...
 
ScreenWindowcreateWindow ()
 Creates a new window onto the output from this emulation. More...
 
virtual char getErase () const
 TODO Document me. More...
 
const HistoryTypehistory ()
 Returns the history store used by this emulation. More...
 
QSize imageSize ()
 Returns the size of the screen image which the emulation produces. More...
 
QString keyBindings ()
 Returns the name of the emulation's current key bindings. More...
 
int lineCount ()
 Returns the total number of lines, including those stored in the history. More...
 
bool programBracketedPasteMode () const
 
bool programUsesMouse () const
 Returns true if the active terminal program wants mouse input events. More...
 
virtual void reset ()=0
 Resets the state of the terminal. More...
 
void setCodec (const QTextCodec *)
 Sets the codec used to decode incoming characters. More...
 
void setHistory (const HistoryType &)
 Sets the history store used by this emulation. More...
 
void setKeyBindings (const QString &name)
 Sets the key bindings used to key events ( received through sendKeyEvent() ) into character streams to send to the terminal. More...
 
bool utf8 ()
 Convenience method. More...
 
virtual void writeToStream (TerminalCharacterDecoder *decoder, int startLine, int endLine)
 Copies the output history from startLine to endLine into stream, using decoder to convert the terminal characters into text. More...
 

Protected Types

enum  EmulationCodec { LocaleCodec = 0 , Utf8Codec = 1 }
 

Protected Slots

void bufferedUpdate ()
 Schedules an update of attached views. More...
 

Protected Member Functions

virtual void receiveChar (int ch)
 Processes an incoming character. More...
 
virtual void resetMode (int mode)=0
 
void setCodec (EmulationCodec codec)
 
virtual void setMode (int mode)=0
 
void setScreen (int index)
 Sets the active screen. More...
 

Protected Attributes

const QTextCodec * _codec
 
Screen_currentScreen
 
QTextDecoder * _decoder
 
const KeyboardTranslator_keyTranslator
 
Screen_screen [2]
 
QList< ScreenWindow * > _windows
 

Private Slots

void bracketedPasteModeChanged (bool bracketedPasteMode)
 
void showBulk ()
 
void usesMouseChanged (bool usesMouse)
 

Private Attributes

bool _bracketedPasteMode
 
QTimer _bulkTimer1
 
QTimer _bulkTimer2
 
bool _usesMouse
 

Detailed Description

Base class for terminal emulation back-ends.

The back-end is responsible for decoding an incoming character stream and producing an output image of characters.

When input from the terminal is received, the receiveData() slot should be called with the data which has arrived. The emulation will process the data and update the screen image accordingly. The codec used to decode the incoming character stream into the unicode characters used internally can be specified using setCodec()

The size of the screen image can be specified by calling setImageSize() with the desired number of lines and columns. When new lines are added, old content is moved into a history store, which can be set by calling setHistory().

The screen image can be accessed by creating a ScreenWindow onto this emulation by calling createWindow(). Screen windows provide access to a section of the output. Each screen window covers the same number of lines and columns as the image size returned by imageSize(). The screen window can be moved up and down and provides transparent access to both the current on-screen image and the previous output. The screen windows emit an outputChanged signal when the section of the image they are looking at changes. Graphical views can then render the contents of a screen window, listening for notifications of output changes from the screen window which they are associated with and updating accordingly.

The emulation also is also responsible for converting input from the connected views such as keypresses and mouse activity into a character string which can be sent to the terminal program. Key presses can be processed by calling the sendKeyEvent() slot, while mouse events can be processed using the sendMouseEvent() slot. When the character stream has been produced, the emulation will emit a sendData() signal with a pointer to the character buffer. This data should be fed to the standard input of the terminal process. The translation of key presses into an output character stream is performed using a lookup in a set of key bindings which map key sequences to output character sequences. The name of the key bindings set used can be specified using setKeyBindings()

The emulation maintains certain state information which changes depending on the input received. The emulation can be reset back to its starting state by calling reset().

The emulation also maintains an activity state, which specifies whether terminal is currently active ( when data is received ), normal ( when the terminal is idle or receiving user input ) or trying to alert the user ( also known as a "Bell" event ). The stateSet() signal is emitted whenever the activity state is set. This can be used to determine how long the emulation has been active/idle for and also respond to a 'bell' event in different ways.

Definition at line 118 of file Emulation.h.

Member Enumeration Documentation

◆ EmulationCodec

enum Emulation::EmulationCodec
protected
Enumerator
LocaleCodec 
Utf8Codec 

Definition at line 410 of file Emulation.h.

Constructor & Destructor Documentation

◆ Emulation()

Emulation::Emulation ( )

◆ ~Emulation()

Emulation::~Emulation ( )

Definition at line 113 of file Emulation.cpp.

References _decoder, _screen, and _windows.

Member Function Documentation

◆ bracketedPasteModeChanged

void Emulation::bracketedPasteModeChanged ( bool  bracketedPasteMode)
privateslot

Definition at line 91 of file Emulation.cpp.

References _bracketedPasteMode.

Referenced by Emulation().

◆ bufferedUpdate

void Emulation::bufferedUpdate ( )
protectedslot

Schedules an update of attached views.

Repeated calls to bufferedUpdate() in close succession will result in only a single update, much like the Qt buffered update of widgets.

Definition at line 310 of file Emulation.cpp.

References _bulkTimer1, _bulkTimer2, BULK_TIMEOUT1, and BULK_TIMEOUT2.

Referenced by Vt102Emulation::clearEntireScreen(), createWindow(), receiveData(), Vt102Emulation::reset(), and setImageSize().

◆ changeTabTextColorRequest

void Emulation::changeTabTextColorRequest ( int  color)
signal

Requests that the color of the text used to represent the tabs associated with this emulation be changed.

This is a Konsole-specific extension from pre-KDE 4 times.

TODO: Document how the parameter works.

Referenced by Vt102Emulation::tau().

◆ clearEntireScreen()

virtual void Emulation::clearEntireScreen ( )
pure virtual

Copies the current image into the history and clears the screen.

Implemented in Vt102Emulation.

◆ clearHistory()

void Emulation::clearHistory ( )

Clears the history scroll.

Definition at line 147 of file Emulation.cpp.

References _screen, and Screen::setScroll().

Referenced by TerminalModel::clearHistory().

◆ codec()

const QTextCodec* Emulation::codec ( )
inline

Returns the codec used to decode incoming characters.

See setCodec()

Definition at line 172 of file Emulation.h.

References _codec.

Referenced by setCodec().

◆ createWindow()

ScreenWindow * Emulation::createWindow ( )

Creates a new window onto the output from this emulation.

The contents of the window are then rendered by views which are set to use this window using the TerminalDisplay::setScreenWindow() method.

Definition at line 96 of file Emulation.cpp.

References _currentScreen, _windows, bufferedUpdate(), outputChanged(), and ScreenWindow::setScreen().

Referenced by TerminalModel::addView().

◆ getErase()

char Emulation::getErase ( ) const
virtual

TODO Document me.

Reimplemented in Vt102Emulation.

Definition at line 321 of file Emulation.cpp.

◆ history()

const HistoryType & Emulation::history ( )

Returns the history store used by this emulation.

See setHistory()

Definition at line 158 of file Emulation.cpp.

References _screen, and Screen::getScroll().

Referenced by TerminalModel::historyType().

◆ imageSize()

QSize Emulation::imageSize ( )

Returns the size of the screen image which the emulation produces.

Definition at line 340 of file Emulation.cpp.

References _currentScreen, Screen::getColumns(), and Screen::getLines().

◆ imageSizeChanged

void Emulation::imageSizeChanged ( int  lineCount,
int  columnCount 
)
signal

Emitted when the program running in the terminal changes the screen size.

Referenced by setImageSize().

◆ keyBindings()

QString Emulation::keyBindings ( )

Returns the name of the emulation's current key bindings.

See setKeyBindings()

Definition at line 187 of file Emulation.cpp.

References _keyTranslator, and KeyboardTranslator::name().

Referenced by TerminalModel::keyBindings().

◆ lineCount()

int Emulation::lineCount ( )

Returns the total number of lines, including those stored in the history.

Definition at line 286 of file Emulation.cpp.

References _currentScreen, Screen::getHistLines(), and Screen::getLines().

◆ lockPtyRequest

void Emulation::lockPtyRequest ( bool  suspend)
signal

Requests that sending of input to the emulation from the terminal process be suspended or resumed.

Parameters
suspendIf true, requests that sending of input from the terminal process' stdout be suspended. Otherwise requests that sending of input be resumed.

◆ outputChanged

void Emulation::outputChanged ( )
signal

Emitted when the contents of the screen image change.

The emulation buffers the updates from successive image changes, and only emits outputChanged() at sensible intervals when there is a lot of terminal activity.

Normally there is no need for objects other than the screen windows created with createWindow() to listen for this signal.

ScreenWindow objects created using createWindow() will emit their own outputChanged() signal in response to this signal.

Referenced by createWindow(), and showBulk().

◆ profileChangeCommandReceived

void Emulation::profileChangeCommandReceived ( const QString &  text)
signal

Emitted when the terminal program requests to change various properties of the terminal display.

A profile change command occurs when a special escape sequence, followed by a string containing a series of name and value pairs is received. This string can be parsed using a ProfileCommandParser instance.

Parameters
textA string expected to contain a series of key and value pairs in the form: name=value;name2=value2 ...

◆ programBracketedPasteMode()

bool Emulation::programBracketedPasteMode ( ) const

Definition at line 86 of file Emulation.cpp.

References _bracketedPasteMode.

Referenced by TerminalModel::addView().

◆ programBracketedPasteModeChanged

void Emulation::programBracketedPasteModeChanged ( bool  bracketedPasteMode)
signal

◆ programUsesMouse()

bool Emulation::programUsesMouse ( ) const

Returns true if the active terminal program wants mouse input events.

The programUsesMouseChanged() signal is emitted when this changes.

Definition at line 76 of file Emulation.cpp.

References _usesMouse.

Referenced by TerminalModel::addView().

◆ programUsesMouseChanged

void Emulation::programUsesMouseChanged ( bool  usesMouse)
signal

This is emitted when the program running in the shell indicates whether or not it is interested in mouse events.

Parameters
usesMouseThis will be true if the program wants to be informed about mouse events or false otherwise.

Referenced by Emulation(), Vt102Emulation::resetMode(), and Vt102Emulation::setMode().

◆ receiveChar()

void Emulation::receiveChar ( int  ch)
protectedvirtual

Processes an incoming character.

See receiveData() ch A unicode character code.

Reimplemented in Vt102Emulation.

Definition at line 205 of file Emulation.cpp.

References _currentScreen, Screen::BackSpace(), Screen::NewLine(), NOTIFYBELL, Screen::Return(), Screen::ShowCharacter(), stateSet(), and Screen::Tabulate().

Referenced by receiveData().

◆ receiveData

void Emulation::receiveData ( const char *  buffer,
int  len 
)
slot

Processes an incoming stream of characters.

receiveData() decodes the incoming character buffer using the current codec(), and then calls receiveChar() for each unicode character in the resulting buffer.

receiveData() also starts a timer which causes the outputChanged() signal to be emitted when it expires. The timer allows multiple updates in quick succession to be buffered into a single outputChanged() signal emission.

Parameters
bufferA string of characters received from the terminal program.
lenThe length of buffer

Definition at line 262 of file Emulation.cpp.

References _decoder, bufferedUpdate(), octave::jit_convention::length, NOTIFYACTIVITY, receiveChar(), and stateSet().

Referenced by TerminalModel::onReceiveBlock(), and Vt102Emulation::sendKeyEvent().

◆ reset()

virtual void Emulation::reset ( )
pure virtual

Resets the state of the terminal.

Implemented in Vt102Emulation.

◆ resetMode()

virtual void Emulation::resetMode ( int  mode)
protectedpure virtual

Implemented in Vt102Emulation.

◆ sendData

void Emulation::sendData ( const char *  data,
int  len 
)
signal

Emitted when a buffer of data is ready to send to the standard input of the terminal.

Parameters
dataThe buffer of data ready to be sent @paran len The length of data in bytes

Referenced by sendKeyEvent(), Vt102Emulation::sendKeyEvent(), and Vt102Emulation::sendString().

◆ sendKeyEvent

void Emulation::sendKeyEvent ( QKeyEvent *  ev)
virtualslot

Interprets a key press event and emits the sendData() signal with the resulting character stream.

Definition at line 231 of file Emulation.cpp.

References NOTIFYNORMAL, sendData(), and stateSet().

◆ sendMouseEvent

void Emulation::sendMouseEvent ( int  buttons,
int  column,
int  line,
int  eventType 
)
virtualslot

Converts information about a mouse event into an xterm-compatible escape sequence and emits the character sequence via sendData()

Definition at line 250 of file Emulation.cpp.

◆ sendString

void Emulation::sendString ( const char *  string,
int  length = -1 
)
pure virtualslot

Sends a string of characters to the foreground terminal process.

Parameters
stringThe characters to send.
lengthLength of string or if set to a negative value, string will be treated as a null-terminated string and its length will be determined automatically.

Definition at line 245 of file Emulation.cpp.

◆ sendText

virtual void Emulation::sendText ( const QString &  text)
pure virtualslot

Interprets a sequence of characters and sends the result to the terminal.

This is equivalent to calling sendKeyEvent() for each character in text in succession.

Referenced by TerminalModel::sendText().

◆ setCodec() [1/2]

void Emulation::setCodec ( const QTextCodec *  qtc)

Sets the codec used to decode incoming characters.


Definition at line 163 of file Emulation.cpp.

References _codec, _decoder, useUtf8Request(), and utf8().

Referenced by Vt102Emulation::reset(), setCodec(), TerminalModel::setCodec(), and Vt102Emulation::tau().

◆ setCodec() [2/2]

void Emulation::setCodec ( EmulationCodec  codec)
protected

Definition at line 174 of file Emulation.cpp.

References codec(), LocaleCodec, setCodec(), and Utf8Codec.

◆ setHistory()

void Emulation::setHistory ( const HistoryType t)

Sets the history store used by this emulation.

When new lines are added to the output, older lines at the top of the screen are transferred to a history store.

The number of lines which are kept and the storage location depend on the type of store.

Definition at line 151 of file Emulation.cpp.

References _screen, Screen::setScroll(), and showBulk().

Referenced by TerminalModel::setHistoryType().

◆ setImageSize

void Emulation::setImageSize ( int  lines,
int  columns 
)
virtualslot

Change the size of the emulation's image.

Definition at line 326 of file Emulation.cpp.

References _screen, bufferedUpdate(), imageSizeChanged(), and Screen::resizeImage().

Referenced by Vt102Emulation::clearScreenAndSetColumns(), Vt102Emulation::tau(), and TerminalModel::updateTerminalSize().

◆ setKeyBindings()

void Emulation::setKeyBindings ( const QString &  name)

Sets the key bindings used to key events ( received through sendKeyEvent() ) into character streams to send to the terminal.

Definition at line 182 of file Emulation.cpp.

References _keyTranslator, KeyboardTranslatorManager::findTranslator(), KeyboardTranslatorManager::instance(), and name.

Referenced by TerminalModel::setKeyBindings().

◆ setMode()

virtual void Emulation::setMode ( int  mode)
protectedpure virtual

Implemented in Vt102Emulation.

◆ setScreen()

void Emulation::setScreen ( int  n)
protected

Sets the active screen.

The terminal has two screens, primary and alternate. The primary screen is used by default. When certain interactive programs such as Vim are run, they trigger a switch to the alternate screen.

Parameters
index0 to switch to the primary screen, or 1 to switch to the alternate screen

change between primary and alternate _screen

Definition at line 130 of file Emulation.cpp.

References _currentScreen, _screen, _windows, n, and Screen::setBusySelecting().

Referenced by Vt102Emulation::resetMode(), and Vt102Emulation::setMode().

◆ showBulk

void Emulation::showBulk ( )
privateslot

◆ stateSet

void Emulation::stateSet ( int  state)
signal

Emitted when the activity state of the emulation is set.

Parameters
stateThe new activity state, one of NOTIFYNORMAL, NOTIFYACTIVITY or NOTIFYBELL

Referenced by receiveChar(), receiveData(), sendKeyEvent(), and Vt102Emulation::tau().

◆ titleChanged

void Emulation::titleChanged ( int  title,
const QString &  newTitle 
)
signal

Emitted when the program running in the terminal wishes to update the session's title.

This also allows terminal programs to customize other aspects of the terminal emulation display.

This signal is emitted when the escape sequence "\033]ARG;VALUE\007" is received in the input string, where ARG is a number specifying what should change and VALUE is a string specifying the new value.

TODO: The name of this method is not very accurate since this method is used to perform a whole range of tasks besides just setting the user-title of the session.

Parameters
titleSpecifies what to change.
  • 0 - Set window icon text and session title to newTitle
  • 1 - Set window icon text to newTitle
  • 2 - Set session title to newTitle
  • 11 - Set the session's default background color to newTitle, where newTitle can be an HTML-style string (#RRGGBB) or a named color (eg 'red', 'blue'). See http://doc.trolltech.com/4.2/qcolor.html#setNamedColor for more details.
  • 31 - Supposedly treats newTitle as a URL and opens it (NOT IMPLEMENTED)
  • 32 - Sets the icon associated with the session. newTitle is the name of the icon to use, which can be the name of any icon in the current KDE icon theme (eg: 'konsole', 'kate', 'folder_home')
newTitleSpecifies the new title

Referenced by Vt102Emulation::updateTitle().

◆ usesMouseChanged

void Emulation::usesMouseChanged ( bool  usesMouse)
privateslot

Definition at line 81 of file Emulation.cpp.

References _usesMouse.

Referenced by Emulation().

◆ useUtf8Request

void Emulation::useUtf8Request ( bool  )
signal

Requests that the pty used by the terminal process be set to UTF 8 mode.

TODO: More documentation

Referenced by setCodec().

◆ utf8()

bool Emulation::utf8 ( )
inline

Convenience method.

Returns true if the current codec used to decode incoming characters is UTF-8

Definition at line 181 of file Emulation.h.

References _codec.

Referenced by setCodec().

◆ writeToStream()

void Emulation::writeToStream ( TerminalCharacterDecoder decoder,
int  startLine,
int  endLine 
)
virtual

Copies the output history from startLine to endLine into stream, using decoder to convert the terminal characters into text.

Parameters
decoderA decoder which converts lines of terminal characters with appearance attributes into output text. PlainTextDecoder is the most commonly used decoder.
startLineThe first

Definition at line 279 of file Emulation.cpp.

References _currentScreen, _decoder, and Screen::writeToStream().

Member Data Documentation

◆ _bracketedPasteMode

bool Emulation::_bracketedPasteMode
private

Definition at line 457 of file Emulation.h.

Referenced by bracketedPasteModeChanged(), and programBracketedPasteMode().

◆ _bulkTimer1

QTimer Emulation::_bulkTimer1
private

Definition at line 458 of file Emulation.h.

Referenced by Emulation(), bufferedUpdate(), and showBulk().

◆ _bulkTimer2

QTimer Emulation::_bulkTimer2
private

Definition at line 459 of file Emulation.h.

Referenced by Emulation(), bufferedUpdate(), and showBulk().

◆ _codec

const QTextCodec* Emulation::_codec
protected

Definition at line 431 of file Emulation.h.

Referenced by codec(), Vt102Emulation::sendKeyEvent(), setCodec(), and utf8().

◆ _currentScreen

◆ _decoder

QTextDecoder* Emulation::_decoder
protected

Definition at line 432 of file Emulation.h.

Referenced by ~Emulation(), receiveData(), setCodec(), and writeToStream().

◆ _keyTranslator

const KeyboardTranslator* Emulation::_keyTranslator
protected

◆ _screen

◆ _usesMouse

bool Emulation::_usesMouse
private

Definition at line 456 of file Emulation.h.

Referenced by programUsesMouse(), and usesMouseChanged().

◆ _windows

QList<ScreenWindow*> Emulation::_windows
protected

Definition at line 418 of file Emulation.h.

Referenced by ~Emulation(), createWindow(), and setScreen().


The documentation for this class was generated from the following files: