KTextEditor

movingcursor.h
1/*
2 SPDX-FileCopyrightText: 2010 Christoph Cullmann <cullmann@kde.org>
3
4 Based on code of the SmartCursor/Range by:
5 SPDX-FileCopyrightText: 2003-2005 Hamish Rodda <rodda@kde.org>
6
7 SPDX-License-Identifier: LGPL-2.0-or-later
8*/
9
10#ifndef KTEXTEDITOR_MOVINGCURSOR_H
11#define KTEXTEDITOR_MOVINGCURSOR_H
12
13#include <ktexteditor/cursor.h>
14#include <ktexteditor_export.h>
15
16class QDebug;
17
18namespace KTextEditor
19{
20class MovingRange;
21class Document;
22
23/**
24 * \class MovingCursor movingcursor.h <KTextEditor/MovingCursor>
25 *
26 * \short A Cursor which is bound to a specific Document, and maintains its position.
27 *
28 * \ingroup kte_group_moving_classes
29 *
30 * A MovingCursor is an extension of the basic Cursor class. It maintains its
31 * position in the document. As a result of this, MovingCursor%s may not be copied, as they need
32 * to maintain a connection to the associated Document.
33 *
34 * Create a new MovingCursor like this:
35 * \code
36 * // Retrieve the MovingInterface
37 * KTextEditor::MovingInterface* moving =
38 * qobject_cast<KTextEditor::MovingInterface*>( yourDocument );
39 *
40 * if ( moving ) {
41 * KTextEditor::MovingCursor* cursor = moving->newMovingCursor();
42 * }
43 * \endcode
44 *
45 * When finished with a MovingCursor, simply delete it.
46 * If the document the cursor belong to is deleted, it will get deleted automatically.
47 *
48 * \sa Cursor, Range, MovingRange and MovingInterface.
49 *
50 * \author Christoph Cullmann <cullmann@kde.org>
51 *
52 * \since 4.5
53 */
54class KTEXTEDITOR_EXPORT MovingCursor
55{
56 //
57 // sub types
58 //
59public:
60 /**
61 * Insert behavior of this cursor, should it stay if text is insert at its position
62 * or should it move.
63 */
65 StayOnInsert = 0x0, ///< stay on insert
66 MoveOnInsert = 0x1 ///< move on insert
67 };
68
69 /**
70 * Wrap behavior for end of line treatement used in move().
71 */
73 Wrap = 0x0, ///< wrap at end of line
74 NoWrap = 0x1 ///< do not wrap at end of line
75 };
76
77 //
78 // stuff that needs to be implemented by editor part cursors
79 //
80public:
81 /**
82 * Set insert behavior.
83 * @param insertBehavior new insert behavior
84 */
85 virtual void setInsertBehavior(InsertBehavior insertBehavior) = 0;
86
87 /**
88 * Get current insert behavior.
89 * @return current insert behavior
90 */
91 virtual InsertBehavior insertBehavior() const = 0;
92
93 /**
94 * Gets the document to which this cursor is bound.
95 * \return a pointer to the document
96 */
97 virtual Document *document() const = 0;
98
99 /**
100 * Get range this cursor belongs to, if any
101 * @return range this pointer is part of, else 0
102 */
103 virtual MovingRange *range() const = 0;
104
105 /**
106 * Set the current cursor position to \e position.
107 *
108 * \param position new cursor position
109 */
110 virtual void setPosition(KTextEditor::Cursor position) = 0;
111
112 /**
113 * Retrieve the line on which this cursor is situated.
114 * \return line number, where 0 is the first line.
115 */
116 virtual int line() const = 0;
117
118 /**
119 * Retrieve the column on which this cursor is situated.
120 * \return column number, where 0 is the first column.
121 */
122 virtual int column() const = 0;
123
124 /**
125 * Destruct the moving cursor.
126 */
127 virtual ~MovingCursor();
128
129 //
130 // forbidden stuff
131 //
132protected:
133 /**
134 * For inherited class only.
135 */
136 MovingCursor();
137
138public:
139 /**
140 * no copy constructor, don't allow this to be copied.
141 */
142 MovingCursor(const MovingCursor &) = delete;
143
144 /**
145 * no assignment operator, no copying around clever cursors.
146 */
148
149 //
150 // convenience API
151 //
152public:
153 /**
154 * Returns whether the current position of this cursor is a valid position,
155 * i.e. whether line() >= 0 and column() >= 0.
156 *
157 * \return \e true , if the cursor position is valid, otherwise \e false
158 */
159 inline bool isValid() const
160 {
161 return line() >= 0 && column() >= 0;
162 }
163
164 /**
165 * Check whether this MovingCursor is located at a valid text position.
166 * A cursor position at (line, column) is valid, if
167 * - line >= 0 and line < document()->lines() holds, and
168 * - column >= 0 and column <= lineLength(column).
169 *
170 * Further, the text position is also invalid if it is inside a Unicode
171 * surrogate (utf-32 character).
172 *
173 * \return \e true, if the cursor is a valid text position, otherwise \e false
174 *
175 * \see Document::isValidTextPosition()
176 */
177 bool isValidTextPosition() const;
178
179 /**
180 * \overload
181 *
182 * Set the cursor position to \e line and \e column.
183 *
184 * \param line new cursor line
185 * \param column new cursor column
186 */
187 void setPosition(int line, int column);
188
189 /**
190 * Set the cursor line to \e line.
191 * \param line new cursor line
192 */
193 void setLine(int line);
194
195 /**
196 * Set the cursor column to \e column.
197 * \param column new cursor column
198 */
199 void setColumn(int column);
200
201 /**
202 * Determine if this cursor is located at column 0 of a valid text line.
203 *
204 * \return \e true if cursor is a valid text position and column()=0, otherwise \e false.
205 */
206 bool atStartOfLine() const;
207
208 /**
209 * Determine if this cursor is located at the end of the current line.
210 *
211 * \return \e true if the cursor is situated at the end of the line, otherwise \e false.
212 */
213 bool atEndOfLine() const;
214
215 /**
216 * Determine if this cursor is located at line 0 and column 0.
217 *
218 * \return \e true if the cursor is at start of the document, otherwise \e false.
219 */
220 bool atStartOfDocument() const;
221
222 /**
223 * Determine if this cursor is located at the end of the last line in the
224 * document.
225 *
226 * \return \e true if the cursor is at the end of the document, otherwise \e false.
227 */
228 bool atEndOfDocument() const;
229
230 /**
231 * Moves the cursor to the next line and sets the column to 0. If the cursor
232 * position is already in the last line of the document, the cursor position
233 * remains unchanged and the return value is \e false.
234 *
235 * \return \e true on success, otherwise \e false
236 */
237 bool gotoNextLine();
238
239 /**
240 * Moves the cursor to the previous line and sets the column to 0. If the
241 * cursor position is already in line 0, the cursor position remains
242 * unchanged and the return value is \e false.
243 *
244 * \return \e true on success, otherwise \e false
245 */
246 bool gotoPreviousLine();
247
248 /**
249 * Moves the cursor \p chars character forward or backwards. If \e wrapBehavior
250 * equals WrapBehavior::Wrap, the cursor is automatically wrapped to the
251 * next line at the end of a line.
252 *
253 * When moving backwards, the WrapBehavior does not have any effect.
254 * \note If the cursor could not be moved the amount of chars requested,
255 * the cursor is not moved at all!
256 *
257 * \return \e true on success, otherwise \e false
258 */
259 bool move(int chars, WrapBehavior wrapBehavior = Wrap);
260
261 /**
262 * Convert this clever cursor into a dumb one.
263 * Even if this cursor belongs to a range, the created one not.
264 * @return normal cursor
265 */
266 const Cursor toCursor() const
267 {
268 return Cursor(line(), column());
269 }
270
271 /**
272 * Convert this clever cursor into a dumb one. Equal to toCursor, allowing to use implicit conversion.
273 * Even if this cursor belongs to a range, the created one not.
274 * @return normal cursor
275 */
276 operator Cursor() const
277 {
278 return Cursor(line(), column());
279 }
280
281 //
282 // operators for: MovingCursor <-> MovingCursor
283 //
284 /**
285 * Equality operator.
286 *
287 * \note comparison between two invalid cursors is undefined.
288 * comparison between an invalid and a valid cursor will always be \e false.
289 *
290 * \param c1 first cursor to compare
291 * \param c2 second cursor to compare
292 * \return \e true, if c1's and c2's line and column are \e equal.
293 */
294 inline friend bool operator==(const MovingCursor &c1, const MovingCursor &c2)
295 {
296 return c1.line() == c2.line() && c1.column() == c2.column();
297 }
298
299 /**
300 * Inequality operator.
301 * \param c1 first cursor to compare
302 * \param c2 second cursor to compare
303 * \return \e true, if c1's and c2's line and column are \e not equal.
304 */
305 inline friend bool operator!=(const MovingCursor &c1, const MovingCursor &c2)
306 {
307 return !(c1 == c2);
308 }
309
310 /**
311 * Greater than operator.
312 * \param c1 first cursor to compare
313 * \param c2 second cursor to compare
314 * \return \e true, if c1's position is greater than c2's position,
315 * otherwise \e false.
316 */
317 inline friend bool operator>(const MovingCursor &c1, const MovingCursor &c2)
318 {
319 return c1.line() > c2.line() || (c1.line() == c2.line() && c1.column() > c2.column());
320 }
321
322 /**
323 * Greater than or equal to operator.
324 * \param c1 first cursor to compare
325 * \param c2 second cursor to compare
326 * \return \e true, if c1's position is greater than or equal to c2's
327 * position, otherwise \e false.
328 */
329 inline friend bool operator>=(const MovingCursor &c1, const MovingCursor &c2)
330 {
331 return c1.line() > c2.line() || (c1.line() == c2.line() && c1.column() >= c2.column());
332 }
333
334 /**
335 * Less than operator.
336 * \param c1 first cursor to compare
337 * \param c2 second cursor to compare
338 * \return \e true, if c1's position is greater than or equal to c2's
339 * position, otherwise \e false.
340 */
341 inline friend bool operator<(const MovingCursor &c1, const MovingCursor &c2)
342 {
343 return !(c1 >= c2);
344 }
345
346 /**
347 * Less than or equal to operator.
348 * \param c1 first cursor to compare
349 * \param c2 second cursor to compare
350 * \return \e true, if c1's position is lesser than or equal to c2's
351 * position, otherwise \e false.
352 */
353 inline friend bool operator<=(const MovingCursor &c1, const MovingCursor &c2)
354 {
355 return !(c1 > c2);
356 }
357};
358
359/**
360 * qDebug() stream operator. Writes this cursor to the debug output in a nicely formatted way.
361 * @param s debug stream
362 * @param cursor cursor to print
363 * @return debug stream
364 */
365KTEXTEDITOR_EXPORT QDebug operator<<(QDebug s, const MovingCursor *cursor);
366
367/**
368 * qDebug() stream operator. Writes this cursor to the debug output in a nicely formatted way.
369 * @param s debug stream
370 * @param cursor cursor to print
371 * @return debug stream
372 */
373KTEXTEDITOR_EXPORT QDebug operator<<(QDebug s, const MovingCursor &cursor);
374}
375
376#endif
The Cursor represents a position in a Document.
Definition cursor.h:75
A KParts derived class representing a text document.
Definition document.h:284
A Cursor which is bound to a specific Document, and maintains its position.
const Cursor toCursor() const
Convert this clever cursor into a dumb one.
friend bool operator>(const MovingCursor &c1, const MovingCursor &c2)
Greater than operator.
bool isValid() const
Returns whether the current position of this cursor is a valid position, i.e.
friend bool operator!=(const MovingCursor &c1, const MovingCursor &c2)
Inequality operator.
WrapBehavior
Wrap behavior for end of line treatement used in move().
virtual Document * document() const =0
Gets the document to which this cursor is bound.
virtual void setInsertBehavior(InsertBehavior insertBehavior)=0
Set insert behavior.
friend bool operator<(const MovingCursor &c1, const MovingCursor &c2)
Less than operator.
MovingCursor & operator=(const MovingCursor &)=delete
no assignment operator, no copying around clever cursors.
friend bool operator==(const MovingCursor &c1, const MovingCursor &c2)
Equality operator.
virtual MovingRange * range() const =0
Get range this cursor belongs to, if any.
virtual int column() const =0
Retrieve the column on which this cursor is situated.
InsertBehavior
Insert behavior of this cursor, should it stay if text is insert at its position or should it move.
friend bool operator>=(const MovingCursor &c1, const MovingCursor &c2)
Greater than or equal to operator.
virtual int line() const =0
Retrieve the line on which this cursor is situated.
friend bool operator<=(const MovingCursor &c1, const MovingCursor &c2)
Less than or equal to operator.
virtual InsertBehavior insertBehavior() const =0
Get current insert behavior.
virtual void setPosition(KTextEditor::Cursor position)=0
Set the current cursor position to position.
MovingCursor(const MovingCursor &)=delete
no copy constructor, don't allow this to be copied.
A range that is bound to a specific Document, and maintains its position.
The KTextEditor namespace contains all the public API that is required to use the KTextEditor compone...
KTEXTEDITOR_EXPORT QDebug operator<<(QDebug s, const MovingCursor *cursor)
qDebug() stream operator.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sun Feb 25 2024 18:42:02 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.