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