2
This file is part of Konsole, KDE's terminal.
4
Copyright 2007-2008 by Robert Knight <robertknight@gmail.com>
5
Copyright 1997,1998 by Lars Doelle <lars.doelle@on-line.de>
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.
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.
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
28
#include <QTextStream>
29
#include <QVarLengthArray>
32
#include "Character.h"
40
#define MODE_NewLine 5
41
#define MODES_SCREEN 6
46
class TerminalCharacterDecoder;
49
\brief An image of characters with associated attributes.
51
The terminal emulation ( Emulation ) receives a serial stream of
52
characters from the program currently running in the terminal.
53
From this stream it creates an image of characters which is ultimately
54
rendered by the display widget ( TerminalDisplay ). Some types of emulation
55
may have more than one screen image.
57
getImage() is used to retrieve the currently visible image
58
which is then used by the display widget to draw the output from the
61
The number of lines of output history which are kept in addition to the current
62
screen image depends on the history scroll being used to store the output.
63
The scroll is specified using setScroll()
64
The output history can be retrieved using writeToStream()
66
The screen image has a selection associated with it, specified using
67
setSelectionStart() and setSelectionEnd(). The selected text can be retrieved
68
using selectedText(). When getImage() is used to retrieve the visible image,
69
characters which are part of the selection have their colours inverted.
74
/** Construct a new screen image of size @p lines by @p columns. */
75
Screen(int lines, int columns);
82
* Move the cursor up by @p n lines. The cursor will stop at the
87
* Move the cursor down by @p n lines. The cursor will stop at the
90
void cursorDown(int n);
92
* Move the cursor to the left by @p n columns.
93
* The cursor will stop at the first column.
95
void cursorLeft(int n);
97
* Move the cursor to the right by @p n columns.
98
* The cursor will stop at the right-most column.
100
void cursorRight(int n);
101
/** Position the cursor on line @p y. */
102
void setCursorY(int y);
103
/** Position the cursor at column @p x. */
104
void setCursorX(int x);
105
/** Position the cursor at line @p y, column @p x. */
106
void setCursorYX(int y, int x);
108
* Sets the margins for scrolling the screen.
110
* @param topLine The top line of the new scrolling margin.
111
* @param bottomLine The bottom line of the new scrolling margin.
113
void setMargins(int topLine , int bottomLine);
114
/** Returns the top line of the scrolling region. */
115
int topMargin() const;
116
/** Returns the bottom line of the scrolling region. */
117
int bottomMargin() const;
120
* Resets the scrolling margins back to the top and bottom lines
123
void setDefaultMargins();
126
* Moves the cursor down one line, if the MODE_NewLine mode
127
* flag is enabled then the cursor is returned to the leftmost
130
* Equivalent to NextLine() if the MODE_NewLine flag is set
131
* or index() otherwise.
135
* Moves the cursor down one line and positions it at the beginning
136
* of the line. Equivalent to calling Return() followed by index()
141
* Move the cursor down one line. If the cursor is on the bottom
142
* line of the scrolling region (as returned by bottomMargin()) the
143
* scrolling region is scrolled up by one line instead.
147
* Move the cursor up one line. If the cursor is on the top line
148
* of the scrolling region (as returned by topMargin()) the scrolling
149
* region is scrolled down by one line instead.
154
* Scroll the scrolling region of the screen up by @p n lines.
155
* The scrolling region is initially the whole screen, but can be changed
158
void scrollUp(int n);
160
* Scroll the scrolling region of the screen down by @p n lines.
161
* The scrolling region is initially the whole screen, but can be changed
164
void scrollDown(int n);
166
* Moves the cursor to the beginning of the current line.
167
* Equivalent to setCursorX(0)
169
void toStartOfLine();
171
* Moves the cursor one column to the left and erases the character
172
* at the new cursor position.
175
/** Moves the cursor @p n tab-stops to the right. */
177
/** Moves the cursor @p n tab-stops to the left. */
183
* Erase @p n characters beginning from the current cursor position.
184
* This is equivalent to over-writing @p n characters starting with the current
185
* cursor position with spaces.
186
* If @p n is 0 then one character is erased.
188
void eraseChars(int n);
190
* Delete @p n characters beginning from the current cursor position.
191
* If @p n is 0 then one character is deleted.
193
void deleteChars(int n);
195
* Insert @p n blank characters beginning from the current cursor position.
196
* The position of the cursor is not altered.
197
* If @p n is 0 then one character is inserted.
199
void insertChars(int n);
201
* Removes @p n lines beginning from the current cursor position.
202
* The position of the cursor is not altered.
203
* If @p n is 0 then one line is removed.
205
void deleteLines(int n);
207
* Inserts @p lines beginning from the current cursor position.
208
* The position of the cursor is not altered.
209
* If @p n is 0 then one line is inserted.
211
void insertLines(int n);
212
/** Clears all the tab stops. */
213
void clearTabStops();
214
/** Sets or removes a tab stop at the cursor's current column. */
215
void changeTabStop(bool set);
217
/** Resets (clears) the specified screen @p mode. */
218
void resetMode(int mode);
219
/** Sets (enables) the specified screen @p mode. */
220
void setMode(int mode);
222
* Saves the state of the specified screen @p mode. It can be restored
223
* using restoreMode()
225
void saveMode(int mode);
226
/** Restores the state of a screen @p mode saved by calling saveMode() */
227
void restoreMode(int mode);
228
/** Returns whether the specified screen @p mode is enabled or not .*/
229
bool getMode(int mode) const;
232
* Saves the current position and appearance (text color and style) of the cursor.
233
* It can be restored by calling restoreCursor()
236
/** Restores the position and appearance of the cursor. See saveCursor() */
237
void restoreCursor();
239
/** Clear the whole screen, moving the current screen contents into the history first. */
240
void clearEntireScreen();
242
* Clear the area of the screen from the current cursor position to the end of
245
void clearToEndOfScreen();
247
* Clear the area of the screen from the current cursor position to the start
250
void clearToBeginOfScreen();
251
/** Clears the whole of the line on which the cursor is currently positioned. */
252
void clearEntireLine();
253
/** Clears from the current cursor position to the end of the line. */
254
void clearToEndOfLine();
255
/** Clears from the current cursor position to the beginning of the line. */
256
void clearToBeginOfLine();
258
/** Fills the entire screen with the letter 'E' */
262
* Enables the given @p rendition flag. Rendition flags control the appearance
263
* of characters on the screen.
265
* @see Character::rendition
267
void setRendition(int rendition);
269
* Disables the given @p rendition flag. Rendition flags control the appearance
270
* of characters on the screen.
272
* @see Character::rendition
274
void resetRendition(int rendition);
277
* Sets the cursor's foreground color.
278
* @param space The color space used by the @p color argument
279
* @param color The new foreground color. The meaning of this depends on
280
* the color @p space used.
282
* @see CharacterColor
284
void setForeColor(int space, int color);
286
* Sets the cursor's background color.
287
* @param space The color space used by the @p color argumnet.
288
* @param color The new background color. The meaning of this depends on
289
* the color @p space used.
291
* @see CharacterColor
293
void setBackColor(int space, int color);
295
* Resets the cursor's color back to the default and sets the
296
* character's rendition flags back to the default settings.
298
void setDefaultRendition();
300
/** Returns the column which the cursor is positioned at. */
301
int getCursorX() const;
302
/** Returns the line which the cursor is positioned on. */
303
int getCursorY() const;
305
/** Clear the entire screen and move the cursor to the home position.
306
* Equivalent to calling clearEntireScreen() followed by home().
310
* Sets the position of the cursor to the 'home' position at the top-left
311
* corner of the screen (0,0)
315
* Resets the state of the screen. This resets the various screen modes
316
* back to their default states. The cursor style and colors are reset
317
* (as if setDefaultRendition() had been called)
320
* <li>Line wrapping is enabled.</li>
321
* <li>Origin mode is disabled.</li>
322
* <li>Insert mode is disabled.</li>
323
* <li>Cursor mode is enabled. TODO Document me</li>
324
* <li>Screen mode is disabled. TODO Document me</li>
325
* <li>New line mode is disabled. TODO Document me</li>
328
* If @p clearScreen is true then the screen contents are erased entirely,
329
* otherwise they are unaltered.
331
void reset(bool clearScreen = true);
334
* Displays a new character at the current cursor position.
336
* If the cursor is currently positioned at the right-edge of the screen and
337
* line wrapping is enabled then the character is added at the start of a new
338
* line below the current one.
340
* If the MODE_Insert screen mode is currently enabled then the character
341
* is inserted at the current cursor position, otherwise it will replace the
342
* character already at the current cursor position.
344
void displayCharacter(unsigned short c);
346
// Do composition with last shown character FIXME: Not implemented yet for KDE 4
347
void compose(const QString& compose);
350
* Resizes the image to a new fixed size of @p new_lines by @p new_columns.
351
* In the case that @p new_columns is smaller than the current number of columns,
352
* existing lines are not truncated. This prevents characters from being lost
353
* if the terminal display is resized smaller and then larger again.
355
* The top and bottom margins are reset to the top and bottom of the new
356
* screen size. Tab stops are also reset and the current selection is
359
void resizeImage(int new_lines, int new_columns);
362
* Returns the current screen image.
363
* The result is an array of Characters of size [getLines()][getColumns()] which
364
* must be freed by the caller after use.
366
* @param dest Buffer to copy the characters into
367
* @param size Size of @p dest in Characters
368
* @param startLine Index of first line to copy
369
* @param endLine Index of last line to copy
371
void getImage( Character* dest , int size , int startLine , int endLine ) const;
374
* Returns the additional attributes associated with lines in the image.
375
* The most important attribute is LINE_WRAPPED which specifies that the
377
* other attributes control the size of characters in the line.
379
QVector<LineProperty> getLineProperties( int startLine , int endLine ) const;
382
/** Return the number of lines. */
385
/** Return the number of columns. */
386
int getColumns() const
388
/** Return the number of lines in the history buffer. */
389
int getHistLines() const;
391
* Sets the type of storage used to keep lines in the history.
392
* If @p copyPreviousScroll is true then the contents of the previous
393
* history buffer are copied into the new scroll.
395
void setScroll(const HistoryType& , bool copyPreviousScroll = true);
396
/** Returns the type of storage used to keep lines in the history. */
397
const HistoryType& getScroll() const;
399
* Returns true if this screen keeps lines that are scrolled off the screen
400
* in a history buffer.
402
bool hasScroll() const;
405
* Sets the start of the selection.
407
* @param column The column index of the first character in the selection.
408
* @param line The line index of the first character in the selection.
409
* @param blockSelectionMode True if the selection is in column mode.
411
void setSelectionStart(const int column, const int line, const bool blockSelectionMode);
414
* Sets the end of the current selection.
416
* @param column The column index of the last character in the selection.
417
* @param line The line index of the last character in the selection.
419
void setSelectionEnd(const int column, const int line);
422
* Retrieves the start of the selection or the cursor position if there
425
void getSelectionStart(int& column , int& line) const;
428
* Retrieves the end of the selection or the cursor position if there
431
void getSelectionEnd(int& column , int& line) const;
433
/** Clears the current selection */
434
void clearSelection();
437
* Returns true if the character at (@p column, @p line) is part of the
440
bool isSelected(const int column,const int line) const;
443
* Convenience method. Returns the currently selected text.
444
* @param preserveLineBreaks Specifies whether new line characters should
445
* be inserted into the returned text at the end of each terminal line.
447
QString selectedText(bool preserveLineBreaks) const;
450
* Copies part of the output to a stream.
452
* @param decoder A decoder which converts terminal characters into text
453
* @param fromLine The first line in the history to retrieve
454
* @param toLine The last line in the history to retrieve
456
void writeLinesToStream(TerminalCharacterDecoder* decoder, int fromLine, int toLine) const;
459
* Copies the selected characters, set using @see setSelBeginXY and @see setSelExtentXY
462
* @param decoder A decoder which converts terminal characters into text.
463
* PlainTextDecoder is the most commonly used decoder which converts characters
464
* into plain text with no formatting.
465
* @param preserveLineBreaks Specifies whether new line characters should
466
* be inserted into the returned text at the end of each terminal line.
468
void writeSelectionToStream(TerminalCharacterDecoder* decoder , bool
469
preserveLineBreaks = true) const;
472
* Checks if the text between from and to is inside the current
473
* selection. If this is the case, the selection is cleared. The
474
* from and to are coordinates in the current viewable window.
475
* The loc(x,y) macro can be used to generate these values from a
478
* @param from The start of the area to check.
479
* @param to The end of the area to check
481
void checkSelection(int from, int to);
484
* Sets or clears an attribute of the current line.
486
* @param property The attribute to set or clear
487
* Possible properties are:
488
* LINE_WRAPPED: Specifies that the line is wrapped.
489
* LINE_DOUBLEWIDTH: Specifies that the characters in the current line
490
* should be double the normal width.
491
* LINE_DOUBLEHEIGHT:Specifies that the characters in the current line
492
* should be double the normal height.
493
* Double-height lines are formed of two lines containing the same characters,
494
* with both having the LINE_DOUBLEHEIGHT attribute.
495
* This allows other parts of the code to work on the
496
* assumption that all lines are the same height.
498
* @param enable true to apply the attribute to the current line or false to remove it
500
void setLineProperty(LineProperty property , bool enable);
503
* Returns the number of lines that the image has been scrolled up or down by,
504
* since the last call to resetScrolledLines().
506
* a positive return value indicates that the image has been scrolled up,
507
* a negative return value indicates that the image has been scrolled down.
509
int scrolledLines() const;
512
* Returns the region of the image which was last scrolled.
514
* This is the area of the image from the top margin to the
515
* bottom margin when the last scroll occurred.
517
QRect lastScrolledRegion() const;
520
* Resets the count of the number of lines that the image has been scrolled up or down by,
521
* see scrolledLines()
523
void resetScrolledLines();
526
* Returns the number of lines of output which have been
527
* dropped from the history since the last call
528
* to resetDroppedLines()
530
* If the history is not unlimited then it will drop
531
* the oldest lines of output if new lines are added when
534
int droppedLines() const;
537
* Resets the count of the number of lines dropped from
540
void resetDroppedLines();
543
* Fills the buffer @p dest with @p count instances of the default (ie. blank)
546
static void fillWithDefaultChar(Character* dest, int count);
550
//copies a line of text from the screen or history into a stream using a
551
//specified character decoder. Returns the number of lines actually copied,
552
//which may be less than 'count' if (start+count) is more than the number of characters on
555
//line - the line number to copy, from 0 (the earliest line in the history) up to
556
// history->getLines() + lines - 1
557
//start - the first column on the line to copy
558
//count - the number of characters on the line to copy
559
//decoder - a decoder which converts terminal characters (an Character array) into text
560
//appendNewLine - if true a new line character (\n) is appended to the end of the line
561
int copyLineToStream(int line,
564
TerminalCharacterDecoder* decoder,
566
bool preserveLineBreaks) const;
568
//fills a section of the screen image with the character 'c'
569
//the parameters are specified as offsets from the start of the screen image.
570
//the loc(x,y) macro can be used to generate these values from a column,line pair.
571
void clearImage(int loca, int loce, char c);
573
//move screen image between 'sourceBegin' and 'sourceEnd' to 'dest'.
574
//the parameters are specified as offsets from the start of the screen image.
575
//the loc(x,y) macro can be used to generate these values from a column,line pair.
577
//NOTE: moveImage() can only move whole lines
578
void moveImage(int dest, int sourceBegin, int sourceEnd);
579
// scroll up 'i' lines in current region, clearing the bottom 'i' lines
580
void scrollUp(int from, int i);
581
// scroll down 'i' lines in current region, clearing the top 'i' lines
582
void scrollDown(int from, int i);
588
void updateEffectiveRendition();
589
void reverseRendition(Character& p) const;
591
bool isSelectionValid() const;
592
// copies text from 'startIndex' to 'endIndex' to a stream
593
// startIndex and endIndex are positions generated using the loc(x,y) macro
594
void writeToStream(TerminalCharacterDecoder* decoder, int startIndex,
595
int endIndex, bool preserveLineBreaks = true) const;
596
// copies 'count' lines from the screen buffer into 'dest',
597
// starting from 'startLine', where 0 is the first line in the screen buffer
598
void copyFromScreen(Character* dest, int startLine, int count) const;
599
// copies 'count' lines from the history buffer into 'dest',
600
// starting from 'startLine', where 0 is the first line in the history
601
void copyFromHistory(Character* dest, int startLine, int count) const;
604
// screen image ----------------
608
typedef QVector<Character> ImageLine; // [0..columns]
609
ImageLine* screenLines; // [lines]
612
QRect _lastScrolledRegion;
616
QVarLengthArray<LineProperty,64> lineProperties;
618
// history buffer ---------------
619
HistoryScroll* history;
625
// cursor color and rendition info
626
CharacterColor currentForeground;
627
CharacterColor currentBackground;
628
quint8 currentRendition;
630
// margins ----------------
634
// states ----------------
635
int currentModes[MODES_SCREEN];
636
int savedModes[MODES_SCREEN];
638
// ----------------------------
642
// selection -------------------
643
int selBegin; // The first location selected.
644
int selTopLeft; // TopLeft Location.
645
int selBottomRight; // Bottom Right Location.
646
bool blockSelectionMode; // Column selection mode
648
// effective colors and rendition ------------
649
CharacterColor effectiveForeground; // These are derived from
650
CharacterColor effectiveBackground; // the cu_* variables above
651
quint8 effectiveRendition; // to speed up operation
657
: cursorColumn(0),cursorLine(0),rendition(0) {}
662
CharacterColor foreground;
663
CharacterColor background;
665
SavedState savedState;
667
// last position where we added a character
670
static Character defaultChar;