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 <QObject>
25#include <QPoint>
26#include <QRect>
27
28// Konsole
29#include "Character.h"
30
31namespace Konsole
32{
33
34class 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 */
53class ScreenWindow : public QObject
54{
55Q_OBJECT
56
57public:
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 optimize
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 optimize 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
218public 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
226signals:
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
242private:
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
260