1 /* 2 This file is part of Konsole, KDE's 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 SCREEN_H 24 #define SCREEN_H 25 26 // Qt 27 #include <QRect> 28 #include <QTextStream> 29 #include <QVarLengthArray> 30 31 // Konsole 32 #include "Character.h" 33 #include "History.h" 34 35 #define MODE_Origin 0 36 #define MODE_Wrap 1 37 #define MODE_Insert 2 38 #define MODE_Screen 3 39 #define MODE_Cursor 4 40 #define MODE_NewLine 5 41 #define MODES_SCREEN 6 42 43 namespace Konsole 44 { 45 46 class TerminalCharacterDecoder; 47 48 /** 49 \brief An image of characters with associated attributes. 50 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. 56 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 59 terminal. 60 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() 65 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. 70 */ 71 class Screen 72 { 73 public: 74 /** Construct a new screen image of size @p lines by @p columns. */ 75 Screen(int lines, int columns); 76 ~Screen(); 77 78 // VT100/2 Operations 79 // Cursor Movement 80 81 /** 82 * Move the cursor up by @p n lines. The cursor will stop at the 83 * top margin. 84 */ 85 void cursorUp(int n); 86 /** 87 * Move the cursor down by @p n lines. The cursor will stop at the 88 * bottom margin. 89 */ 90 void cursorDown(int n); 91 /** 92 * Move the cursor to the left by @p n columns. 93 * The cursor will stop at the first column. 94 */ 95 void cursorLeft(int n); 96 /** 97 * Moves cursor to beginning of the line by @p n lines down. 98 * The cursor will stop at the beginning of the line. 99 */ 100 void cursorNextLine(int n); 101 /** 102 * Moves cursor to beginning of the line by @p n lines up. 103 * The cursor will stop at the beginning of the line. 104 */ 105 void cursorPreviousLine(int n); 106 /** 107 * Move the cursor to the right by @p n columns. 108 * The cursor will stop at the right-most column. 109 */ 110 void cursorRight(int n); 111 /** Position the cursor on line @p y. */ 112 void setCursorY(int y); 113 /** Position the cursor at column @p x. */ 114 void setCursorX(int x); 115 /** Position the cursor at line @p y, column @p x. */ 116 void setCursorYX(int y, int x); 117 /** 118 * Sets the margins for scrolling the screen. 119 * 120 * @param topLine The top line of the new scrolling margin. 121 * @param bottomLine The bottom line of the new scrolling margin. 122 */ 123 void setMargins(int topLine , int bottomLine); 124 /** Returns the top line of the scrolling region. */ 125 int topMargin() const; 126 /** Returns the bottom line of the scrolling region. */ 127 int bottomMargin() const; 128 129 /** 130 * Resets the scrolling margins back to the top and bottom lines 131 * of the screen. 132 */ 133 void setDefaultMargins(); 134 135 /** 136 * Moves the cursor down one line, if the MODE_NewLine mode 137 * flag is enabled then the cursor is returned to the leftmost 138 * column first. 139 * 140 * Equivalent to NextLine() if the MODE_NewLine flag is set 141 * or index() otherwise. 142 */ 143 void newLine(); 144 /** 145 * Moves the cursor down one line and positions it at the beginning 146 * of the line. Equivalent to calling Return() followed by index() 147 */ 148 void nextLine(); 149 150 /** 151 * Move the cursor down one line. If the cursor is on the bottom 152 * line of the scrolling region (as returned by bottomMargin()) the 153 * scrolling region is scrolled up by one line instead. 154 */ 155 void index(); 156 /** 157 * Move the cursor up one line. If the cursor is on the top line 158 * of the scrolling region (as returned by topMargin()) the scrolling 159 * region is scrolled down by one line instead. 160 */ 161 void reverseIndex(); 162 163 /** 164 * Scroll the scrolling region of the screen up by @p n lines. 165 * The scrolling region is initially the whole screen, but can be changed 166 * using setMargins() 167 */ 168 void scrollUp(int n); 169 /** 170 * Scroll the scrolling region of the screen down by @p n lines. 171 * The scrolling region is initially the whole screen, but can be changed 172 * using setMargins() 173 */ 174 void scrollDown(int n); 175 /** 176 * Moves the cursor to the beginning of the current line. 177 * Equivalent to setCursorX(0) 178 */ 179 void toStartOfLine(); 180 /** 181 * Moves the cursor one column to the left and erases the character 182 * at the new cursor position. 183 */ 184 void backspace(); 185 /** Moves the cursor @p n tab-stops to the right. */ 186 void tab(int n = 1); 187 /** Moves the cursor @p n tab-stops to the left. */ 188 void backtab(int n); 189 190 // Editing 191 192 /** 193 * Erase @p n characters beginning from the current cursor position. 194 * This is equivalent to over-writing @p n characters starting with the current 195 * cursor position with spaces. 196 * If @p n is 0 then one character is erased. 197 */ 198 void eraseChars(int n); 199 /** 200 * Delete @p n characters beginning from the current cursor position. 201 * If @p n is 0 then one character is deleted. 202 */ 203 void deleteChars(int n); 204 /** 205 * Insert @p n blank characters beginning from the current cursor position. 206 * The position of the cursor is not altered. 207 * If @p n is 0 then one character is inserted. 208 */ 209 void insertChars(int n); 210 /** 211 * Repeat the preceeding graphic character @count times, including SPACE. 212 * If @count is 0 then the character is repeated once. 213 */ 214 void repeatChars(int count); 215 /** 216 * Removes @p n lines beginning from the current cursor position. 217 * The position of the cursor is not altered. 218 * If @p n is 0 then one line is removed. 219 */ 220 void deleteLines(int n); 221 /** 222 * Inserts @p lines beginning from the current cursor position. 223 * The position of the cursor is not altered. 224 * If @p n is 0 then one line is inserted. 225 */ 226 void insertLines(int n); 227 /** Clears all the tab stops. */ 228 void clearTabStops(); 229 /** Sets or removes a tab stop at the cursor's current column. */ 230 void changeTabStop(bool set); 231 232 /** Resets (clears) the specified screen @p mode. */ 233 void resetMode(int mode); 234 /** Sets (enables) the specified screen @p mode. */ 235 void setMode(int mode); 236 /** 237 * Saves the state of the specified screen @p mode. It can be restored 238 * using restoreMode() 239 */ 240 void saveMode(int mode); 241 /** Restores the state of a screen @p mode saved by calling saveMode() */ 242 void restoreMode(int mode); 243 /** Returns whether the specified screen @p mode is enabled or not .*/ 244 bool getMode(int mode) const; 245 246 /** 247 * Saves the current position and appearance (text color and style) of the cursor. 248 * It can be restored by calling restoreCursor() 249 */ 250 void saveCursor(); 251 /** Restores the position and appearance of the cursor. See saveCursor() */ 252 void restoreCursor(); 253 254 /** Clear the whole screen, moving the current screen contents into the history first. */ 255 void clearEntireScreen(); 256 /** 257 * Clear the area of the screen from the current cursor position to the end of 258 * the screen. 259 */ 260 void clearToEndOfScreen(); 261 /** 262 * Clear the area of the screen from the current cursor position to the start 263 * of the screen. 264 */ 265 void clearToBeginOfScreen(); 266 /** Clears the whole of the line on which the cursor is currently positioned. */ 267 void clearEntireLine(); 268 /** Clears from the current cursor position to the end of the line. */ 269 void clearToEndOfLine(); 270 /** Clears from the current cursor position to the beginning of the line. */ 271 void clearToBeginOfLine(); 272 273 /** Fills the entire screen with the letter 'E' */ 274 void helpAlign(); 275 276 /** 277 * Enables the given @p rendition flag. Rendition flags control the appearance 278 * of characters on the screen. 279 * 280 * @see Character::rendition 281 */ 282 void setRendition(int rendition); 283 /** 284 * Disables the given @p rendition flag. Rendition flags control the appearance 285 * of characters on the screen. 286 * 287 * @see Character::rendition 288 */ 289 void resetRendition(int rendition); 290 291 /** 292 * Sets the cursor's foreground color. 293 * @param space The color space used by the @p color argument 294 * @param color The new foreground color. The meaning of this depends on 295 * the color @p space used. 296 * 297 * @see CharacterColor 298 */ 299 void setForeColor(int space, int color); 300 /** 301 * Sets the cursor's background color. 302 * @param space The color space used by the @p color argumnet. 303 * @param color The new background color. The meaning of this depends on 304 * the color @p space used. 305 * 306 * @see CharacterColor 307 */ 308 void setBackColor(int space, int color); 309 /** 310 * Resets the cursor's color back to the default and sets the 311 * character's rendition flags back to the default settings. 312 */ 313 void setDefaultRendition(); 314 315 /** Returns the column which the cursor is positioned at. */ 316 int getCursorX() const; 317 /** Returns the line which the cursor is positioned on. */ 318 int getCursorY() const; 319 320 /** Clear the entire screen and move the cursor to the home position. 321 * Equivalent to calling clearEntireScreen() followed by home(). 322 */ 323 void clear(); 324 /** 325 * Sets the position of the cursor to the 'home' position at the top-left 326 * corner of the screen (0,0) 327 */ 328 void home(); 329 /** 330 * Resets the state of the screen. This resets the various screen modes 331 * back to their default states. The cursor style and colors are reset 332 * (as if setDefaultRendition() had been called) 333 * 334 * <ul> 335 * <li>Line wrapping is enabled.</li> 336 * <li>Origin mode is disabled.</li> 337 * <li>Insert mode is disabled.</li> 338 * <li>Cursor mode is enabled. TODO Document me</li> 339 * <li>Screen mode is disabled. TODO Document me</li> 340 * <li>New line mode is disabled. TODO Document me</li> 341 * </ul> 342 * 343 * If @p clearScreen is true then the screen contents are erased entirely, 344 * otherwise they are unaltered. 345 */ 346 void reset(bool clearScreen = true); 347 348 /** 349 * Displays a new character at the current cursor position. 350 * 351 * If the cursor is currently positioned at the right-edge of the screen and 352 * line wrapping is enabled then the character is added at the start of a new 353 * line below the current one. 354 * 355 * If the MODE_Insert screen mode is currently enabled then the character 356 * is inserted at the current cursor position, otherwise it will replace the 357 * character already at the current cursor position. 358 */ 359 void displayCharacter(wchar_t c); 360 361 // Do composition with last shown character FIXME: Not implemented yet for KDE 4 362 void compose(const QString& compose); 363 364 /** 365 * Resizes the image to a new fixed size of @p new_lines by @p new_columns. 366 * In the case that @p new_columns is smaller than the current number of columns, 367 * existing lines are not truncated. This prevents characters from being lost 368 * if the terminal display is resized smaller and then larger again. 369 * 370 * The top and bottom margins are reset to the top and bottom of the new 371 * screen size. Tab stops are also reset and the current selection is 372 * cleared. 373 */ 374 void resizeImage(int new_lines, int new_columns); 375 376 /** 377 * Returns the current screen image. 378 * The result is an array of Characters of size [getLines()][getColumns()] which 379 * must be freed by the caller after use. 380 * 381 * @param dest Buffer to copy the characters into 382 * @param size Size of @p dest in Characters 383 * @param startLine Index of first line to copy 384 * @param endLine Index of last line to copy 385 */ 386 void getImage( Character* dest , int size , int startLine , int endLine ) const; 387 388 /** 389 * Returns the additional attributes associated with lines in the image. 390 * The most important attribute is LINE_WRAPPED which specifies that the 391 * line is wrapped, 392 * other attributes control the size of characters in the line. 393 */ 394 QVector<LineProperty> getLineProperties( int startLine , int endLine ) const; 395 396 397 /** Return the number of lines. */ getLines()398 int getLines() const 399 { return lines; } 400 /** Return the number of columns. */ getColumns()401 int getColumns() const 402 { return columns; } 403 /** Return the number of lines in the history buffer. */ 404 int getHistLines() const; 405 /** 406 * Sets the type of storage used to keep lines in the history. 407 * If @p copyPreviousScroll is true then the contents of the previous 408 * history buffer are copied into the new scroll. 409 */ 410 void setScroll(const HistoryType& , bool copyPreviousScroll = true); 411 /** Returns the type of storage used to keep lines in the history. */ 412 const HistoryType& getScroll() const; 413 /** 414 * Returns true if this screen keeps lines that are scrolled off the screen 415 * in a history buffer. 416 */ 417 bool hasScroll() const; 418 419 /** 420 * Sets the start of the selection. 421 * 422 * @param column The column index of the first character in the selection. 423 * @param line The line index of the first character in the selection. 424 * @param blockSelectionMode True if the selection is in column mode. 425 */ 426 void setSelectionStart(const int column, const int line, const bool blockSelectionMode); 427 428 /** 429 * Sets the end of the current selection. 430 * 431 * @param column The column index of the last character in the selection. 432 * @param line The line index of the last character in the selection. 433 */ 434 void setSelectionEnd(const int column, const int line); 435 436 /** 437 * Retrieves the start of the selection or the cursor position if there 438 * is no selection. 439 */ 440 void getSelectionStart(int& column , int& line) const; 441 442 /** 443 * Retrieves the end of the selection or the cursor position if there 444 * is no selection. 445 */ 446 void getSelectionEnd(int& column , int& line) const; 447 448 /** Clears the current selection */ 449 void clearSelection(); 450 451 /** 452 * Returns true if the character at (@p column, @p line) is part of the 453 * current selection. 454 */ 455 bool isSelected(const int column,const int line) const; 456 457 /** 458 * Convenience method. Returns the currently selected text. 459 * @param preserveLineBreaks Specifies whether new line characters should 460 * be inserted into the returned text at the end of each terminal line. 461 */ 462 QString selectedText(bool preserveLineBreaks) const; 463 464 /** 465 * Copies part of the output to a stream. 466 * 467 * @param decoder A decoder which converts terminal characters into text 468 * @param fromLine The first line in the history to retrieve 469 * @param toLine The last line in the history to retrieve 470 */ 471 void writeLinesToStream(TerminalCharacterDecoder* decoder, int fromLine, int toLine) const; 472 473 /** 474 * Copies the selected characters, set using @see setSelBeginXY and @see setSelExtentXY 475 * into a stream. 476 * 477 * @param decoder A decoder which converts terminal characters into text. 478 * PlainTextDecoder is the most commonly used decoder which converts characters 479 * into plain text with no formatting. 480 * @param preserveLineBreaks Specifies whether new line characters should 481 * be inserted into the returned text at the end of each terminal line. 482 */ 483 void writeSelectionToStream(TerminalCharacterDecoder* decoder , bool 484 preserveLineBreaks = true) const; 485 486 /** 487 * Checks if the text between from and to is inside the current 488 * selection. If this is the case, the selection is cleared. The 489 * from and to are coordinates in the current viewable window. 490 * The loc(x,y) macro can be used to generate these values from a 491 * column,line pair. 492 * 493 * @param from The start of the area to check. 494 * @param to The end of the area to check 495 */ 496 void checkSelection(int from, int to); 497 498 /** 499 * Sets or clears an attribute of the current line. 500 * 501 * @param property The attribute to set or clear 502 * Possible properties are: 503 * LINE_WRAPPED: Specifies that the line is wrapped. 504 * LINE_DOUBLEWIDTH: Specifies that the characters in the current line 505 * should be double the normal width. 506 * LINE_DOUBLEHEIGHT:Specifies that the characters in the current line 507 * should be double the normal height. 508 * Double-height lines are formed of two lines containing the same characters, 509 * with both having the LINE_DOUBLEHEIGHT attribute. 510 * This allows other parts of the code to work on the 511 * assumption that all lines are the same height. 512 * 513 * @param enable true to apply the attribute to the current line or false to remove it 514 */ 515 void setLineProperty(LineProperty property , bool enable); 516 517 /** 518 * Returns the number of lines that the image has been scrolled up or down by, 519 * since the last call to resetScrolledLines(). 520 * 521 * a positive return value indicates that the image has been scrolled up, 522 * a negative return value indicates that the image has been scrolled down. 523 */ 524 int scrolledLines() const; 525 526 /** 527 * Returns the region of the image which was last scrolled. 528 * 529 * This is the area of the image from the top margin to the 530 * bottom margin when the last scroll occurred. 531 */ 532 QRect lastScrolledRegion() const; 533 534 /** 535 * Resets the count of the number of lines that the image has been scrolled up or down by, 536 * see scrolledLines() 537 */ 538 void resetScrolledLines(); 539 540 /** 541 * Returns the number of lines of output which have been 542 * dropped from the history since the last call 543 * to resetDroppedLines() 544 * 545 * If the history is not unlimited then it will drop 546 * the oldest lines of output if new lines are added when 547 * it is full. 548 */ 549 int droppedLines() const; 550 551 /** 552 * Resets the count of the number of lines dropped from 553 * the history. 554 */ 555 void resetDroppedLines(); 556 557 /** 558 * Fills the buffer @p dest with @p count instances of the default (ie. blank) 559 * Character style. 560 */ 561 static void fillWithDefaultChar(Character* dest, int count); 562 563 private: 564 Screen(const Screen &) = delete; 565 Screen &operator=(const Screen &) = delete; 566 567 //copies a line of text from the screen or history into a stream using a 568 //specified character decoder. Returns the number of lines actually copied, 569 //which may be less than 'count' if (start+count) is more than the number of characters on 570 //the line 571 // 572 //line - the line number to copy, from 0 (the earliest line in the history) up to 573 // history->getLines() + lines - 1 574 //start - the first column on the line to copy 575 //count - the number of characters on the line to copy 576 //decoder - a decoder which converts terminal characters (an Character array) into text 577 //appendNewLine - if true a new line character (\n) is appended to the end of the line 578 int copyLineToStream(int line, 579 int start, 580 int count, 581 TerminalCharacterDecoder* decoder, 582 bool appendNewLine, 583 bool preserveLineBreaks) const; 584 585 //fills a section of the screen image with the character 'c' 586 //the parameters are specified as offsets from the start of the screen image. 587 //the loc(x,y) macro can be used to generate these values from a column,line pair. 588 void clearImage(int loca, int loce, char c); 589 590 //move screen image between 'sourceBegin' and 'sourceEnd' to 'dest'. 591 //the parameters are specified as offsets from the start of the screen image. 592 //the loc(x,y) macro can be used to generate these values from a column,line pair. 593 // 594 //NOTE: moveImage() can only move whole lines 595 void moveImage(int dest, int sourceBegin, int sourceEnd); 596 // scroll up 'i' lines in current region, clearing the bottom 'i' lines 597 void scrollUp(int from, int i); 598 // scroll down 'i' lines in current region, clearing the top 'i' lines 599 void scrollDown(int from, int i); 600 601 void addHistLine(); 602 603 void initTabStops(); 604 605 void updateEffectiveRendition(); 606 void reverseRendition(Character& p) const; 607 608 bool isSelectionValid() const; 609 // copies text from 'startIndex' to 'endIndex' to a stream 610 // startIndex and endIndex are positions generated using the loc(x,y) macro 611 void writeToStream(TerminalCharacterDecoder* decoder, int startIndex, 612 int endIndex, bool preserveLineBreaks = true) const; 613 // copies 'count' lines from the screen buffer into 'dest', 614 // starting from 'startLine', where 0 is the first line in the screen buffer 615 void copyFromScreen(Character* dest, int startLine, int count) const; 616 // copies 'count' lines from the history buffer into 'dest', 617 // starting from 'startLine', where 0 is the first line in the history 618 void copyFromHistory(Character* dest, int startLine, int count) const; 619 620 621 // screen image ---------------- 622 int lines; 623 int columns; 624 625 typedef QVector<Character> ImageLine; // [0..columns] 626 ImageLine* screenLines; // [lines] 627 628 int _scrolledLines; 629 QRect _lastScrolledRegion; 630 631 int _droppedLines; 632 633 QVarLengthArray<LineProperty,64> lineProperties; 634 635 // history buffer --------------- 636 HistoryScroll* history; 637 638 // cursor location 639 int cuX; 640 int cuY; 641 642 // cursor color and rendition info 643 CharacterColor currentForeground; 644 CharacterColor currentBackground; 645 quint8 currentRendition; 646 647 // margins ---------------- 648 int _topMargin; 649 int _bottomMargin; 650 651 // states ---------------- 652 bool currentModes[MODES_SCREEN]; 653 bool savedModes[MODES_SCREEN]; 654 655 // ---------------------------- 656 657 QBitArray tabStops; 658 659 // selection ------------------- 660 int selBegin; // The first location selected. 661 int selTopLeft; // TopLeft Location. 662 int selBottomRight; // Bottom Right Location. 663 bool blockSelectionMode; // Column selection mode 664 665 // effective colors and rendition ------------ 666 CharacterColor effectiveForeground; // These are derived from 667 CharacterColor effectiveBackground; // the cu_* variables above 668 quint8 effectiveRendition; // to speed up operation 669 670 class SavedState 671 { 672 public: SavedState()673 SavedState() 674 : cursorColumn(0),cursorLine(0),rendition(0) {} 675 676 int cursorColumn; 677 int cursorLine; 678 quint8 rendition; 679 CharacterColor foreground; 680 CharacterColor background; 681 }; 682 SavedState savedState; 683 684 // last position where we added a character 685 int lastPos; 686 687 // used in REP (repeating char) 688 unsigned short lastDrawnChar; 689 690 static Character defaultChar; 691 }; 692 693 } 694 695 #endif // SCREEN_H 696