KTextEditor

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

KDE's Doxygen guidelines are available online.