KTextEditor

foldinginterface.h
1/*
2 SPDX-FileCopyrightText: 2013 Christoph Cullmann <cullmann@kde.org>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5*/
6
7#ifndef KTEXTEDITOR_FOLDINGINTERFACE_H
8#define KTEXTEDITOR_FOLDINGINTERFACE_H
9
10// #include <ktexteditor_export.h>
11
12#include <QFlags>
13
14namespace KTextEditor
15{
16class Range;
17
18/**
19 * KTextEditor interface for code folding of a KTextEditor::View.
20 * The interface allows to arbitrary fold given regions of a buffer as long
21 * as they are well nested.
22 * Multiple instances of this class can exist for the same buffer.
23 */
24class KTEXTEDITOR_EXPORT FoldingInterface
25{
26public:
27 /**
28 * Create folding object for given buffer.
29 * @param buffer text buffer we want to provide folding info for
30 */
32
33 /**
34 * Cleanup
35 */
37
38 /**
39 * Folding state of a range
40 */
42 /**
43 * Range is persistent, e.g. it should not auto-delete after unfolding!
44 */
45 Persistent = 0x1,
46
47 /**
48 * Range is folded away
49 */
50 Folded = 0x2
51 };
52 Q_DECLARE_FLAGS(FoldingRangeFlags, FoldingRangeFlag)
53
54 /**
55 * \name Creation, Folding and Unfolding
56 *
57 * The following functions provide access and manipulation of the range's position.
58 * \{
59 */
60
61 /**
62 * Create a new folding range.
63 * @param range folding range
64 * @param flags initial flags for the new folding range
65 * @return on success, id of new range >= 0, else -1, we return no pointer as folding ranges might be auto-deleted internally!
66 * the ids are stable for one KTextEditor::FoldingInterface, e.g. you can rely in unit tests that you get 0,1,.... for successfully created ranges!
67 */
68 qint64 newFoldingRange(KTextEditor::Range range, FoldingRangeFlags flags = FoldingRangeFlags());
69
70 /**
71 * Fold the given range.
72 * @param id id of the range to fold
73 * @return success
74 */
75 virtual bool foldRange(qint64 id) = 0;
76
77 /**
78 * Unfold the given range.
79 * In addition it can be forced to remove the region, even if it is persistent.
80 * @param id id of the range to unfold
81 * @param remove should the range be removed from the folding after unfolding? ranges that are not persistent auto-remove themself on unfolding
82 * @return success
83 */
84 virtual bool unfoldRange(qint64 id, bool remove = false) = 0;
85
86 /**
87 * Queries which folding ranges start at the given line and returns the id + flags for all
88 * of them. Very fast if nothing is folded, else binary search.
89 * @param line line to query starting folding ranges
90 * @return vector of id's + flags
91 */
92 virtual QList<QPair<qint64, FoldingRangeFlags>> foldingRangesStartingOnLine(int line) const = 0;
93
94 /**
95 * Check whether on this line starts a folding range
96 * @param line line to query starting folding ranges
97 * @return true, if a folding range starts, otherwise false
98 */
99 virtual bool lineContainsStartFoldingRanges(int line) const = 0;
100
101 /**
102 * Fold the first folding range starting on this line, if applicable.
103 * @param line line to fold
104 * @return id of folded range (>= 0) or -1, if no folding range starts at line
105 */
106 virtual qint64 foldLine(int line) const = 0;
107
108 /**
109 * Unfolds all folding range starting on this line, if applicable.
110 * @param line line to unfold
111 * @return id of folded range (>= 0) or -1, if no folding range starts at line
112 */
113 virtual bool unfoldLine(int line) const = 0;
114
115 /**
116 * \}
117 *
118 * \name Line Visibility
119 *
120 * The following functions provide access and manipulation of the range's position.
121 * \{
122 */
123
124 /**
125 * Query if a given line is visible.
126 * Very fast, if nothing is folded, else does binary search
127 * log(n) for n == number of folded ranges
128 * @param line line to query
129 * @param foldedRangeId if the line is not visible and that pointer is not 0, will be filled with id of range hiding the line or -1
130 * @return is that line visible?
131 */
132 virtual bool isLineVisible(int line, qint64 *foldedRangeId = 0) const = 0;
133
134 /**
135 * Ensure that a given line will be visible.
136 * Potentially unfold recursively all folds hiding this line, else just returns.
137 * @param line line to make visible
138 */
139 virtual void ensureLineIsVisible(int line) = 0;
140
141 /**
142 * Query number of visible lines.
143 * Very fast, if nothing is folded, else walks over all folded regions
144 * O(n) for n == number of folded ranges
145 */
146 virtual int visibleLines() const = 0;
147
148 /**
149 * Convert a text buffer line to a visible line number.
150 * Very fast, if nothing is folded, else walks over all folded regions
151 * O(n) for n == number of folded ranges
152 * @param line line index in the text buffer
153 * @return index in visible lines
154 */
155 virtual int lineToVisibleLine(int line) const = 0;
156
157 /**
158 * Convert a visible line number to a line number in the text buffer.
159 * Very fast, if nothing is folded, else walks over all folded regions
160 * O(n) for n == number of folded ranges
161 * @param visibleLine visible line index
162 * @return index in text buffer lines
163 */
164 virtual int visibleLineToLine(int visibleLine) const = 0;
165
166 /**
167 * \}
168 */
169
170public Q_SLOTS:
171 /**
172 * Clear the complete folding.
173 * This is automatically triggered if the buffer is cleared.
174 */
175 void clear();
176
177Q_SIGNALS:
178 /**
179 * If the folding state of existing ranges changes or
180 * ranges are added/removed, this signal is emitted.
181 */
182 void foldingRangesChanged();
183};
184
185Q_DECLARE_OPERATORS_FOR_FLAGS(FoldingInterface::FoldingRangeFlags)
186
187}
188
189#endif
KTextEditor interface for code folding of a KTextEditor::View.
virtual ~FoldingInterface()
Cleanup.
FoldingInterface()
Create folding object for given buffer.
FoldingRangeFlag
Folding state of a range.
An object representing a section of text, from one Cursor to another.
The KTextEditor namespace contains all the public API that is required to use the KTextEditor compone...
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sat Feb 24 2024 20:00:58 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.