MauiKit Terminal

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

KDE's Doxygen guidelines are available online.