ScreenWindow.h 9.43 KB
Newer Older
1
/*
2
    Copyright 2007-2008 by Robert Knight <robertknight@gmail.com>
3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
    02110-1301  USA.
*/

#ifndef SCREENWINDOW_H
#define SCREENWINDOW_H

// Qt
Dirk Mueller's avatar
Dirk Mueller committed
24
#include <QtCore/QObject>
25
#include <QtCore/QPoint>
26
#include <QtCore/QRect>
27

28
// Konsole
29
#include "Character.h"
30

31 32 33
namespace Konsole
{
class Screen;
34 35

/**
36
 * Provides a window onto a section of a terminal screen.  A terminal widget can then render
Jekyll Wu's avatar
Jekyll Wu committed
37
 * the contents of the window and use the window to change the terminal screen's selection
38 39 40
 * in response to mouse or keyboard input.
 *
 * A new ScreenWindow for a terminal session can be created by calling Emulation::createWindow()
41
 *
42
 * Use the scrollTo() method to scroll the window up and down on the screen.
43
 * Use the getImage() method to retrieve the character image which is currently visible in the window.
44 45 46 47 48 49 50
 *
 * setTrackOutput() controls whether the window moves to the bottom of the associated screen when new
 * lines are added to it.
 *
 * Whenever the output from the underlying screen is changed, the notifyOutputChanged() slot should
 * be called.  This in turn will update the window's position and emit the outputChanged() signal
 * if necessary.
51
 */
52
class ScreenWindow : public QObject
53
{
Kurt Hindenburg's avatar
Kurt Hindenburg committed
54
    Q_OBJECT
55

56
public:
Jekyll Wu's avatar
Jekyll Wu committed
57
    /**
58
     * Constructs a new screen window with the given parent.
59 60
     * A screen must be specified by calling setScreen() before calling getImage() or getLineProperties().
     *
61
     * You should not call this constructor directly, instead use the Emulation::createWindow() method
62
     * to create a window on the emulation which you wish to view.  This allows the emulation
63
     * to notify the window when the associated screen has changed and synchronize selection updates
64
     * between all views on a session.
65
     */
Kurt Hindenburg's avatar
Kurt Hindenburg committed
66
    explicit ScreenWindow(Screen* screen, QObject* parent = 0);
67
    virtual ~ScreenWindow();
68 69

    /** Sets the screen which this window looks onto */
70
    void setScreen(Screen* screen);
71
    /** Returns the screen which this window looks onto */
72
    Screen* screen() const;
73

Jekyll Wu's avatar
Jekyll Wu committed
74
    /**
75 76 77
     * Returns the image of characters which are currently visible through this window
     * onto the screen.
     *
78
     * The returned buffer is managed by the ScreenWindow instance and does not need to be
Robert Knight's avatar
 
Robert Knight committed
79
     * deleted by the caller.
80 81
     */
    Character* getImage();
Robert Knight's avatar
 
Robert Knight committed
82

83 84 85 86 87 88 89
    /**
     * Returns the line attributes associated with the lines of characters which
     * are currently visible through this window
     */
    QVector<LineProperty> getLineProperties();

    /**
90
     * Returns the number of lines which the region of the window
Jekyll Wu's avatar
Jekyll Wu committed
91 92
     * specified by scrollRegion() has been scrolled by since the last call
     * to resetScrollCount().  scrollRegion() is in most cases the
93 94 95
     * whole window, but will be a smaller area in, for example, applications
     * which provide split-screen facilities.
     *
96
     * This is not guaranteed to be accurate, but allows views to optimize
97
     * rendering by reducing the amount of costly text rendering that
Jekyll Wu's avatar
Jekyll Wu committed
98
     * needs to be done when the output is scrolled.
99 100 101 102 103 104 105
     */
    int scrollCount() const;

    /**
     * Resets the count of scrolled lines returned by scrollCount()
     */
    void resetScrollCount();
106 107

    /**
Jekyll Wu's avatar
Jekyll Wu committed
108
     * Returns the area of the window which was last scrolled, this is
109 110 111
     * usually the whole window area.
     *
     * Like scrollCount(), this is not guaranteed to be accurate,
112
     * but allows views to optimize rendering.
113 114
     */
    QRect scrollRegion() const;
115

Harald Hvaal's avatar
Harald Hvaal committed
116 117 118 119 120 121 122

    /**
     * What line the next search will start from
     */
    void setCurrentResultLine(int line);
    int currentResultLine() const;

Jekyll Wu's avatar
Jekyll Wu committed
123 124
    /**
     * Sets the start of the selection to the given @p line and @p column within
125 126
     * the window.
     */
Kurt Hindenburg's avatar
Kurt Hindenburg committed
127
    void setSelectionStart(int column , int line , bool columnMode);
128 129 130 131
    /**
     * Sets the end of the selection to the given @p line and @p column within
     * the window.
     */
Kurt Hindenburg's avatar
Kurt Hindenburg committed
132
    void setSelectionEnd(int column , int line);
133 134 135 136 137 138 139 140 141 142 143 144

    /**
     * Sets the selection as the range specified by line @p start and line @p
     * end in the whole history.
     *
     * Both @p start and @p end are absolute line number in the whole history,
     * not relative line number in the window. This make it possible to select
     * range larger than the window . A good use case is selecting the whole
     * history.
     */
    void setSelectionByLineRange(int start, int end);

145 146 147
    /**
     * Retrieves the start of the selection within the window.
     */
Kurt Hindenburg's avatar
Kurt Hindenburg committed
148
    void getSelectionStart(int& column , int& line);
149 150 151
    /**
     * Retrieves the end of the selection within the window.
     */
Kurt Hindenburg's avatar
Kurt Hindenburg committed
152
    void getSelectionEnd(int& column , int& line);
153 154 155
    /**
     * Returns true if the character at @p line , @p column is part of the selection.
     */
Kurt Hindenburg's avatar
Kurt Hindenburg committed
156
    bool isSelected(int column , int line);
Jekyll Wu's avatar
Jekyll Wu committed
157
    /**
158 159 160 161
     * Clears the current selection
     */
    void clearSelection();

162 163
    /** Sets the number of lines in the window */
    void setWindowLines(int lines);
164 165 166 167
    /** Returns the number of lines in the window */
    int windowLines() const;
    /** Returns the number of columns in the window */
    int windowColumns() const;
168

169 170 171 172 173 174 175 176
    /** Returns the total number of lines in the screen */
    int lineCount() const;
    /** Returns the total number of columns in the screen */
    int columnCount() const;

    /** Returns the index of the line which is currently at the top of this window */
    int currentLine() const;

Jekyll Wu's avatar
Jekyll Wu committed
177 178
    /**
     * Returns the position of the cursor
179 180 181 182
     * within the window.
     */
    QPoint cursorPosition() const;

Jekyll Wu's avatar
Jekyll Wu committed
183
    /**
184 185 186 187 188
     * Convenience method. Returns true if the window is currently at the bottom
     * of the screen.
     */
    bool atEndOfOutput() const;

189
    /** Scrolls the window so that @p line is at the top of the window */
Kurt Hindenburg's avatar
Kurt Hindenburg committed
190
    void scrollTo(int line);
191

192
    /** Describes the units which scrollBy() moves the window by. */
Kurt Hindenburg's avatar
Kurt Hindenburg committed
193
    enum RelativeScrollMode {
194
        /** Scroll the window down by a given number of lines. */
Robert Knight's avatar
 
Robert Knight committed
195
        ScrollLines,
Jekyll Wu's avatar
Jekyll Wu committed
196
        /**
197 198 199
         * Scroll the window down by a given number of pages, where
         * one page is windowLines() lines
         */
Robert Knight's avatar
 
Robert Knight committed
200 201 202
        ScrollPages
    };

Jekyll Wu's avatar
Jekyll Wu committed
203
    /**
Robert Knight's avatar
 
Robert Knight committed
204 205 206
     * Scrolls the window relative to its current position on the screen.
     *
     * @param mode Specifies whether @p amount refers to the number of lines or the number
Jekyll Wu's avatar
Jekyll Wu committed
207
     * of pages to scroll.
Robert Knight's avatar
 
Robert Knight committed
208 209 210
     * @param amount The number of lines or pages ( depending on @p mode ) to scroll by.  If
     * this number is positive, the view is scrolled down.  If this number is negative, the view
     * is scrolled up.
211
     * @param fullPage Specifies whether to scroll by full page or half page.
Robert Knight's avatar
 
Robert Knight committed
212
     */
213
    void scrollBy(RelativeScrollMode mode, int amount, bool fullPage);
Robert Knight's avatar
 
Robert Knight committed
214

Jekyll Wu's avatar
Jekyll Wu committed
215
    /**
216 217
     * Specifies whether the window should automatically move to the bottom
     * of the screen when new output is added.
218
     *
Jekyll Wu's avatar
Jekyll Wu committed
219
     * If this is set to true, the window will be moved to the bottom of the associated screen ( see
220
     * screen() ) when the notifyOutputChanged() method is called.
221 222
     */
    void setTrackOutput(bool trackOutput);
Jekyll Wu's avatar
Jekyll Wu committed
223
    /**
224
     * Returns whether the window automatically moves to the bottom of the screen as
225
     * new output is added.  See setTrackOutput()
226 227 228 229 230 231
     */
    bool trackOutput() const;

    /**
     * Returns the text which is currently selected.
     *
232
     * @param preserveLineBreaks See Screen::selectedText()
233
     * @param trimTrailingSpaces See Screen::selectedText()
Kurt Hindenburg's avatar
Kurt Hindenburg committed
234
     * @param html Specifies if returned text should have HTML tags.
235
     */
236
    QString selectedText(bool preserveLineBreaks, bool trimTrailingSpaces = false, bool html = false) const;
237

238
public slots:
Jekyll Wu's avatar
Jekyll Wu committed
239
    /**
240 241 242 243 244 245 246
     * Notifies the window that the contents of the associated terminal screen have changed.
     * This moves the window to the bottom of the screen if trackOutput() is true and causes
     * the outputChanged() signal to be emitted.
     */
    void notifyOutputChanged();

signals:
247
    /**
Jekyll Wu's avatar
Jekyll Wu committed
248
     * Emitted when the contents of the associated terminal screen (see screen()) changes.
249
     */
250
    void outputChanged();
251

Harald Hvaal's avatar
Harald Hvaal committed
252 253
    void currentResultLineChanged();

254 255
    /**
     * Emitted when the screen window is scrolled to a different position.
Jekyll Wu's avatar
Jekyll Wu committed
256
     *
257 258 259 260
     * @param line The line which is now at the top of the window.
     */
    void scrolled(int line);

261
    /** Emitted when the selection is changed. */
262 263
    void selectionChanged();

264
private:
265 266
    int endWindowLine() const;
    void fillUnusedArea();
267

268
    Screen* _screen; // see setScreen() , screen()
269 270 271
    Character* _windowBuffer;
    int _windowBufferSize;
    bool _bufferNeedsUpdate;
272

273
    int  _windowLines;
274
    int  _currentLine; // see scrollTo() , currentLine()
Harald Hvaal's avatar
Harald Hvaal committed
275
    int _currentResultLine;
Kurt Hindenburg's avatar
Kurt Hindenburg committed
276
    bool _trackOutput; // see setTrackOutput() , trackOutput()
277
    int  _scrollCount; // count of lines which the window has been scrolled by since
Kurt Hindenburg's avatar
Kurt Hindenburg committed
278
    // the last call to resetScrollCount()
279
};
Stephan Binner's avatar
Stephan Binner committed
280
}
281
#endif // SCREENWINDOW_H