src/Widgets/BaulkTerm/qtermwidget/Screen.h

   1 //  This file is part of Konsole, KDE's terminal.
   2 //
   3 //  Copyright (C) 2007 by Robert Knight <robertknight@gmail.com>
   4 //  Copyright (C) 1997,1998 by Lars Doelle <lars.doelle@on-line.de>
   5 //
   6 //  Rewritten for QT4 by e_k <e_k at users.sourceforge.net>, Copyright (C)2008
   7 //  Forked for Baulk - Copyright (C) 2008-2009 - Jacob Alexander <haata at users.sf.net>
   8 //
   9 //  This program is free software; you can redistribute it and/or modify
  10 //  it under the terms of the GNU General Public License as published by
  11 //  the Free Software Foundation; either version 2 of the License, or
  12 //  any later version, including version 3 of the License.
  13 //
  14 //  This program is distributed in the hope that it will be useful,
  15 //  but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 //  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17 //  GNU General Public License for more details.
  18 //
  19 //  You should have received a copy of the GNU General Public License
  20 //  along with this program.  If not, see <http://www.gnu.org/licenses/>.
  21
  22 #ifndef SCREEN_H
  23 #define SCREEN_H
  24
  25 // Qt
  26 #include <QtCore/QRect>
  27 #include <QtCore/QTextStream>
  28 #include <QtCore/QVarLengthArray>
  29
  30 // Konsole
  31 #include "Character.h"
  32 #include "History.h"
  33
  34 #define MODE_Origin    0
  35 #define MODE_Wrap      1
  36 #define MODE_Insert    2
  37 #define MODE_Screen    3
  38 #define MODE_Cursor    4
  39 #define MODE_NewLine   5
  40 #define MODES_SCREEN   6
  41
  42 namespace Konsole
  43 {
  44
  45 /*!
  46 */
  47 struct ScreenParm
  48 {
  49   int mode[MODES_SCREEN];
  50 };
  51
  52 class TerminalCharacterDecoder;
  53
  54 /*!
  55     \brief An image of characters with associated attributes.
  56
  57     The terminal emulation ( Emulation ) receives a serial stream of
  58     characters from the program currently running in the terminal.
  59     From this stream it creates an image of characters which is ultimately
  60     rendered by the display widget ( TerminalDisplay ).  Some types of emulation
  61     may have more than one screen image.
  62
  63     getImage() is used to retrieve the currently visible image
  64     which is then used by the display widget to draw the output from the
  65     terminal.
  66
  67     The number of lines of output history which are kept in addition to the current
  68     screen image depends on the history scroll being used to store the output.
  69     The scroll is specified using setScroll()
  70     The output history can be retrieved using writeToStream()
  71
  72     The screen image has a selection associated with it, specified using
  73     setSelectionStart() and setSelectionEnd().  The selected text can be retrieved
  74     using selectedText().  When getImage() is used to retrieve the the visible image,
  75     characters which are part of the selection have their colours inverted.
  76 */
  77 class Screen
  78 {
  79 public:
  80     /*! Construct a new screen image of size @p lines by @p columns. */
  81     Screen(int lines, int columns);
  82     ~Screen();
  83
  84     // VT100/2 Operations
  85     // Cursor Movement
  86
  87     /*! Move the cursor up by @p n lines. */
  88     void cursorUp    (int n);
  89     /*! Move the cursor down by @p n lines. */
  90     void cursorDown  (int n);
  91     /*! Move the cursor to the left by @p n columns. */
  92     void cursorLeft  (int n);
  93     /*! Move the cursor to the right by @p n columns. */
  94     void cursorRight (int n);
  95     /*! Position the cursor on line @p y. */
  96     void setCursorY  (int y);
  97     /*! Position the cursor at column @p x. */
  98     void setCursorX  (int x);
  99     /*! Position the cursor at line @p y, column @p x. */
 100     void setCursorYX (int y, int x);
 101     /*!
 102      * Sets the margins for scrolling the screen.
 103      *
 104      * @param topLine The top line of the new scrolling margin.
 105      * @param bottomLine The bottom line of the new scrolling margin.
 106      */
 107     void setMargins  (int topLine , int bottomLine);
 108     /*! Returns the top line of the scrolling region. */
 109     int topMargin() const;
 110     /*! Returns the bottom line of the scrolling region. */
 111     int bottomMargin() const;
 112
 113     /*!
 114      * Resets the scrolling margins back to the top and bottom lines
 115      * of the screen.
 116      */
 117     void setDefaultMargins();
 118
 119     /*!
 120      * Moves the cursor down one line, if the MODE_NewLine mode
 121      * flag is enabled then the cursor is returned to the leftmost
 122      * column first.
 123      *
 124      * Equivalent to NextLine() if the MODE_NewLine flag is set
 125      * or index() otherwise.
 126      */
 127     void NewLine     ();
 128     /*!
 129      * Moves the cursor down one line and positions it at the beginning
 130      * of the line.
 131      */
 132     void NextLine    ();
 133
 134     /*!
 135      * Move the cursor down one line.  If the cursor is on the bottom
 136      * line of the scrolling region (as returned by bottomMargin()) the
 137      * scrolling region is scrolled up by one line instead.
 138      */
 139     void index       ();
 140     /*!
 141      * Move the cursor up one line.  If the cursor is on the top line
 142      * of the scrolling region (as returned by topMargin()) the scrolling
 143      * region is scrolled down by one line instead.
 144      */
 145     void reverseIndex();
 146
 147     /*!
 148      * Scroll the scrolling region of the screen up by @p n lines.
 149      * The scrolling region is initially the whole screen, but can be changed
 150      * using setMargins()
 151      */
 152     void scrollUp(int n);
 153     /*!
 154      * Scroll the scrolling region of the screen down by @p n lines.
 155      * The scrolling region is initially the whole screen, but can be changed
 156      * using setMargins()
 157      */
 158     void scrollDown(int n);
 159
 160     /*!
 161      * Moves the cursor to the beginning of the current line.
 162      * Equivalent to setCursorX(0)
 163      */
 164     void Return      ();
 165     /*!
 166      * Moves the cursor one column to the left and erases the character
 167      * at the new cursor position.
 168      */
 169     void BackSpace   ();
 170     /*!
 171      * Moves the cursor @p n tab-stops to the right.
 172      */
 173     void Tabulate    (int n = 1);
 174     /*!
 175      * Moves the cursor @p n tab-stops to the left.
 176      */
 177     void backTabulate(int n);
 178
 179     // Editing
 180
 181     /*!
 182      * Erase @p n characters beginning from the current cursor position.
 183      * This is equivalent to over-writing @p n characters starting with the current
 184      * cursor position with spaces.
 185      * If @p n is 0 then one character is erased.
 186      */
 187     void eraseChars  (int n);
 188     /*!
 189      * Delete @p n characters beginning from the current cursor position.
 190      * If @p n is 0 then one character is deleted.
 191      */
 192     void deleteChars (int n);
 193     /*!
 194      * Insert @p n blank characters beginning from the current cursor position.
 195      * The position of the cursor is not altered.
 196      * If @p n is 0 then one character is inserted.
 197      */
 198     void insertChars (int n);
 199     /*!
 200      * Removes @p n lines beginning from the current cursor position.
 201      * The position of the cursor is not altered.
 202      * If @p n is 0 then one line is removed.
 203      */
 204     void deleteLines (int n);
 205     /*!
 206      * Inserts @p lines beginning from the current cursor position.
 207      * The position of the cursor is not altered.
 208      * If @p n is 0 then one line is inserted.
 209      */
 210     void insertLines (int n);
 211     /*! Clears all the tab stops. */
 212     void clearTabStops();
 213     /*!  Sets or removes a tab stop at the cursor's current column. */
 214     void changeTabStop(bool set);
 215
 216     /*! Resets (clears) the specified screen @p mode. */
 217     void resetMode   (int mode);
 218     /*! Sets (enables) the specified screen @p mode. */
 219     void setMode     (int mode);
 220     /*!
 221      * Saves the state of the specified screen @p mode.  It can be restored
 222      * using restoreMode()
 223      */
 224     void saveMode    (int mode);
 225     /*! Restores the state of a screen @p mode saved by calling saveMode() */
 226     void restoreMode (int mode);
 227     /*! Returns whether the specified screen @p mode is enabled or not .*/
 228     bool getMode     (int mode) const;
 229
 230     /*!
 231      * Saves the current position and appearence (text color and style) of the cursor.
 232      * It can be restored by calling restoreCursor()
 233      */
 234     void saveCursor  ();
 235     /*! Restores the position and appearence of the cursor.  See saveCursor() */
 236     void restoreCursor();
 237
 238     /*! Clear the whole screen, moving the current screen contents into the history first. */
 239     void clearEntireScreen();
 240     /*!
 241      * Clear the area of the screen from the current cursor position to the end of
 242      * the screen.
 243      */
 244     void clearToEndOfScreen();
 245     /*!
 246      * Clear the area of the screen from the current cursor position to the start
 247      * of the screen.
 248      */
 249     void clearToBeginOfScreen();
 250     /*! Clears the whole of the line on which the cursor is currently positioned. */
 251     void clearEntireLine();
 252     /*! Clears from the current cursor position to the end of the line. */
 253     void clearToEndOfLine();
 254     /*! Clears from the current cursor position to the beginning of the line. */
 255     void clearToBeginOfLine();
 256
 257     /*! Fills the entire screen with the letter 'E' */
 258     void helpAlign   ();
 259
 260     /*!
 261      * Enables the given @p rendition flag.  Rendition flags control the appearence
 262      * of characters on the screen.
 263      *
 264      * @see Character::rendition
 265      */
 266     void setRendition  (int rendition);
 267     /*!
 268      * Disables the given @p rendition flag.  Rendition flags control the appearence
 269      * of characters on the screen.
 270      *
 271      * @see Character::rendition
 272      */
 273     void resetRendition(int rendition);
 274
 275     /*!
 276      * Sets the cursor's foreground color.
 277      * @param space The color space used by the @p color argument
 278      * @param color The new foreground color.  The meaning of this depends on
 279      * the color @p space used.
 280      *
 281      * @see CharacterColor
 282      */
 283     void setForeColor  (int space, int color);
 284     /*!
 285      * Sets the cursor's background color.
 286      * @param space The color space used by the @p color argumnet.
 287      * @param color The new background color.  The meaning of this depends on
 288      * the color @p space used.
 289      *
 290      * @see CharacterColor
 291      */
 292     void setBackColor  (int space, int color);
 293     /*!
 294      * Resets the cursor's color back to the default and sets the
 295      * character's rendition flags back to the default settings.
 296      */
 297     void setDefaultRendition();
 298
 299     /*! Returns the column which the cursor is positioned at. */
 300     int  getCursorX() const;
 301     /*! Returns the line which the cursor is positioned on. */
 302     int  getCursorY() const;
 303
 304         /*! TODO Document me */
 305         void clear();
 306     /*!
 307      * Sets the position of the cursor to the 'home' position at the top-left
 308      * corner of the screen (0,0)
 309      */
 310     void home();
 311     /*!
 312      * Resets the state of the screen.  This resets the various screen modes
 313      * back to their default states.  The cursor style and colors are reset
 314      * (as if setDefaultRendition() had been called)
 315      *
 316      * <ul>
 317      * <li>Line wrapping is enabled.</li>
 318      * <li>Origin mode is disabled.</li>
 319      * <li>Insert mode is disabled.</li>
 320      * <li>Cursor mode is enabled.  TODO Document me</li>
 321      * <li>Screen mode is disabled. TODO Document me</li>
 322      * <li>New line mode is disabled.  TODO Document me</li>
 323      * </ul>
 324      *
 325      * If @p clearScreen is true then the screen contents are erased entirely,
 326      * otherwise they are unaltered.
 327      */
 328     void reset(bool clearScreen = true);
 329
 330     /*!
 331      * Displays a new character at the current cursor position.
 332      *
 333      * If the cursor is currently positioned at the right-edge of the screen and
 334      * line wrapping is enabled then the character is added at the start of a new
 335      * line below the current one.
 336      *
 337      * If the MODE_Insert screen mode is currently enabled then the character
 338      * is inserted at the current cursor position, otherwise it will replace the
 339      * character already at the current cursor position.
 340      */
 341     void ShowCharacter(unsigned short c);
 342
 343     // Do composition with last shown character FIXME: Not implemented yet for KDE 4
 344     void compose(const QString& compose);
 345
 346     /*!
 347      * Resizes the image to a new fixed size of @p new_lines by @p new_columns.
 348      * In the case that @p new_columns is smaller than the current number of columns,
 349      * existing lines are not truncated.  This prevents characters from being lost
 350      * if the terminal display is resized smaller and then larger again.
 351      *
 352      * (note that in versions of Konsole prior to KDE 4, existing lines were
 353      *  truncated when making the screen image smaller)
 354      */
 355     void resizeImage(int new_lines, int new_columns);
 356
 357     /*!
 358      * Returns the current screen image.
 359      * The result is an array of Characters of size [getLines()][getColumns()] which
 360      * must be freed by the caller after use.
 361      *
 362      * @param dest Buffer to copy the characters into
 363      * @param size Size of @p dest in Characters
 364      * @param startLine Index of first line to copy
 365      * @param endLine Index of last line to copy
 366      */
 367     void getImage( Character* dest , int size , int startLine , int endLine ) const;
 368
 369     /*!
 370      * Returns the additional attributes associated with lines in the image.
 371      * The most important attribute is LINE_WRAPPED which specifies that the
 372      * line is wrapped,
 373      * other attributes control the size of characters in the line.
 374      */
 375     QVector<LineProperty> getLineProperties( int startLine , int endLine ) const;
 376
 377
 378     /*! Return the number of lines. */
 379     int  getLines()   { return lines; }
 380     /*! Return the number of columns. */
 381     int  getColumns() { return columns; }
 382     /*! Return the number of lines in the history buffer. */
 383     int  getHistLines ();
 384     /*!
 385      * Sets the type of storage used to keep lines in the history.
 386      * If @p copyPreviousScroll is true then the contents of the previous
 387      * history buffer are copied into the new scroll.
 388      */
 389     void setScroll(const HistoryType& , bool copyPreviousScroll = true);
 390     /*! Returns the type of storage used to keep lines in the history. */
 391     const HistoryType& getScroll();
 392     /*!
 393      * Returns true if this screen keeps lines that are scrolled off the screen
 394      * in a history buffer.
 395      */
 396     bool hasScroll();
 397
 398     /*!
 399      * Sets the start of the selection.
 400      *
 401      * @param column The column index of the first character in the selection.
 402      * @param line The line index of the first character in the selection.
 403      * @param columnmode True if the selection is in column mode.
 404      */
 405     void setSelectionStart(const int column, const int line, const bool columnmode);
 406
 407     /*!
 408      * Sets the end of the current selection.
 409      *
 410      * @param column The column index of the last character in the selection.
 411      * @param line The line index of the last character in the selection.
 412      */
 413     void setSelectionEnd(const int column, const int line);
 414
 415     /*!
 416      * Retrieves the start of the selection or the cursor position if there
 417      * is no selection.
 418      */
 419     void getSelectionStart(int& column , int& line);
 420
 421     /*!
 422      * Retrieves the end of the selection or the cursor position if there
 423      * is no selection.
 424      */
 425     void getSelectionEnd(int& column , int& line);
 426
 427     /*! Clears the current selection */
 428     void clearSelection();
 429
 430     void setBusySelecting(bool busy) { sel_busy = busy; }
 431
 432     /*!
 433          *      Returns true if the character at (@p column, @p line) is part of the
 434          *  current selection.
 435          */
 436     bool isSelected(const int column,const int line) const;
 437
 438     /*!
 439      * Convenience method.  Returns the currently selected text.
 440      * @param preserveLineBreaks Specifies whether new line characters should
 441      * be inserted into the returned text at the end of each terminal line.
 442      */
 443     QString selectedText(bool preserveLineBreaks);
 444
 445         /*!
 446          * Copies part of the output to a stream.
 447          *
 448          * @param decoder A decoder which coverts terminal characters into text
 449          * @param from The first line in the history to retrieve
 450          * @param to The last line in the history to retrieve
 451          */
 452         void writeToStream(TerminalCharacterDecoder* decoder, int from, int to);
 453
 454     /*!
 455      * Sets the selection to line @p no in the history and returns
 456      * the text of that line from the history buffer.
 457      */
 458     QString getHistoryLine(int no);
 459
 460         /*!
 461          * Copies the selected characters, set using @see setSelBeginXY and @see setSelExtentXY
 462          * into a stream.
 463          *
 464          * @param decoder A decoder which converts terminal characters into text.
 465          * PlainTextDecoder is the most commonly used decoder which coverts characters
 466          * into plain text with no formatting.
 467      * @param preserveLineBreaks Specifies whether new line characters should
 468      * be inserted into the returned text at the end of each terminal line.
 469          */
 470         void writeSelectionToStream(TerminalCharacterDecoder* decoder , bool
 471                                 preserveLineBreaks = true);
 472
 473     /*! TODO Document me */
 474     void checkSelection(int from, int to);
 475
 476         /*!
 477          * Sets or clears an attribute of the current line.
 478          *
 479          * @param property The attribute to set or clear
 480          * Possible properties are:
 481          * LINE_WRAPPED:         Specifies that the line is wrapped.
 482          * LINE_DOUBLEWIDTH: Specifies that the characters in the current line should be double the normal width.
 483          * LINE_DOUBLEHEIGHT:Specifies that the characters in the current line 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.  This allows other parts of the
 486      *                   code to work on the assumption that all lines are the same height.
 487          *
 488          * @param enable true to apply the attribute to the current line or false to remove it
 489          */
 490         void setLineProperty(LineProperty property , bool enable);
 491
 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
 543         //line - the line number to copy, from 0 (the earliest line in the history) up to
 544         //               hist->getLines() + lines - 1
 545         //start - the first column on the line to copy
 546         //count - the number of characters on the line to copy
 547         //decoder - a decoder which coverts terminal characters (an Character array) into text
 548     //appendNewLine - if true a new line character (\n) is appended to the end of the line
 549         void copyLineToStream(int line,
 550                           int start,
 551                           int count,
 552                           TerminalCharacterDecoder* decoder,
 553                           bool appendNewLine,
 554                           bool preserveLineBreaks);
 555
 556     //fills a section of the screen image with the character 'c'
 557     //the parameters are specified as offsets from the start of the screen image.
 558     //the loc(x,y) macro can be used to generate these values from a column,line pair.
 559     void clearImage(int loca, int loce, char c);
 560
 561     //move screen image between 'sourceBegin' and 'sourceEnd' to 'dest'.
 562     //the parameters are specified as offsets from the start of the screen image.
 563     //the loc(x,y) macro can be used to generate these values from a column,line pair.
 564     void moveImage(int dest, int sourceBegin, int sourceEnd);
 565
 566     void scrollUp(int from, int i);
 567     void scrollDown(int from, int i);
 568
 569     void addHistLine();
 570
 571     void initTabStops();
 572
 573     void effectiveRendition();
 574     void reverseRendition(Character& p) const;
 575
 576     bool isSelectionValid() const;
 577
 578         // copies 'count' lines from the screen buffer into 'dest',
 579         // starting from 'startLine', where 0 is the first line in the screen buffer
 580         void copyFromScreen(Character* dest, int startLine, int count) const;
 581         // copies 'count' lines from the history buffer into 'dest',
 582         // starting from 'startLine', where 0 is the first line in the history
 583         void copyFromHistory(Character* dest, int startLine, int count) const;
 584
 585
 586     // screen image ----------------
 587     int lines;
 588     int columns;
 589
 590     typedef QVector<Character> ImageLine;      // [0..columns]
 591     ImageLine*          screenLines;    // [lines]
 592
 593     int _scrolledLines;
 594     QRect _lastScrolledRegion;
 595
 596     int _droppedLines;
 597
 598     QVarLengthArray<LineProperty,64> lineProperties;
 599
 600     // history buffer ---------------
 601     HistoryScroll *hist;
 602
 603     // cursor location
 604     int cuX;
 605     int cuY;
 606
 607     // cursor color and rendition info
 608     CharacterColor cu_fg;      // foreground
 609     CharacterColor cu_bg;      // background
 610     quint8 cu_re;      // rendition
 611
 612     // margins ----------------
 613     int tmargin;      // top margin
 614     int bmargin;      // bottom margin
 615
 616     // states ----------------
 617     ScreenParm currParm;
 618
 619     // ----------------------------
 620
 621     bool* tabstops;
 622
 623     // selection -------------------
 624     int sel_begin; // The first location selected.
 625     int sel_TL;    // TopLeft Location.
 626     int sel_BR;    // Bottom Right Location.
 627     bool sel_busy; // Busy making a selection.
 628     bool columnmode;  // Column selection mode
 629
 630     // effective colors and rendition ------------
 631     CharacterColor ef_fg;      // These are derived from
 632     CharacterColor ef_bg;      // the cu_* variables above
 633     quint8 ef_re;      // to speed up operation
 634
 635     //
 636     // save cursor, rendition & states ------------
 637     //
 638
 639     // cursor location
 640     int sa_cuX;
 641     int sa_cuY;
 642
 643     // rendition info
 644     quint8 sa_cu_re;
 645     CharacterColor sa_cu_fg;
 646     CharacterColor sa_cu_bg;
 647
 648     // last position where we added a character
 649     int lastPos;
 650
 651     // modes
 652     ScreenParm saveParm;
 653
 654     static Character defaultChar;
 655 };
 656
 657 }
 658
 659 #endif // SCREEN_H
 660