1/*
2 This file is part of Konsole, an X terminal.
3
4 Copyright 2007-2008 by Robert Knight <robertknight@gmail.com>
5 Copyright 1997,1998 by Lars Doelle <lars.doelle@on-line.de>
6
7 This program is free software; you can redistribute it and/or modify
8 it under the terms of the GNU General Public License as published by
9 the Free Software Foundation; either version 2 of the License, or
10 (at your option) any later version.
11
12 This program is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 GNU General Public License for more details.
16
17 You should have received a copy of the GNU General Public License
18 along with this program; if not, write to the Free Software
19 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
20 02110-1301 USA.
21*/
22
23#ifndef EMULATION_H
24#define EMULATION_H
25
26// Qt
27#include <QtCore/QSize>
28#include <QtCore/QTextCodec>
29#include <QtCore/QTimer>
30
31// Konsole
32#include "konsole_export.h"
33
34class QKeyEvent;
35
36namespace Konsole
37{
38class KeyboardTranslator;
39class HistoryType;
40class Screen;
41class ScreenWindow;
42class TerminalCharacterDecoder;
43
44/**
45 * This enum describes the available states which
46 * the terminal emulation may be set to.
47 *
48 * These are the values used by Emulation::stateChanged()
49 */
50enum {
51 /** The emulation is currently receiving user input. */
52 NOTIFYNORMAL = 0,
53 /**
54 * The terminal program has triggered a bell event
55 * to get the user's attention.
56 */
57 NOTIFYBELL = 1,
58 /**
59 * The emulation is currently receiving data from its
60 * terminal input.
61 */
62 NOTIFYACTIVITY = 2,
63
64 // unused here?
65 NOTIFYSILENCE = 3
66};
67
68/**
69 * Base class for terminal emulation back-ends.
70 *
71 * The back-end is responsible for decoding an incoming character stream and
72 * producing an output image of characters.
73 *
74 * When input from the terminal is received, the receiveData() slot should be called with
75 * the data which has arrived. The emulation will process the data and update the
76 * screen image accordingly. The codec used to decode the incoming character stream
77 * into the unicode characters used internally can be specified using setCodec()
78 *
79 * The size of the screen image can be specified by calling setImageSize() with the
80 * desired number of lines and columns. When new lines are added, old content
81 * is moved into a history store, which can be set by calling setHistory().
82 *
83 * The screen image can be accessed by creating a ScreenWindow onto this emulation
84 * by calling createWindow(). Screen windows provide access to a section of the
85 * output. Each screen window covers the same number of lines and columns as the
86 * image size returned by imageSize(). The screen window can be moved up and down
87 * and provides transparent access to both the current on-screen image and the
88 * previous output. The screen windows emit an outputChanged signal
89 * when the section of the image they are looking at changes.
90 * Graphical views can then render the contents of a screen window, listening for notifications
91 * of output changes from the screen window which they are associated with and updating
92 * accordingly.
93 *
94 * The emulation also is also responsible for converting input from the connected views such
95 * as keypresses and mouse activity into a character string which can be sent
96 * to the terminal program. Key presses can be processed by calling the sendKeyEvent() slot,
97 * while mouse events can be processed using the sendMouseEvent() slot. When the character
98 * stream has been produced, the emulation will emit a sendData() signal with a pointer
99 * to the character buffer. This data should be fed to the standard input of the terminal
100 * process. The translation of key presses into an output character stream is performed
101 * using a lookup in a set of key bindings which map key sequences to output
102 * character sequences. The name of the key bindings set used can be specified using
103 * setKeyBindings()
104 *
105 * The emulation maintains certain state information which changes depending on the
106 * input received. The emulation can be reset back to its starting state by calling
107 * reset().
108 *
109 * The emulation also maintains an activity state, which specifies whether
110 * terminal is currently active ( when data is received ), normal
111 * ( when the terminal is idle or receiving user input ) or trying
112 * to alert the user ( also known as a "Bell" event ). The stateSet() signal
113 * is emitted whenever the activity state is set. This can be used to determine
114 * how long the emulation has been active/idle for and also respond to
115 * a 'bell' event in different ways.
116 */
117class KONSOLEPRIVATE_EXPORT Emulation : public QObject
118{
119 Q_OBJECT
120
121public:
122 /** Constructs a new terminal emulation */
123 Emulation();
124 ~Emulation();
125
126 /**
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.
130 */
131 ScreenWindow* createWindow();
132
133 /** Returns the size of the screen image which the emulation produces */
134 QSize imageSize() const;
135
136 /**
137 * Returns the total number of lines, including those stored in the history.
138 */
139 int lineCount() const;
140
141 /**
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
144 * store.
145 *
146 * The number of lines which are kept and the storage location depend on the
147 * type of store.
148 */
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. */
153 void clearHistory();
154
155 /**
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.
159 *
160 * @param decoder A decoder which converts lines of terminal characters with
161 * appearance attributes into output text. PlainTextDecoder is the most commonly
162 * used decoder.
163 * @param startLine Index of first line to copy
164 * @param endLine Index of last line to copy
165 */
166 virtual void writeToStream(TerminalCharacterDecoder* decoder, int startLine, int endLine);
167
168 /** Returns the codec used to decode incoming characters. See setCodec() */
169 const QTextCodec* codec() const {
170 return _codec;
171 }
172 /** Sets the codec used to decode incoming characters. */
173 void setCodec(const QTextCodec*);
174
175 /**
176 * Convenience method.
177 * Returns true if the current codec used to decode incoming
178 * characters is UTF-8
179 */
180 bool utf8() const {
181 Q_ASSERT(_codec);
182 return _codec->mibEnum() == 106;
183 }
184
185
186 /** Returns the special character used for erasing character. */
187 virtual char eraseChar() const;
188
189 /**
190 * Sets the key bindings used to key events
191 * ( received through sendKeyEvent() ) into character
192 * streams to send to the terminal.
193 */
194 void setKeyBindings(const QString& name);
195 /**
196 * Returns the name of the emulation's current key bindings.
197 * See setKeyBindings()
198 */
199 QString keyBindings() const;
200
201 /**
202 * Copies the current image into the history and clears the screen.
203 */
204 virtual void clearEntireScreen() = 0;
205
206 /** Resets the state of the terminal. */
207 virtual void reset() = 0;
208
209 /**
210 * Returns true if the active terminal program wants
211 * mouse input events.
212 *
213 * The programUsesMouseChanged() signal is emitted when this
214 * changes.
215 */
216 bool programUsesMouse() const;
217
218 bool programBracketedPasteMode() const;
219
220public slots:
221
222 /** Change the size of the emulation's image */
223 virtual void setImageSize(int lines, int columns);
224
225 /**
226 * Interprets a sequence of characters and sends the result to the terminal.
227 * This is equivalent to calling sendKeyEvent() for each character in @p text in succession.
228 */
229 virtual void sendText(const QString& text) = 0;
230
231 /**
232 * Interprets a key press event and emits the sendData() signal with
233 * the resulting character stream.
234 */
235 virtual void sendKeyEvent(QKeyEvent*);
236
237 /**
238 * Converts information about a mouse event into an xterm-compatible escape
239 * sequence and emits the character sequence via sendData()
240 */
241 virtual void sendMouseEvent(int buttons, int column, int line, int eventType);
242
243 /**
244 * Sends a string of characters to the foreground terminal process.
245 *
246 * @param string The characters to send.
247 * @param length Length of @p string or if set to a negative value, @p string will
248 * be treated as a null-terminated string and its length will be determined automatically.
249 */
250 virtual void sendString(const char* string, int length = -1) = 0;
251
252 /**
253 * Processes an incoming stream of characters. receiveData() decodes the incoming
254 * character buffer using the current codec(), and then calls receiveChar() for
255 * each unicode character in the resulting buffer.
256 *
257 * receiveData() also starts a timer which causes the outputChanged() signal
258 * to be emitted when it expires. The timer allows multiple updates in quick
259 * succession to be buffered into a single outputChanged() signal emission.
260 *
261 * @param buffer A string of characters received from the terminal program.
262 * @param len The length of @p buffer
263 */
264 void receiveData(const char* buffer, int len);
265
266signals:
267
268 /**
269 * Emitted when a buffer of data is ready to send to the
270 * standard input of the terminal.
271 *
272 * @param data The buffer of data ready to be sent
273 * @param len The length of @p data in bytes
274 */
275 void sendData(const char* data, int len);
276
277 /**
278 * Requests that the pty used by the terminal process
279 * be set to UTF 8 mode.
280 *
281 * Refer to the IUTF8 entry in termios(3) for more information.
282 */
283 void useUtf8Request(bool);
284
285 /**
286 * Emitted when the activity state of the emulation is set.
287 *
288 * @param state The new activity state, one of NOTIFYNORMAL, NOTIFYACTIVITY
289 * or NOTIFYBELL
290 */
291 void stateSet(int state);
292
293 /**
294 * Emitted when the special sequence indicating the request for data
295 * transmission through ZModem protocol is detected.
296 */
297 void zmodemDetected();
298
299
300 /**
301 * Requests that the color of the text used
302 * to represent the tabs associated with this
303 * emulation be changed. This is a Konsole-specific
304 * extension from pre-KDE 4 times.
305 *
306 * TODO: Document how the parameter works.
307 */
308 void changeTabTextColorRequest(int color);
309
310 /**
311 * This is emitted when the program running in the shell indicates whether or
312 * not it is interested in mouse events.
313 *
314 * @param usesMouse This will be true if the program wants to be informed about
315 * mouse events or false otherwise.
316 */
317 void programUsesMouseChanged(bool usesMouse);
318
319 void programBracketedPasteModeChanged(bool bracketedPasteMode);
320
321 /**
322 * Emitted when the contents of the screen image change.
323 * The emulation buffers the updates from successive image changes,
324 * and only emits outputChanged() at sensible intervals when
325 * there is a lot of terminal activity.
326 *
327 * Normally there is no need for objects other than the screen windows
328 * created with createWindow() to listen for this signal.
329 *
330 * ScreenWindow objects created using createWindow() will emit their
331 * own outputChanged() signal in response to this signal.
332 */
333 void outputChanged();
334
335 /**
336 * Emitted when the program running in the terminal wishes to update the
337 * session's title. This also allows terminal programs to customize other
338 * aspects of the terminal emulation display.
339 *
340 * This signal is emitted when the escape sequence "\033]ARG;VALUE\007"
341 * is received in the input string, where ARG is a number specifying what
342 * should change and VALUE is a string specifying the new value.
343 *
344 * TODO: The name of this method is not very accurate since this method
345 * is used to perform a whole range of tasks besides just setting
346 * the user-title of the session.
347 *
348 * @param title Specifies what to change.
349 * <ul>
350 * <li>0 - Set window icon text and session title to @p newTitle</li>
351 * <li>1 - Set window icon text to @p newTitle</li>
352 * <li>2 - Set session title to @p newTitle</li>
353 * <li>11 - Set the session's default background color to @p newTitle,
354 * where @p newTitle can be an HTML-style string ("#RRGGBB") or a named
355 * color (eg 'red', 'blue').
356 * See http://doc.trolltech.com/4.2/qcolor.html#setNamedColor for more
357 * details.
358 * </li>
359 * <li>31 - Supposedly treats @p newTitle as a URL and opens it (NOT IMPLEMENTED)</li>
360 * <li>32 - Sets the icon associated with the session. @p newTitle is the name
361 * of the icon to use, which can be the name of any icon in the current KDE icon
362 * theme (eg: 'konsole', 'kate', 'folder_home')</li>
363 * </ul>
364 * @param newTitle Specifies the new title
365 */
366
367 void titleChanged(int title, const QString& newTitle);
368
369 /**
370 * Emitted when the terminal emulator's size has changed
371 */
372 void imageSizeChanged(int lineCount , int columnCount);
373
374 /**
375 * Emitted when the setImageSize() is called on this emulation for
376 * the first time.
377 */
378 void imageSizeInitialized();
379
380 /**
381 * Emitted after receiving the escape sequence which asks to change
382 * the terminal emulator's size
383 */
384 void imageResizeRequest(const QSize& sizz);
385
386 /**
387 * Emitted when the terminal program requests to change various properties
388 * of the terminal display.
389 *
390 * A profile change command occurs when a special escape sequence, followed
391 * by a string containing a series of name and value pairs is received.
392 * This string can be parsed using a ProfileCommandParser instance.
393 *
394 * @param text A string expected to contain a series of key and value pairs in
395 * the form: name=value;name2=value2 ...
396 */
397 void profileChangeCommandReceived(const QString& text);
398
399 /**
400 * Emitted when a flow control key combination ( Ctrl+S or Ctrl+Q ) is pressed.
401 * @param suspendKeyPressed True if Ctrl+S was pressed to suspend output or Ctrl+Q to
402 * resume output.
403 */
404 void flowControlKeyPressed(bool suspendKeyPressed);
405
406 /**
407 * Emitted when the active screen is switched, to indicate whether the primary
408 * screen is in use.
409 */
410 void primaryScreenInUse(bool use);
411
412 /**
413 * Emitted when the text selection is changed
414 */
415 void selectionChanged(const QString& text);
416
417protected:
418 virtual void setMode(int mode) = 0;
419 virtual void resetMode(int mode) = 0;
420
421 /**
422 * Processes an incoming character. See receiveData()
423 * @p ch A unicode character code.
424 */
425 virtual void receiveChar(int ch);
426
427 /**
428 * Sets the active screen. The terminal has two screens, primary and alternate.
429 * The primary screen is used by default. When certain interactive programs such
430 * as Vim are run, they trigger a switch to the alternate screen.
431 *
432 * @param index 0 to switch to the primary screen, or 1 to switch to the alternate screen
433 */
434 void setScreen(int index);
435
436 enum EmulationCodec {
437 LocaleCodec = 0,
438 Utf8Codec = 1
439 };
440
441 void setCodec(EmulationCodec codec);
442
443 QList<ScreenWindow*> _windows;
444
445 Screen* _currentScreen; // pointer to the screen which is currently active,
446 // this is one of the elements in the screen[] array
447
448 Screen* _screen[2]; // 0 = primary screen ( used by most programs, including the shell
449 // scrollbars are enabled in this mode )
450 // 1 = alternate ( used by vi , emacs etc.
451 // scrollbars are not enabled in this mode )
452
453
454 //decodes an incoming C-style character stream into a unicode QString using
455 //the current text codec. (this allows for rendering of non-ASCII characters in text files etc.)
456 const QTextCodec* _codec;
457 QTextDecoder* _decoder;
458 const KeyboardTranslator* _keyTranslator; // the keyboard layout
459
460protected slots:
461 /**
462 * Schedules an update of attached views.
463 * Repeated calls to bufferedUpdate() in close succession will result in only a single update,
464 * much like the Qt buffered update of widgets.
465 */
466 void bufferedUpdate();
467
468 // used to emit the primaryScreenInUse(bool) signal
469 void checkScreenInUse();
470
471 // used to emit the selectionChanged(QString) signal
472 void checkSelectedText();
473
474private slots:
475 // triggered by timer, causes the emulation to send an updated screen image to each
476 // view
477 void showBulk();
478
479 void usesMouseChanged(bool usesMouse);
480
481 void bracketedPasteModeChanged(bool bracketedPasteMode);
482
483private:
484 bool _usesMouse;
485 bool _bracketedPasteMode;
486 QTimer _bulkTimer1;
487 QTimer _bulkTimer2;
488 bool _imageSizeInitialized;
489};
490}
491
492#endif // ifndef EMULATION_H
493