KTextEditor

katetextrange.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 KATE_TEXTRANGE_H
11#define KATE_TEXTRANGE_H
12
13#include <ktexteditor/movingrange.h>
14
15#include "katetextcursor.h"
16
17namespace KTextEditor
18{
19class MovingRangeFeedback;
20class View;
21}
22
23namespace Kate
24{
25class TextBuffer;
26
27/**
28 * Class representing a 'clever' text range.
29 * It will automagically move if the text inside the buffer it belongs to is modified.
30 * By intention no subclass of KTextEditor::Range, must be converted manually.
31 * A TextRange is allowed to be empty. If you call setInvalidateIfEmpty(true),
32 * a TextRange will become automatically invalid as soon as start() == end()
33 * position holds.
34 */
36{
37 // this is a friend, block changes might invalidate ranges...
38 friend class TextBlock;
39 friend class TextBuffer;
40
41public:
42 /**
43 * Construct a text range.
44 * A TextRange is not allowed to be empty, as soon as start == end position, it will become
45 * automatically invalid!
46 * @param buffer parent text buffer
47 * @param range The initial text range assumed by the new range.
48 * @param insertBehavior Define whether the range should expand when text is inserted adjacent to the range.
49 * @param emptyBehavior Define whether the range should invalidate itself on becoming empty.
50 */
52
53 /**
54 * No copy constructor, don't allow this to be copied.
55 */
56 TextRange(const TextRange &) = delete;
57
58 /**
59 * Destruct the text block
60 */
61 ~TextRange() override;
62
63 /**
64 * No assignment operator, no copying around.
65 */
66 TextRange &operator=(const TextRange &) = delete;
67
68 /**
69 * Set insert behaviors.
70 * @param insertBehaviors new insert behaviors
71 */
73
74 /**
75 * Get current insert behaviors.
76 * @return current insert behaviors
77 */
78 InsertBehaviors insertBehaviors() const override;
79
80 /**
81 * Set if this range will invalidate itself if it becomes empty.
82 * @param emptyBehavior behavior on becoming empty
83 */
85
86 /**
87 * Will this range invalidate itself if it becomes empty?
88 * @return behavior on becoming empty
89 */
91 {
92 return m_invalidateIfEmpty ? InvalidateIfEmpty : AllowEmpty;
93 }
94
95 /**
96 * Gets the document to which this range is bound.
97 * \return a pointer to the document
98 */
99 KTextEditor::Document *document() const override;
100
101 /**
102 * Set the range of this range.
103 * A TextRange is not allowed to be empty, as soon as start == end position, it will become
104 * automatically invalid!
105 * @param range new range for this clever range
106 */
107 void setRange(KTextEditor::Range range) override;
108
109 /**
110 * \overload
111 * Set the range of this range
112 * A TextRange is not allowed to be empty, as soon as start == end position, it will become
113 * automatically invalid!
114 * @param start new start for this clever range
115 * @param end new end for this clever range
116 */
121
122 /**
123 * Set the range of this range and the connected attribute.
124 * Avoids internal overhead of separate setting that.
125 *
126 * A TextRange is not allowed to be empty, as soon as start == end position, it will become
127 * automatically invalid!
128 *
129 * @param range new range for this clever range
130 * @param attribute Attribute to assign to this range. If null, simply removes the previous Attribute.
131 *
132 * @since 6.0
133 */
135
136 /**
137 * Set the range of this range and the connected attribute and Z-depth.
138 * Avoids internal overhead of separate setting that.
139 *
140 * A TextRange is not allowed to be empty, as soon as start == end position, it will become
141 * automatically invalid!
142 *
143 * @param range new range for this clever range
144 * @param attribute Attribute to assign to this range. If null, simply removes the previous Attribute.
145 * @param zDepth new Z-depth of this range
146 *
147 * @since 6.0
148 */
150
151 /**
152 * Retrieve start cursor of this range, read-only.
153 * @return start cursor
154 */
155 const KTextEditor::MovingCursor &start() const override
156 {
157 return m_start;
158 }
159
160 /**
161 * Non-virtual version of start(), which is faster.
162 * @return start cursor
163 */
165 {
166 return m_start;
167 }
168
169 /**
170 * Retrieve end cursor of this range, read-only.
171 * @return end cursor
172 */
173 const KTextEditor::MovingCursor &end() const override
174 {
175 return m_end;
176 }
177
178 /**
179 * Nonvirtual version of end(), which is faster.
180 * @return end cursor
181 */
182 const TextCursor &endInternal() const
183 {
184 return m_end;
185 }
186
187 /**
188 * Hides parent's impl of toLineRange() and uses non-virtual functions internally.
189 */
194
195 /**
196 * Convert this clever range into a dumb one.
197 * @return normal range
198 */
200 {
201 auto startCursor = KTextEditor::Cursor(startInternal().lineInternal(), startInternal().columnInternal());
202 auto endCursor = KTextEditor::Cursor(endInternal().lineInternal(), endInternal().columnInternal());
203 return KTextEditor::Range(startCursor, endCursor);
204 }
205
206 /**
207 * Convert this clever range into a dumb one. Equal to toRange, allowing to use implicit conversion.
208 * @return normal range
209 */
210 operator KTextEditor::Range() const
211 {
212 return toRange();
213 }
214
215 /**
216 * Gets the active view for this range. Might be already invalid, internally only used for pointer comparisons.
217 *
218 * \return a pointer to the active view
219 */
220 KTextEditor::View *view() const override
221 {
222 return m_view;
223 }
224
225 /**
226 * Sets the currently active view for this range.
227 * This will trigger update of the relevant view parts, if the view changed.
228 * Set view before the attribute, that will avoid not needed redraws.
229 *
230 * \param view View to assign to this range. If null, simply
231 * removes the previous view.
232 */
233 void setView(KTextEditor::View *view) override;
234
235 /**
236 * Gets the active Attribute for this range.
237 *
238 * \return a pointer to the active attribute
239 */
241 {
242 return m_attribute;
243 }
244
245 /**
246 * \return whether a nonzero attribute is set. This is faster than checking attribute(),
247 * because the reference-counting is omitted.
248 */
249 bool hasAttribute() const
250 {
251 return m_attribute.constData();
252 }
253
254 /**
255 * Sets the currently active attribute for this range.
256 * This will trigger update of the relevant view parts.
257 *
258 * \param attribute Attribute to assign to this range. If null, simply
259 * removes the previous Attribute.
260 */
262
263 /**
264 * Gets the active MovingRangeFeedback for this range.
265 *
266 * \return a pointer to the active MovingRangeFeedback
267 */
269 {
270 return m_feedback;
271 }
272
273 /**
274 * Sets the currently active MovingRangeFeedback for this range.
275 * This will trigger evaluation if feedback must be send again (for example if mouse is already inside range).
276 *
277 * \param feedback MovingRangeFeedback to assign to this range. If null, simply
278 * removes the previous MovingRangeFeedback.
279 */
281
282 /**
283 * Is this range's attribute only visible in views, not for example prints?
284 * Default is false.
285 * @return range visible only for views
286 */
287 bool attributeOnlyForViews() const override
288 {
289 return m_attributeOnlyForViews;
290 }
291
292 /**
293 * Set if this range's attribute is only visible in views, not for example prints.
294 * @param onlyForViews attribute only valid for views
295 */
296 void setAttributeOnlyForViews(bool onlyForViews) override;
297
298 /**
299 * Gets the current Z-depth of this range.
300 * Ranges with smaller Z-depth than others will win during rendering.
301 * Default is 0.0.
302 *
303 * \return current Z-depth of this range
304 */
305 qreal zDepth() const override
306 {
307 return m_zDepth;
308 }
309
310 /**
311 * Set the current Z-depth of this range.
312 * Ranges with smaller Z-depth than others will win during rendering.
313 * This will trigger update of the relevant view parts, if the depth changed.
314 * Set depth before the attribute, that will avoid not needed redraws.
315 * Default is 0.0.
316 *
317 * \param zDepth new Z-depth of this range
318 */
319 void setZDepth(qreal zDepth) override;
320
321 bool spansMultipleBlocks() const
322 {
323 return m_start.m_block && m_end.m_block && m_start.m_block != m_end.m_block;
324 }
325
326private:
327 /**
328 * Check if range is valid, used by constructor and setRange.
329 * If at least one cursor is invalid, both will set to invalid.
330 * Same if range itself is invalid (start >= end).
331 *
332 * IMPORTANT: Notifications might need to deletion of this range!
333 *
334 * @param oldLineRange line range of this range before changing of cursors, needed to add/remove range from m_ranges in blocks, required!
335 * @param notifyAboutChange should feedback be emitted or not?
336 */
337 void checkValidity(bool notifyAboutChange = true);
338
339 /**
340 * Mark this range for later validity checking.
341 */
342 void setValidityCheckRequired()
343 {
344 m_isCheckValidityRequired = true;
345 }
346
347 /**
348 * Does this range need validity checking?
349 * @return is checking required?
350 */
351 bool isValidityCheckRequired() const
352 {
353 return m_isCheckValidityRequired;
354 }
355
356private:
357 /**
358 * parent text buffer
359 * is a reference, and no pointer, as this must always exist and can't change
360 */
361 TextBuffer *m_buffer;
362
363 /**
364 * Start cursor for this range, is a clever cursor
365 */
366 TextCursor m_start;
367
368 /**
369 * End cursor for this range, is a clever cursor
370 */
371 TextCursor m_end;
372
373 /**
374 * The view for which the attribute is valid, 0 means any view
375 */
376 KTextEditor::View *m_view;
377
378 /**
379 * This range's current attribute.
380 */
381 KTextEditor::Attribute::Ptr m_attribute;
382
383 /**
384 * pointer to the active MovingRangeFeedback
385 */
387
388 /**
389 * Z-depth of this range for rendering
390 */
391 qreal m_zDepth;
392
393 /**
394 * Is this range's attribute only visible in views, not for example prints?
395 */
396 bool m_attributeOnlyForViews;
397
398 /**
399 * Will this range invalidate itself if it becomes empty?
400 */
401 bool m_invalidateIfEmpty;
402
403 /**
404 * Should this range be validated?
405 * Used by KateTextBlock to avoid multiple updates without costly hashing.
406 * Reset by checkValidity().
407 */
408 bool m_isCheckValidityRequired = false;
409};
410
411}
412
413#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
An object representing lines from a start line to an end line.
Definition linerange.h:41
A Cursor which is bound to a specific Document, and maintains its position.
A class which provides notifications of state changes to a MovingRange.
A range that is bound to a specific Document, and maintains its position.
EmptyBehavior
Behavior of range if it becomes empty.
@ InvalidateIfEmpty
invalidate range, if it becomes empty
@ AllowEmpty
allow range to be empty
virtual void setRange(KTextEditor::Range range)=0
Set the range of this range.
An object representing a section of text, from one Cursor to another.
A text widget with KXMLGUIClient that represents a Document.
Definition view.h:244
Class representing a text block.
Class representing a text buffer.
Class representing a 'clever' text cursor.
int lineInternal() const
Non-virtual version of line(), which is faster.
Class representing a 'clever' text range.
qreal zDepth() const override
Gets the current Z-depth of this range.
void setAttribute(KTextEditor::Attribute::Ptr attribute) override
Sets the currently active attribute for this range.
~TextRange() override
Destruct the text block.
KTextEditor::MovingRangeFeedback * feedback() const override
Gets the active MovingRangeFeedback for this range.
const TextCursor & startInternal() const
Non-virtual version of start(), which is faster.
KTextEditor::Document * document() const override
Gets the document to which this range is bound.
const KTextEditor::MovingCursor & end() const override
Retrieve end cursor of this range, read-only.
const KTextEditor::Attribute::Ptr & attribute() const override
Gets the active Attribute for this range.
void setRange(KTextEditor::Cursor start, KTextEditor::Cursor end)
This is an overloaded member function, provided for convenience. It differs from the above function o...
void setZDepth(qreal zDepth) override
Set the current Z-depth of this range.
TextRange & operator=(const TextRange &)=delete
No assignment operator, no copying around.
TextRange(const TextRange &)=delete
No copy constructor, don't allow this to be copied.
InsertBehaviors insertBehaviors() const override
Get current insert behaviors.
const KTextEditor::MovingCursor & start() const override
Retrieve start cursor of this range, read-only.
void setAttributeOnlyForViews(bool onlyForViews) override
Set if this range's attribute is only visible in views, not for example prints.
KTextEditor::View * view() const override
Gets the active view for this range.
void setFeedback(KTextEditor::MovingRangeFeedback *feedback) override
Sets the currently active MovingRangeFeedback for this range.
const KTextEditor::Range toRange() const
Convert this clever range into a dumb one.
void setView(KTextEditor::View *view) override
Sets the currently active view for this range.
void setInsertBehaviors(InsertBehaviors insertBehaviors) override
Set insert behaviors.
bool hasAttribute() const
const TextCursor & endInternal() const
Nonvirtual version of end(), which is faster.
bool attributeOnlyForViews() const override
Is this range's attribute only visible in views, not for example prints? Default is false.
EmptyBehavior emptyBehavior() const override
Will this range invalidate itself if it becomes empty?
KTextEditor::LineRange toLineRange() const
Hides parent's impl of toLineRange() and uses non-virtual functions internally.
void setEmptyBehavior(EmptyBehavior emptyBehavior) override
Set if this range will invalidate itself if it becomes empty.
void setRange(KTextEditor::Range range) override
Set the range of this range.
TextRange(TextBuffer *buffer, KTextEditor::Range range, InsertBehaviors insertBehavior, EmptyBehavior emptyBehavior=AllowEmpty)
Construct a text range.
Q_SCRIPTABLE Q_NOREPLY void start()
The KTextEditor namespace contains all the public API that is required to use the KTextEditor compone...
const T * constData() const const
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sat Dec 21 2024 17:01:55 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.