121
117
class KONSOLEPRIVATE_EXPORT Emulation : public QObject
127
/** Constructs a new terminal emulation */
132
* Creates a new window onto the output from this emulation. The contents
133
* of the window are then rendered by views which are set to use this window using the
134
* TerminalDisplay::setScreenWindow() method.
136
ScreenWindow* createWindow();
138
/** Returns the size of the screen image which the emulation produces */
139
QSize imageSize() const;
142
* Returns the total number of lines, including those stored in the history.
144
int lineCount() const;
147
* Sets the history store used by this emulation. When new lines
148
* are added to the output, older lines at the top of the screen are transferred to a history
151
* The number of lines which are kept and the storage location depend on the
154
void setHistory(const HistoryType&);
155
/** Returns the history store used by this emulation. See setHistory() */
156
const HistoryType& history() const;
157
/** Clears the history scroll. */
161
* Copies the output history from @p startLine to @p endLine
162
* into @p stream, using @p decoder to convert the terminal
163
* characters into text.
165
* @param decoder A decoder which converts lines of terminal characters with
166
* appearance attributes into output text. PlainTextDecoder is the most commonly
168
* @param startLine Index of first line to copy
169
* @param endLine Index of last line to copy
171
virtual void writeToStream(TerminalCharacterDecoder* decoder,int startLine,int endLine);
173
/** Returns the codec used to decode incoming characters. See setCodec() */
174
const QTextCodec* codec() const { return _codec; }
175
/** Sets the codec used to decode incoming characters. */
176
void setCodec(const QTextCodec*);
179
* Convenience method.
180
* Returns true if the current codec used to decode incoming
181
* characters is UTF-8
184
{ Q_ASSERT(_codec); return _codec->mibEnum() == 106; }
187
/** Returns the special character used for erasing character. */
188
virtual char eraseChar() const;
191
* Sets the key bindings used to key events
192
* ( received through sendKeyEvent() ) into character
193
* streams to send to the terminal.
195
void setKeyBindings(const QString& name);
197
* Returns the name of the emulation's current key bindings.
198
* See setKeyBindings()
200
QString keyBindings() const;
203
* Copies the current image into the history and clears the screen.
205
virtual void clearEntireScreen() =0;
207
/** Resets the state of the terminal. */
208
virtual void reset() =0;
211
* Returns true if the active terminal program wants
212
* mouse input events.
214
* The programUsesMouseChanged() signal is emitted when this
217
bool programUsesMouse() const;
122
/** Constructs a new terminal emulation */
127
* Creates a new window onto the output from this emulation. The contents
128
* of the window are then rendered by views which are set to use this window using the
129
* TerminalDisplay::setScreenWindow() method.
131
ScreenWindow* createWindow();
133
/** Returns the size of the screen image which the emulation produces */
134
QSize imageSize() const;
137
* Returns the total number of lines, including those stored in the history.
139
int lineCount() const;
142
* Sets the history store used by this emulation. When new lines
143
* are added to the output, older lines at the top of the screen are transferred to a history
146
* The number of lines which are kept and the storage location depend on the
149
void setHistory(const HistoryType&);
150
/** Returns the history store used by this emulation. See setHistory() */
151
const HistoryType& history() const;
152
/** Clears the history scroll. */
156
* Copies the output history from @p startLine to @p endLine
157
* into @p stream, using @p decoder to convert the terminal
158
* characters into text.
160
* @param decoder A decoder which converts lines of terminal characters with
161
* appearance attributes into output text. PlainTextDecoder is the most commonly
163
* @param startLine Index of first line to copy
164
* @param endLine Index of last line to copy
166
virtual void writeToStream(TerminalCharacterDecoder* decoder, int startLine, int endLine);
168
/** Returns the codec used to decode incoming characters. See setCodec() */
169
const QTextCodec* codec() const {
172
/** Sets the codec used to decode incoming characters. */
173
void setCodec(const QTextCodec*);
176
* Convenience method.
177
* Returns true if the current codec used to decode incoming
178
* characters is UTF-8
182
return _codec->mibEnum() == 106;
186
/** Returns the special character used for erasing character. */
187
virtual char eraseChar() const;
190
* Sets the key bindings used to key events
191
* ( received through sendKeyEvent() ) into character
192
* streams to send to the terminal.
194
void setKeyBindings(const QString& name);
196
* Returns the name of the emulation's current key bindings.
197
* See setKeyBindings()
199
QString keyBindings() const;
202
* Copies the current image into the history and clears the screen.
204
virtual void clearEntireScreen() = 0;
206
/** Resets the state of the terminal. */
207
virtual void reset() = 0;
210
* Returns true if the active terminal program wants
211
* mouse input events.
213
* The programUsesMouseChanged() signal is emitted when this
216
bool programUsesMouse() const;
221
/** Change the size of the emulation's image */
222
virtual void setImageSize(int lines, int columns);
225
* Interprets a sequence of characters and sends the result to the terminal.
226
* This is equivalent to calling sendKeyEvent() for each character in @p text in succession.
228
virtual void sendText(const QString& text) = 0;
231
* Interprets a key press event and emits the sendData() signal with
232
* the resulting character stream.
234
virtual void sendKeyEvent(QKeyEvent*);
237
* Converts information about a mouse event into an xterm-compatible escape
238
* sequence and emits the character sequence via sendData()
240
virtual void sendMouseEvent(int buttons, int column, int line, int eventType);
243
* Sends a string of characters to the foreground terminal process.
245
* @param string The characters to send.
246
* @param length Length of @p string or if set to a negative value, @p string will
247
* be treated as a null-terminated string and its length will be determined automatically.
249
virtual void sendString(const char* string, int length = -1) = 0;
252
* Processes an incoming stream of characters. receiveData() decodes the incoming
253
* character buffer using the current codec(), and then calls receiveChar() for
254
* each unicode character in the resulting buffer.
256
* receiveData() also starts a timer which causes the outputChanged() signal
257
* to be emitted when it expires. The timer allows multiple updates in quick
258
* succession to be buffered into a single outputChanged() signal emission.
260
* @param buffer A string of characters received from the terminal program.
261
* @param len The length of @p buffer
263
void receiveData(const char* buffer,int len);
220
/** Change the size of the emulation's image */
221
virtual void setImageSize(int lines, int columns);
224
* Interprets a sequence of characters and sends the result to the terminal.
225
* This is equivalent to calling sendKeyEvent() for each character in @p text in succession.
227
virtual void sendText(const QString& text) = 0;
230
* Interprets a key press event and emits the sendData() signal with
231
* the resulting character stream.
233
virtual void sendKeyEvent(QKeyEvent*);
236
* Converts information about a mouse event into an xterm-compatible escape
237
* sequence and emits the character sequence via sendData()
239
virtual void sendMouseEvent(int buttons, int column, int line, int eventType);
242
* Sends a string of characters to the foreground terminal process.
244
* @param string The characters to send.
245
* @param length Length of @p string or if set to a negative value, @p string will
246
* be treated as a null-terminated string and its length will be determined automatically.
248
virtual void sendString(const char* string, int length = -1) = 0;
251
* Processes an incoming stream of characters. receiveData() decodes the incoming
252
* character buffer using the current codec(), and then calls receiveChar() for
253
* each unicode character in the resulting buffer.
255
* receiveData() also starts a timer which causes the outputChanged() signal
256
* to be emitted when it expires. The timer allows multiple updates in quick
257
* succession to be buffered into a single outputChanged() signal emission.
259
* @param buffer A string of characters received from the terminal program.
260
* @param len The length of @p buffer
262
void receiveData(const char* buffer, int len);
268
* Emitted when a buffer of data is ready to send to the
269
* standard input of the terminal.
271
* @param data The buffer of data ready to be sent
272
* @param len The length of @p data in bytes
274
void sendData(const char* data,int len);
277
* Requests that sending of input to the emulation
278
* from the terminal process be suspended or resumed.
280
* @param suspend If true, requests that sending of
281
* input from the terminal process' stdout be
282
* suspended. Otherwise requests that sending of
285
void lockPtyRequest(bool suspend);
288
* Requests that the pty used by the terminal process
289
* be set to UTF 8 mode.
291
* Refer to the IUTF8 entry in termios(3) for more information.
293
void useUtf8Request(bool);
296
* Emitted when the activity state of the emulation is set.
298
* @param state The new activity state, one of NOTIFYNORMAL, NOTIFYACTIVITY
301
void stateSet(int state);
304
* Emitted when the special sequence indicating the request for data
305
* transmission through ZModem protocol is detected.
307
void zmodemDetected();
311
* Requests that the color of the text used
312
* to represent the tabs associated with this
313
* emulation be changed. This is a Konsole-specific
314
* extension from pre-KDE 4 times.
316
* TODO: Document how the parameter works.
318
void changeTabTextColorRequest(int color);
321
* This is emitted when the program running in the shell indicates whether or
322
* not it is interested in mouse events.
324
* @param usesMouse This will be true if the program wants to be informed about
325
* mouse events or false otherwise.
327
void programUsesMouseChanged(bool usesMouse);
330
* Emitted when the contents of the screen image change.
331
* The emulation buffers the updates from successive image changes,
332
* and only emits outputChanged() at sensible intervals when
333
* there is a lot of terminal activity.
335
* Normally there is no need for objects other than the screen windows
336
* created with createWindow() to listen for this signal.
338
* ScreenWindow objects created using createWindow() will emit their
339
* own outputChanged() signal in response to this signal.
341
void outputChanged();
344
* Emitted when the program running in the terminal wishes to update the
345
* session's title. This also allows terminal programs to customize other
346
* aspects of the terminal emulation display.
348
* This signal is emitted when the escape sequence "\033]ARG;VALUE\007"
349
* is received in the input string, where ARG is a number specifying what
350
* should change and VALUE is a string specifying the new value.
352
* TODO: The name of this method is not very accurate since this method
353
* is used to perform a whole range of tasks besides just setting
354
* the user-title of the session.
356
* @param title Specifies what to change.
358
* <li>0 - Set window icon text and session title to @p newTitle</li>
359
* <li>1 - Set window icon text to @p newTitle</li>
360
* <li>2 - Set session title to @p newTitle</li>
361
* <li>11 - Set the session's default background color to @p newTitle,
362
* where @p newTitle can be an HTML-style string ("#RRGGBB") or a named
363
* color (eg 'red', 'blue').
364
* See http://doc.trolltech.com/4.2/qcolor.html#setNamedColor for more
367
* <li>31 - Supposedly treats @p newTitle as a URL and opens it (NOT IMPLEMENTED)</li>
368
* <li>32 - Sets the icon associated with the session. @p newTitle is the name
369
* of the icon to use, which can be the name of any icon in the current KDE icon
370
* theme (eg: 'konsole', 'kate', 'folder_home')</li>
372
* @param newTitle Specifies the new title
375
void titleChanged(int title,const QString& newTitle);
378
* Emitted when the program running in the terminal changes the
381
void imageSizeChanged(int lineCount , int columnCount);
384
* Emitted when the setImageSize() is called on this emulation for
387
void imageSizeInitialized();
390
* Emitted when the terminal program requests to change various properties
391
* of the terminal display.
393
* A profile change command occurs when a special escape sequence, followed
394
* by a string containing a series of name and value pairs is received.
395
* This string can be parsed using a ProfileCommandParser instance.
397
* @param text A string expected to contain a series of key and value pairs in
398
* the form: name=value;name2=value2 ...
400
void profileChangeCommandReceived(const QString& text);
403
* Emitted when a flow control key combination ( Ctrl+S or Ctrl+Q ) is pressed.
404
* @param suspendKeyPressed True if Ctrl+S was pressed to suspend output or Ctrl+Q to
407
void flowControlKeyPressed(bool suspendKeyPressed);
410
* Emitted when the active screen is switched, to indicate whether the primary
413
void primaryScreenInUse(bool use);
416
* Emitted when the text selection is changed
418
void selectedText(const QString & text);
267
* Emitted when a buffer of data is ready to send to the
268
* standard input of the terminal.
270
* @param data The buffer of data ready to be sent
271
* @param len The length of @p data in bytes
273
void sendData(const char* data, int len);
276
* Requests that the pty used by the terminal process
277
* be set to UTF 8 mode.
279
* Refer to the IUTF8 entry in termios(3) for more information.
281
void useUtf8Request(bool);
284
* Emitted when the activity state of the emulation is set.
286
* @param state The new activity state, one of NOTIFYNORMAL, NOTIFYACTIVITY
289
void stateSet(int state);
292
* Emitted when the special sequence indicating the request for data
293
* transmission through ZModem protocol is detected.
295
void zmodemDetected();
299
* Requests that the color of the text used
300
* to represent the tabs associated with this
301
* emulation be changed. This is a Konsole-specific
302
* extension from pre-KDE 4 times.
304
* TODO: Document how the parameter works.
306
void changeTabTextColorRequest(int color);
309
* This is emitted when the program running in the shell indicates whether or
310
* not it is interested in mouse events.
312
* @param usesMouse This will be true if the program wants to be informed about
313
* mouse events or false otherwise.
315
void programUsesMouseChanged(bool usesMouse);
318
* Emitted when the contents of the screen image change.
319
* The emulation buffers the updates from successive image changes,
320
* and only emits outputChanged() at sensible intervals when
321
* there is a lot of terminal activity.
323
* Normally there is no need for objects other than the screen windows
324
* created with createWindow() to listen for this signal.
326
* ScreenWindow objects created using createWindow() will emit their
327
* own outputChanged() signal in response to this signal.
329
void outputChanged();
332
* Emitted when the program running in the terminal wishes to update the
333
* session's title. This also allows terminal programs to customize other
334
* aspects of the terminal emulation display.
336
* This signal is emitted when the escape sequence "\033]ARG;VALUE\007"
337
* is received in the input string, where ARG is a number specifying what
338
* should change and VALUE is a string specifying the new value.
340
* TODO: The name of this method is not very accurate since this method
341
* is used to perform a whole range of tasks besides just setting
342
* the user-title of the session.
344
* @param title Specifies what to change.
346
* <li>0 - Set window icon text and session title to @p newTitle</li>
347
* <li>1 - Set window icon text to @p newTitle</li>
348
* <li>2 - Set session title to @p newTitle</li>
349
* <li>11 - Set the session's default background color to @p newTitle,
350
* where @p newTitle can be an HTML-style string ("#RRGGBB") or a named
351
* color (eg 'red', 'blue').
352
* See http://doc.trolltech.com/4.2/qcolor.html#setNamedColor for more
355
* <li>31 - Supposedly treats @p newTitle as a URL and opens it (NOT IMPLEMENTED)</li>
356
* <li>32 - Sets the icon associated with the session. @p newTitle is the name
357
* of the icon to use, which can be the name of any icon in the current KDE icon
358
* theme (eg: 'konsole', 'kate', 'folder_home')</li>
360
* @param newTitle Specifies the new title
363
void titleChanged(int title, const QString& newTitle);
366
* Emitted when the terminal emualtor's size has changed
368
void imageSizeChanged(int lineCount , int columnCount);
371
* Emitted when the setImageSize() is called on this emulation for
374
void imageSizeInitialized();
377
* Emitted after receiving the escape sequence which asks to change
378
* the terminal emulator's size
380
void imageResizeRequest(const QSize& sizz);
383
* Emitted when the terminal program requests to change various properties
384
* of the terminal display.
386
* A profile change command occurs when a special escape sequence, followed
387
* by a string containing a series of name and value pairs is received.
388
* This string can be parsed using a ProfileCommandParser instance.
390
* @param text A string expected to contain a series of key and value pairs in
391
* the form: name=value;name2=value2 ...
393
void profileChangeCommandReceived(const QString& text);
396
* Emitted when a flow control key combination ( Ctrl+S or Ctrl+Q ) is pressed.
397
* @param suspendKeyPressed True if Ctrl+S was pressed to suspend output or Ctrl+Q to
400
void flowControlKeyPressed(bool suspendKeyPressed);
403
* Emitted when the active screen is switched, to indicate whether the primary
406
void primaryScreenInUse(bool use);
409
* Emitted when the text selection is changed
411
void selectionChanged(const QString& text);
422
virtual void setMode(int mode) = 0;
423
virtual void resetMode(int mode) = 0;
426
* Processes an incoming character. See receiveData()
427
* @p ch A unicode character code.
429
virtual void receiveChar(int ch);
432
* Sets the active screen. The terminal has two screens, primary and alternate.
433
* The primary screen is used by default. When certain interactive programs such
434
* as Vim are run, they trigger a switch to the alternate screen.
436
* @param index 0 to switch to the primary screen, or 1 to switch to the alternate screen
438
void setScreen(int index);
445
void setCodec(EmulationCodec codec); // codec number, 0 = locale, 1=utf8
448
QList<ScreenWindow*> _windows;
450
Screen* _currentScreen; // pointer to the screen which is currently active,
451
// this is one of the elements in the screen[] array
453
Screen* _screen[2]; // 0 = primary screen ( used by most programs, including the shell
454
// scrollbars are enabled in this mode )
455
// 1 = alternate ( used by vi , emacs etc.
456
// scrollbars are not enabled in this mode )
459
//decodes an incoming C-style character stream into a unicode QString using
460
//the current text codec. (this allows for rendering of non-ASCII characters in text files etc.)
461
const QTextCodec* _codec;
462
QTextDecoder* _decoder;
463
const KeyboardTranslator* _keyTranslator; // the keyboard layout
414
virtual void setMode(int mode) = 0;
415
virtual void resetMode(int mode) = 0;
418
* Processes an incoming character. See receiveData()
419
* @p ch A unicode character code.
421
virtual void receiveChar(int ch);
424
* Sets the active screen. The terminal has two screens, primary and alternate.
425
* The primary screen is used by default. When certain interactive programs such
426
* as Vim are run, they trigger a switch to the alternate screen.
428
* @param index 0 to switch to the primary screen, or 1 to switch to the alternate screen
430
void setScreen(int index);
432
enum EmulationCodec {
437
void setCodec(EmulationCodec codec);
439
QList<ScreenWindow*> _windows;
441
Screen* _currentScreen; // pointer to the screen which is currently active,
442
// this is one of the elements in the screen[] array
444
Screen* _screen[2]; // 0 = primary screen ( used by most programs, including the shell
445
// scrollbars are enabled in this mode )
446
// 1 = alternate ( used by vi , emacs etc.
447
// scrollbars are not enabled in this mode )
450
//decodes an incoming C-style character stream into a unicode QString using
451
//the current text codec. (this allows for rendering of non-ASCII characters in text files etc.)
452
const QTextCodec* _codec;
453
QTextDecoder* _decoder;
454
const KeyboardTranslator* _keyTranslator; // the keyboard layout
467
* Schedules an update of attached views.
468
* Repeated calls to bufferedUpdate() in close succession will result in only a single update,
469
* much like the Qt buffered update of widgets.
471
void bufferedUpdate();
473
// used to emit the primaryScreenInUse(bool) signal
474
void checkScreenInUse();
476
// used to emit the selectedText(QString) signal
477
void checkSelectedText();
458
* Schedules an update of attached views.
459
* Repeated calls to bufferedUpdate() in close succession will result in only a single update,
460
* much like the Qt buffered update of widgets.
462
void bufferedUpdate();
464
// used to emit the primaryScreenInUse(bool) signal
465
void checkScreenInUse();
467
// used to emit the selectionChanged(QString) signal
468
void checkSelectedText();
481
// triggered by timer, causes the emulation to send an updated screen image to each
485
void usesMouseChanged(bool usesMouse);
471
// triggered by timer, causes the emulation to send an updated screen image to each
475
void usesMouseChanged(bool usesMouse);
491
bool _imageSizeInitialized;
481
bool _imageSizeInitialized;
497
485
#endif // ifndef EMULATION_H
added
removed
src/Emulation.h
