apps/konsole/src/Screen.h

   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 <QtCore/QRect>
  28 #include <QtCore/QTextStream>
  29 #include <QtCore/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      * Move the cursor to the right by @p n columns.
  98      * The cursor will stop at the right-most column.
  99      */
 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);
 107     /**
 108      * Sets the margins for scrolling the screen.
 109      *
 110      * @param topLine The top line of the new scrolling margin.
 111      * @param bottomLine The bottom line of the new scrolling margin.
 112      */
 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;
 118
 119     /**
 120      * Resets the scrolling margins back to the top and bottom lines
 121      * of the screen.
 122      */
 123     void setDefaultMargins();
 124
 125     /**
 126      * Moves the cursor down one line, if the MODE_NewLine mode
 127      * flag is enabled then the cursor is returned to the leftmost
 128      * column first.
 129      *
 130      * Equivalent to NextLine() if the MODE_NewLine flag is set
 131      * or index() otherwise.
 132      */
 133     void newLine();
 134     /**
 135      * Moves the cursor down one line and positions it at the beginning
 136      * of the line.  Equivalent to calling Return() followed by index()
 137      */
 138     void nextLine();
 139
 140     /**
 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.
 144      */
 145     void index();
 146     /**
 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.
 150      */
 151     void reverseIndex();
 152
 153     /**
 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
 156      * using setMargins()
 157      */
 158     void scrollUp(int n);
 159     /**
 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
 162      * using setMargins()
 163      */
 164     void scrollDown(int n);
 165     /**
 166      * Moves the cursor to the beginning of the current line.
 167      * Equivalent to setCursorX(0)
 168      */
 169     void toStartOfLine();
 170     /**
 171      * Moves the cursor one column to the left and erases the character
 172      * at the new cursor position.
 173      */
 174     void backspace();
 175     /** Moves the cursor @p n tab-stops to the right. */
 176     void tab(int n = 1);
 177     /** Moves the cursor @p n tab-stops to the left. */
 178     void backtab(int n);
 179
 180     // Editing
 181
 182     /**
 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.
 187      */
 188     void eraseChars(int n);
 189     /**
 190      * Delete @p n characters beginning from the current cursor position.
 191      * If @p n is 0 then one character is deleted.
 192      */
 193     void deleteChars(int n);
 194     /**
 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.
 198      */
 199     void insertChars(int n);
 200     /**
 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.
 204      */
 205     void deleteLines(int n);
 206     /**
 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.
 210      */
 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);
 216
 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);
 221     /**
 222      * Saves the state of the specified screen @p mode.  It can be restored
 223      * using restoreMode()
 224      */
 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;
 230
 231     /**
 232      * Saves the current position and appearance (text color and style) of the cursor.
 233      * It can be restored by calling restoreCursor()
 234      */
 235     void saveCursor();
 236     /** Restores the position and appearance of the cursor.  See saveCursor() */
 237     void restoreCursor();
 238
 239     /** Clear the whole screen, moving the current screen contents into the history first. */
 240     void clearEntireScreen();
 241     /**
 242      * Clear the area of the screen from the current cursor position to the end of
 243      * the screen.
 244      */
 245     void clearToEndOfScreen();
 246     /**
 247      * Clear the area of the screen from the current cursor position to the start
 248      * of the screen.
 249      */
 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();
 257
 258     /** Fills the entire screen with the letter 'E' */
 259     void helpAlign();
 260
 261     /**
 262      * Enables the given @p rendition flag.  Rendition flags control the appearance
 263      * of characters on the screen.
 264      *
 265      * @see Character::rendition
 266      */
 267     void setRendition(int rendition);
 268     /**
 269      * Disables the given @p rendition flag.  Rendition flags control the appearance
 270      * of characters on the screen.
 271      *
 272      * @see Character::rendition
 273      */
 274     void resetRendition(int rendition);
 275
 276     /**
 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.
 281      *
 282      * @see CharacterColor
 283      */
 284     void setForeColor(int space, int color);
 285     /**
 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.
 290      *
 291      * @see CharacterColor
 292      */
 293     void setBackColor(int space, int color);
 294     /**
 295      * Resets the cursor's color back to the default and sets the
 296      * character's rendition flags back to the default settings.
 297      */
 298     void setDefaultRendition();
 299
 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;
 304
 305     /** Clear the entire screen and move the cursor to the home position.
 306      * Equivalent to calling clearEntireScreen() followed by home().
 307      */
 308     void clear();
 309     /**
 310      * Sets the position of the cursor to the 'home' position at the top-left
 311      * corner of the screen (0,0)
 312      */
 313     void home();
 314     /**
 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)
 318      *
 319      * <ul>
 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>
 326      * </ul>
 327      *
 328      * If @p clearScreen is true then the screen contents are erased entirely,
 329      * otherwise they are unaltered.
 330      */
 331     void reset(bool clearScreen = true);
 332
 333     /**
 334      * Displays a new character at the current cursor position.
 335      *
 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.
 339      *
 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.
 343      */
 344     void displayCharacter(unsigned short c);
 345
 346     // Do composition with last shown character FIXME: Not implemented yet for KDE 4
 347     void compose(const QString& compose);
 348
 349     /**
 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.
 354      *
 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
 357      * cleared.
 358      */
 359     void resizeImage(int new_lines, int new_columns);
 360
 361     /**
 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.
 365      *
 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
 370      */
 371     void getImage( Character* dest , int size , int startLine , int endLine ) const;
 372
 373     /**
 374      * Returns the additional attributes associated with lines in the image.
 375      * The most important attribute is LINE_WRAPPED which specifies that the
 376      * line is wrapped,
 377      * other attributes control the size of characters in the line.
 378      */
 379     QVector<LineProperty> getLineProperties( int startLine , int endLine ) const;
 380
 381
 382     /** Return the number of lines. */
 383     int getLines() const
 384     { return lines; }
 385     /** Return the number of columns. */
 386     int getColumns() const
 387     { return columns; }
 388     /** Return the number of lines in the history buffer. */
 389     int getHistLines() const;
 390     /**
 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.
 394      */
 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;
 398     /**
 399      * Returns true if this screen keeps lines that are scrolled off the screen
 400      * in a history buffer.
 401      */
 402     bool hasScroll() const;
 403
 404     /**
 405      * Sets the start of the selection.
 406      *
 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.
 410      */
 411     void setSelectionStart(const int column, const int line, const bool blockSelectionMode);
 412
 413     /**
 414      * Sets the end of the current selection.
 415      *
 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.
 418      */
 419     void setSelectionEnd(const int column, const int line);
 420
 421     /**
 422      * Retrieves the start of the selection or the cursor position if there
 423      * is no selection.
 424      */
 425     void getSelectionStart(int& column , int& line) const;
 426
 427     /**
 428      * Retrieves the end of the selection or the cursor position if there
 429      * is no selection.
 430      */
 431     void getSelectionEnd(int& column , int& line) const;
 432
 433     /** Clears the current selection */
 434     void clearSelection();
 435
 436     /**
 437       *  Returns true if the character at (@p column, @p line) is part of the
 438       *  current selection.
 439       */
 440     bool isSelected(const int column,const int line) const;
 441
 442     /**
 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.
 446      */
 447     QString selectedText(bool preserveLineBreaks) const;
 448
 449     /**
 450      * Copies part of the output to a stream.
 451      *
 452      * @param decoder A decoder which coverts terminal characters into text
 453      * @param from The first line in the history to retrieve
 454      * @param to The last line in the history to retrieve
 455      */
 456     void writeLinesToStream(TerminalCharacterDecoder* decoder, int fromLine, int toLine) const;
 457
 458     /**
 459      * Copies the selected characters, set using @see setSelBeginXY and @see setSelExtentXY
 460      * into a stream.
 461      *
 462      * @param decoder A decoder which converts terminal characters into text.
 463      * PlainTextDecoder is the most commonly used decoder which coverts 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.
 467      */
 468     void writeSelectionToStream(TerminalCharacterDecoder* decoder , bool
 469                                 preserveLineBreaks = true) const;
 470
 471     /** TODO Document me */
 472     void checkSelection(int from, int to);
 473
 474     /**
 475      * Sets or clears an attribute of the current line.
 476      *
 477      * @param property The attribute to set or clear
 478      * Possible properties are:
 479      * LINE_WRAPPED:     Specifies that the line is wrapped.
 480      * LINE_DOUBLEWIDTH: Specifies that the characters in the current line
 481      *                   should be double the normal width.
 482      * LINE_DOUBLEHEIGHT:Specifies that the characters in the current line
 483      *                   should be double the normal height.
 484      *                   Double-height lines are formed of two lines containing the same characters,
 485      *                   with both having the LINE_DOUBLEHEIGHT attribute.
 486      *                   This allows other parts of the code to work on the
 487      *                   assumption that all lines are the same height.
 488      *
 489      * @param enable true to apply the attribute to the current line or false to remove it
 490      */
 491     void setLineProperty(LineProperty property , bool enable);
 492
 493     /**
 494      * Returns the number of lines that the image has been scrolled up or down by,
 495      * since the last call to resetScrolledLines().
 496      *
 497      * a positive return value indicates that the image has been scrolled up,
 498      * a negative return value indicates that the image has been scrolled down.
 499      */
 500     int scrolledLines() const;
 501
 502     /**
 503      * Returns the region of the image which was last scrolled.
 504      *
 505      * This is the area of the image from the top margin to the
 506      * bottom margin when the last scroll occurred.
 507      */
 508     QRect lastScrolledRegion() const;
 509
 510     /**
 511      * Resets the count of the number of lines that the image has been scrolled up or down by,
 512      * see scrolledLines()
 513      */
 514     void resetScrolledLines();
 515
 516     /**
 517      * Returns the number of lines of output which have been
 518      * dropped from the history since the last call
 519      * to resetDroppedLines()
 520      *
 521      * If the history is not unlimited then it will drop
 522      * the oldest lines of output if new lines are added when
 523      * it is full.
 524      */
 525     int droppedLines() const;
 526
 527     /**
 528      * Resets the count of the number of lines dropped from
 529      * the history.
 530      */
 531     void resetDroppedLines();
 532
 533     /**
 534       * Fills the buffer @p dest with @p count instances of the default (ie. blank)
 535       * Character style.
 536       */
 537     static void fillWithDefaultChar(Character* dest, int count);
 538
 539 private:
 540
 541     //copies a line of text from the screen or history into a stream using a
 542     //specified character decoder.  Returns the number of lines actually copied,
 543     //which may be less than 'count' if (start+count) is more than the number of characters on
 544     //the line
 545     //
 546     //line - the line number to copy, from 0 (the earliest line in the history) up to
 547     //         history->getLines() + lines - 1
 548     //start - the first column on the line to copy
 549     //count - the number of characters on the line to copy
 550     //decoder - a decoder which coverts terminal characters (an Character array) into text
 551     //appendNewLine - if true a new line character (\n) is appended to the end of the line
 552     int  copyLineToStream(int line,
 553                           int start,
 554                           int count,
 555                           TerminalCharacterDecoder* decoder,
 556                           bool appendNewLine,
 557                           bool preserveLineBreaks) const;
 558
 559     //fills a section of the screen image with the character 'c'
 560     //the parameters are specified as offsets from the start of the screen image.
 561     //the loc(x,y) macro can be used to generate these values from a column,line pair.
 562     void clearImage(int loca, int loce, char c);
 563
 564     //move screen image between 'sourceBegin' and 'sourceEnd' to 'dest'.
 565     //the parameters are specified as offsets from the start of the screen image.
 566     //the loc(x,y) macro can be used to generate these values from a column,line pair.
 567     //
 568     //NOTE: moveImage() can only move whole lines
 569     void moveImage(int dest, int sourceBegin, int sourceEnd);
 570     // scroll up 'i' lines in current region, clearing the bottom 'i' lines
 571     void scrollUp(int from, int i);
 572     // scroll down 'i' lines in current region, clearing the top 'i' lines
 573     void scrollDown(int from, int i);
 574
 575     void addHistLine();
 576
 577     void initTabStops();
 578
 579     void updateEffectiveRendition();
 580     void reverseRendition(Character& p) const;
 581
 582     bool isSelectionValid() const;
 583     // copies text from 'startIndex' to 'endIndex' to a stream
 584     // startIndex and endIndex are positions generated using the loc(x,y) macro
 585     void writeToStream(TerminalCharacterDecoder* decoder, int startIndex,
 586                        int endIndex, bool preserveLineBreaks = true) const;
 587     // copies 'count' lines from the screen buffer into 'dest',
 588     // starting from 'startLine', where 0 is the first line in the screen buffer
 589     void copyFromScreen(Character* dest, int startLine, int count) const;
 590     // copies 'count' lines from the history buffer into 'dest',
 591     // starting from 'startLine', where 0 is the first line in the history
 592     void copyFromHistory(Character* dest, int startLine, int count) const;
 593
 594
 595     // screen image ----------------
 596     int lines;
 597     int columns;
 598
 599     typedef QVector<Character> ImageLine;      // [0..columns]
 600     ImageLine*          screenLines;    // [lines]
 601
 602     int _scrolledLines;
 603     QRect _lastScrolledRegion;
 604
 605     int _droppedLines;
 606
 607     QVarLengthArray<LineProperty,64> lineProperties;
 608
 609     // history buffer ---------------
 610     HistoryScroll* history;
 611
 612     // cursor location
 613     int cuX;
 614     int cuY;
 615
 616     // cursor color and rendition info
 617     CharacterColor currentForeground;
 618     CharacterColor currentBackground;
 619     quint8 currentRendition;
 620
 621     // margins ----------------
 622     int _topMargin;
 623     int _bottomMargin;
 624
 625     // states ----------------
 626     int currentModes[MODES_SCREEN];
 627     int savedModes[MODES_SCREEN];
 628
 629     // ----------------------------
 630
 631     QBitArray tabStops;
 632
 633     // selection -------------------
 634     int selBegin; // The first location selected.
 635     int selTopLeft;    // TopLeft Location.
 636     int selBottomRight;    // Bottom Right Location.
 637     bool blockSelectionMode;  // Column selection mode
 638
 639     // effective colors and rendition ------------
 640     CharacterColor effectiveForeground; // These are derived from
 641     CharacterColor effectiveBackground; // the cu_* variables above
 642     quint8 effectiveRendition;          // to speed up operation
 643
 644     class SavedState
 645     {
 646     public:
 647         SavedState()
 648         : cursorColumn(0),cursorLine(0),rendition(0) {}
 649
 650         int cursorColumn;
 651         int cursorLine;
 652         quint8 rendition;
 653         CharacterColor foreground;
 654         CharacterColor background;
 655     };
 656     SavedState savedState;
 657
 658     // last position where we added a character
 659     int lastPos;
 660
 661     static Character defaultChar;
 662 };
 663
 664 }
 665
 666 #endif // SCREEN_H