apps/konsole/src/ScreenWindow.h

   1 /*
   2     Copyright 2007-2008 by Robert Knight <robertknight@gmail.com>
   3
   4     This program is free software; you can redistribute it and/or modify
   5     it under the terms of the GNU General Public License as published by
   6     the Free Software Foundation; either version 2 of the License, or
   7     (at your option) any later version.
   8
   9     This program is distributed in the hope that it will be useful,
  10     but WITHOUT ANY WARRANTY; without even the implied warranty of
  11     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12     GNU General Public License for more details.
  13
  14     You should have received a copy of the GNU General Public License
  15     along with this program; if not, write to the Free Software
  16     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  17     02110-1301  USA.
  18 */
  19
  20 #ifndef SCREENWINDOW_H
  21 #define SCREENWINDOW_H
  22
  23 // Qt
  24 #include <QtCore/QObject>
  25 #include <QtCore/QPoint>
  26 #include <QtCore/QRect>
  27
  28 // Konsole
  29 #include "Character.h"
  30
  31 namespace Konsole
  32 {
  33
  34 class Screen;
  35
  36 /**
  37  * Provides a window onto a section of a terminal screen.  A terminal widget can then render
  38  * the contents of the window and use the window to change the terminal screen's selection
  39  * in response to mouse or keyboard input.
  40  *
  41  * A new ScreenWindow for a terminal session can be created by calling Emulation::createWindow()
  42  *
  43  * Use the scrollTo() method to scroll the window up and down on the screen.
  44  * Use the getImage() method to retrieve the character image which is currently visible in the window.
  45  *
  46  * setTrackOutput() controls whether the window moves to the bottom of the associated screen when new
  47  * lines are added to it.
  48  *
  49  * Whenever the output from the underlying screen is changed, the notifyOutputChanged() slot should
  50  * be called.  This in turn will update the window's position and emit the outputChanged() signal
  51  * if necessary.
  52  */
  53 class ScreenWindow : public QObject
  54 {
  55 Q_OBJECT
  56
  57 public:
  58     /**
  59      * Constructs a new screen window with the given parent.
  60      * A screen must be specified by calling setScreen() before calling getImage() or getLineProperties().
  61      *
  62      * You should not call this constructor directly, instead use the Emulation::createWindow() method
  63      * to create a window on the emulation which you wish to view.  This allows the emulation
  64      * to notify the window when the associated screen has changed and synchronize selection updates
  65      * between all views on a session.
  66      */
  67     ScreenWindow(QObject* parent = 0);
  68     virtual ~ScreenWindow();
  69
  70     /** Sets the screen which this window looks onto */
  71     void setScreen(Screen* screen);
  72     /** Returns the screen which this window looks onto */
  73     Screen* screen() const;
  74
  75     /**
  76      * Returns the image of characters which are currently visible through this window
  77      * onto the screen.
  78      *
  79      * The returned buffer is managed by the ScreenWindow instance and does not need to be
  80      * deleted by the caller.
  81      */
  82     Character* getImage();
  83
  84     /**
  85      * Returns the line attributes associated with the lines of characters which
  86      * are currently visible through this window
  87      */
  88     QVector<LineProperty> getLineProperties();
  89
  90     /**
  91      * Returns the number of lines which the region of the window
  92      * specified by scrollRegion() has been scrolled by since the last call
  93      * to resetScrollCount().  scrollRegion() is in most cases the
  94      * whole window, but will be a smaller area in, for example, applications
  95      * which provide split-screen facilities.
  96      *
  97      * This is not guaranteed to be accurate, but allows views to optimise
  98      * rendering by reducing the amount of costly text rendering that
  99      * needs to be done when the output is scrolled.
 100      */
 101     int scrollCount() const;
 102
 103     /**
 104      * Resets the count of scrolled lines returned by scrollCount()
 105      */
 106     void resetScrollCount();
 107
 108     /**
 109      * Returns the area of the window which was last scrolled, this is
 110      * usually the whole window area.
 111      *
 112      * Like scrollCount(), this is not guaranteed to be accurate,
 113      * but allows views to optimise rendering.
 114      */
 115     QRect scrollRegion() const;
 116
 117     /**
 118      * Sets the start of the selection to the given @p line and @p column within
 119      * the window.
 120      */
 121     void setSelectionStart( int column , int line , bool columnMode );
 122     /**
 123      * Sets the end of the selection to the given @p line and @p column within
 124      * the window.
 125      */
 126     void setSelectionEnd( int column , int line );
 127     /**
 128      * Retrieves the start of the selection within the window.
 129      */
 130     void getSelectionStart( int& column , int& line );
 131     /**
 132      * Retrieves the end of the selection within the window.
 133      */
 134     void getSelectionEnd( int& column , int& line );
 135     /**
 136      * Returns true if the character at @p line , @p column is part of the selection.
 137      */
 138     bool isSelected( int column , int line );
 139     /**
 140      * Clears the current selection
 141      */
 142     void clearSelection();
 143
 144     /** Sets the number of lines in the window */
 145     void setWindowLines(int lines);
 146     /** Returns the number of lines in the window */
 147     int windowLines() const;
 148     /** Returns the number of columns in the window */
 149     int windowColumns() const;
 150
 151     /** Returns the total number of lines in the screen */
 152     int lineCount() const;
 153     /** Returns the total number of columns in the screen */
 154     int columnCount() const;
 155
 156     /** Returns the index of the line which is currently at the top of this window */
 157     int currentLine() const;
 158
 159     /**
 160      * Returns the position of the cursor
 161      * within the window.
 162      */
 163     QPoint cursorPosition() const;
 164
 165     /**
 166      * Convenience method. Returns true if the window is currently at the bottom
 167      * of the screen.
 168      */
 169     bool atEndOfOutput() const;
 170
 171     /** Scrolls the window so that @p line is at the top of the window */
 172     void scrollTo( int line );
 173
 174     /** Describes the units which scrollBy() moves the window by. */
 175     enum RelativeScrollMode
 176     {
 177         /** Scroll the window down by a given number of lines. */
 178         ScrollLines,
 179         /**
 180          * Scroll the window down by a given number of pages, where
 181          * one page is windowLines() lines
 182          */
 183         ScrollPages
 184     };
 185
 186     /**
 187      * Scrolls the window relative to its current position on the screen.
 188      *
 189      * @param mode Specifies whether @p amount refers to the number of lines or the number
 190      * of pages to scroll.
 191      * @param amount The number of lines or pages ( depending on @p mode ) to scroll by.  If
 192      * this number is positive, the view is scrolled down.  If this number is negative, the view
 193      * is scrolled up.
 194      */
 195     void scrollBy( RelativeScrollMode mode , int amount );
 196
 197     /**
 198      * Specifies whether the window should automatically move to the bottom
 199      * of the screen when new output is added.
 200      *
 201      * If this is set to true, the window will be moved to the bottom of the associated screen ( see
 202      * screen() ) when the notifyOutputChanged() method is called.
 203      */
 204     void setTrackOutput(bool trackOutput);
 205     /**
 206      * Returns whether the window automatically moves to the bottom of the screen as
 207      * new output is added.  See setTrackOutput()
 208      */
 209     bool trackOutput() const;
 210
 211     /**
 212      * Returns the text which is currently selected.
 213      *
 214      * @param preserveLineBreaks See Screen::selectedText()
 215      */
 216     QString selectedText( bool preserveLineBreaks ) const;
 217
 218 public slots:
 219     /**
 220      * Notifies the window that the contents of the associated terminal screen have changed.
 221      * This moves the window to the bottom of the screen if trackOutput() is true and causes
 222      * the outputChanged() signal to be emitted.
 223      */
 224     void notifyOutputChanged();
 225
 226 signals:
 227     /**
 228      * Emitted when the contents of the associated terminal screen (see screen()) changes.
 229      */
 230     void outputChanged();
 231
 232     /**
 233      * Emitted when the screen window is scrolled to a different position.
 234      *
 235      * @param line The line which is now at the top of the window.
 236      */
 237     void scrolled(int line);
 238
 239     /** Emitted when the selection is changed. */
 240     void selectionChanged();
 241
 242 private:
 243     int endWindowLine() const;
 244     void fillUnusedArea();
 245
 246     Screen* _screen; // see setScreen() , screen()
 247     Character* _windowBuffer;
 248     int _windowBufferSize;
 249     bool _bufferNeedsUpdate;
 250
 251     int  _windowLines;
 252     int  _currentLine; // see scrollTo() , currentLine()
 253     bool _trackOutput; // see setTrackOutput() , trackOutput()
 254     int  _scrollCount; // count of lines which the window has been scrolled by since
 255                        // the last call to resetScrollCount()
 256 };
 257
 258 }
 259 #endif // SCREENWINDOW_H