MauiKit Terminal

Filter.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 FILTER_H
18#define FILTER_H
19
20// Qt
21#include <QAction>
22#include <QHash>
23#include <QList>
24#include <QObject>
25#include <QRegExp>
26#include <QStringList>
27#include <span>
28
29namespace Konsole
30{
31
32typedef unsigned char LineProperty;
33class Character;
34
35/**
36 * A filter processes blocks of text looking for certain patterns (such as URLs or keywords from a list)
37 * and marks the areas which match the filter's patterns as 'hotspots'.
38 *
39 * Each hotspot has a type identifier associated with it ( such as a link or a highlighted section ),
40 * and an action. When the user performs some activity such as a mouse-click in a hotspot area ( the exact
41 * action will depend on what is displaying the block of text which the filter is processing ), the hotspot's
42 * activate() method should be called. Depending on the type of hotspot this will trigger a suitable response.
43 *
44 * For example, if a hotspot represents a URL then a suitable action would be opening that URL in a web browser.
45 * Hotspots may have more than one action, in which case the list of actions can be obtained using the
46 * actions() method.
47 *
48 * Different subclasses of filter will return different types of hotspot.
49 * Subclasses must reimplement the process() method to examine a block of text and identify sections of interest.
50 * When processing the text they should create instances of Filter::HotSpot subclasses for sections of interest
51 * and add them to the filter's list of hotspots using addHotSpot()
52 */
53class Filter : public QObject
54{
55public:
56 /**
57 * Represents an area of text which matched the pattern a particular filter has been looking for.
58 *
59 * Each hotspot has a type identifier associated with it ( such as a link or a highlighted section ),
60 * and an action. When the user performs some activity such as a mouse-click in a hotspot area ( the exact
61 * action will depend on what is displaying the block of text which the filter is processing ), the hotspot's
62 * activate() method should be called. Depending on the type of hotspot this will trigger a suitable response.
63 *
64 * For example, if a hotspot represents a URL then a suitable action would be opening that URL in a web browser.
65 * Hotspots may have more than one action, in which case the list of actions can be obtained using the
66 * actions() method. These actions may then be displayed in a popup menu or toolbar for example.
67 */
68 class HotSpot
69 {
70 public:
71 /**
72 * Constructs a new hotspot which covers the area from (@p startLine,@p startColumn) to (@p endLine,@p endColumn)
73 * in a block of text.
74 */
75 HotSpot(int startLine, int startColumn, int endLine, int endColumn);
76 virtual ~HotSpot();
77
78 enum Type {
79 // the type of the hotspot is not specified
80 NotSpecified,
81 // this hotspot represents a clickable link
82 Link,
83 // this hotspot represents a marker
84 Marker
85 };
86
87 /** Returns the line when the hotspot area starts */
88 int startLine() const;
89 /** Returns the line where the hotspot area ends */
90 int endLine() const;
91 /** Returns the column on startLine() where the hotspot area starts */
92 int startColumn() const;
93 /** Returns the column on endLine() where the hotspot area ends */
94 int endColumn() const;
95 /**
96 * Returns the type of the hotspot. This is usually used as a hint for views on how to represent
97 * the hotspot graphically. eg. Link hotspots are typically underlined when the user mouses over them
98 */
99 Type type() const;
100 /**
101 * Causes the an action associated with a hotspot to be triggered.
102 *
103 * @param action The action to trigger. This is
104 * typically empty ( in which case the default action should be performed ) or
105 * one of the object names from the actions() list. In which case the associated
106 * action should be performed.
107 */
108 virtual void activate(const QString &action = QString()) = 0;
109 /**
110 * Returns a list of actions associated with the hotspot which can be used in a
111 * menu or toolbar
112 */
113 virtual QList<QAction *> actions();
114
115 protected:
116 /** Sets the type of a hotspot. This should only be set once */
117 void setType(Type type);
118
119 private:
120 int _startLine;
121 int _startColumn;
122 int _endLine;
123 int _endColumn;
124 Type _type;
125 };
126
127 /** Constructs a new filter. */
129 ~Filter() override;
130
131 /** Causes the filter to process the block of text currently in its internal buffer */
132 virtual void process() = 0;
133
134 /**
135 * Empties the filters internal buffer and resets the line count back to 0.
136 * All hotspots are deleted.
137 */
138 void reset();
139
140 /** Adds a new line of text to the filter and increments the line count */
141 // void addLine(const QString& string);
142
143 /** Returns the hotspot which covers the given @p line and @p column, or 0 if no hotspot covers that area */
144 HotSpot *hotSpotAt(int line, int column) const;
145
146 /** Returns the list of hotspots identified by the filter */
147 const std::vector<std::unique_ptr<HotSpot>> &hotSpots() const;
148
149 /** Returns the list of hotspots identified by the filter which occur on a given line */
150 QList<HotSpot *> hotSpotsAtLine(int line) const;
151
152 /**
153 * TODO: Document me
154 */
155 void setBuffer(const QString *buffer, const QList<int> *linePositions);
156
157protected:
158 /** Adds a new hotspot to the list */
159 void addHotSpot(std::unique_ptr<HotSpot> &&);
160 /** Returns the internal buffer */
161 const QString *buffer();
162 /** Converts a character position within buffer() to a line and column */
163 void getLineColumn(int position, int &startLine, int &startColumn);
164
165private:
166 std::multimap<int, std::unique_ptr<HotSpot>> _hotspots;
167 std::vector<std::unique_ptr<HotSpot>> _hotspotList;
168
169 const QList<int> *_linePositions;
170 const QString *_buffer;
171};
172
173/**
174 * A filter which searches for sections of text matching a regular expression and creates a new RegExpFilter::HotSpot
175 * instance for them.
176 *
177 * Subclasses can reimplement newHotSpot() to return custom hotspot types when matches for the regular expression
178 * are found.
179 */
180class RegExpFilter : public Filter
181{
182public:
183 /**
184 * Type of hotspot created by RegExpFilter. The capturedTexts() method can be used to find the text
185 * matched by the filter's regular expression.
186 */
188 {
189 public:
190 HotSpot(int startLine, int startColumn, int endLine, int endColumn);
191 void activate(const QString &action = QString()) override;
192
193 /** Sets the captured texts associated with this hotspot */
194 void setCapturedTexts(const QStringList &texts);
195 /** Returns the texts found by the filter when matching the filter's regular expression */
197
198 private:
199 QStringList _capturedTexts;
200 };
201
202 /** Constructs a new regular expression filter */
203 RegExpFilter();
204
205 /**
206 * Sets the regular expression which the filter searches for in blocks of text.
207 *
208 * Regular expressions which match the empty string are treated as not matching
209 * anything.
210 */
211 void setRegExp(const QRegExp &text);
212 /** Returns the regular expression which the filter searches for in blocks of text */
213 QRegExp regExp() const;
214
215 /**
216 * Reimplemented to search the filter's text buffer for text matching regExp()
217 *
218 * If regexp matches the empty string, then process() will return immediately
219 * without finding results.
220 */
221 void process() override;
222
223protected:
224 /**
225 * Called when a match for the regular expression is encountered. Subclasses should reimplement this
226 * to return custom hotspot types
227 */
228 virtual std::unique_ptr<HotSpot> newHotSpot(int startLine, int startColumn, int endLine, int endColumn);
229
230private:
231 QRegExp _searchText;
232};
233
234class FilterObject;
235
236/** A filter which matches URLs in blocks of text */
238{
240public:
241 /**
242 * Hotspot type created by UrlFilter instances. The activate() method opens a web browser
243 * at the given URL when called.
244 */
246 {
247 public:
248 HotSpot(int startLine, int startColumn, int endLine, int endColumn);
249 ~HotSpot() override;
250
251 FilterObject *getUrlObject() const;
252
253 QList<QAction *> actions() override;
254
255 /**
256 * Open a web browser at the current URL. The url itself can be determined using
257 * the capturedTexts() method.
258 */
259 void activate(const QString &action = QString()) override;
260
261 private:
262 enum UrlType { StandardUrl, Email, Unknown };
263 UrlType urlType() const;
264
265 FilterObject *_urlObject;
266 };
267
268 UrlFilter();
269
270protected:
271 std::unique_ptr<RegExpFilter::HotSpot> newHotSpot(int, int, int, int) override;
272
273private:
274 static const QRegExp FullUrlRegExp;
275 static const QRegExp EmailAddressRegExp;
276
277 // combined OR of FullUrlRegExp and EmailAddressRegExp
278 static const QRegExp CompleteUrlRegExp;
280 void activated(const QUrl &url, bool fromContextMenu);
281};
282
283class FilterObject : public QObject
284{
286public:
287 FilterObject(Filter::HotSpot *filter)
288 : _filter(filter)
289 {
290 }
291
292 void emitActivated(const QUrl &url, bool fromContextMenu);
293public Q_SLOTS:
294 void activate();
295
296private:
297 Filter::HotSpot *_filter;
299 void activated(const QUrl &url, bool fromContextMenu);
300};
301
302/**
303 * A chain which allows a group of filters to be processed as one.
304 * The chain owns the filters added to it and deletes them when the chain itself is destroyed.
305 *
306 * Use addFilter() to add a new filter to the chain.
307 * When new text to be filtered arrives, use addLine() to add each additional
308 * line of text which needs to be processed and then after adding the last line, use
309 * process() to cause each filter in the chain to process the text.
310 *
311 * After processing a block of text, the reset() method can be used to set the filter chain's
312 * internal cursor back to the first line.
313 *
314 * The hotSpotAt() method will return the first hotspot which covers a given position.
315 *
316 * The hotSpots() and hotSpotsAtLine() method return all of the hotspots in the text and on
317 * a given line respectively.
318 */
319class FilterChain : protected std::vector<std::unique_ptr<Filter>>
320{
321public:
322 virtual ~FilterChain();
323
324 /** Adds a new filter to the chain. The chain will delete this filter when it is destroyed */
325 void addFilter(std::unique_ptr<Filter> &&filter);
326 /** Removes a filter from the chain. The chain will no longer delete the filter when destroyed */
327 void removeFilter(Filter *filter);
328 /** Returns true if the chain contains @p filter */
329 bool containsFilter(Filter *filter);
330
331 /** Resets each filter in the chain */
332 void reset();
333 /**
334 * Processes each filter in the chain
335 */
336 void process();
337
338 /** Sets the buffer for each filter in the chain to process. */
339 void setBuffer(const QString *buffer, const QList<int> *linePositions);
340
341 /** Returns the first hotspot which occurs at @p line, @p column or 0 if no hotspot was found */
342 Filter::HotSpot *hotSpotAt(int line, int column) const;
343 /** Returns a list of all the hotspots in all the chain's filters */
345 /** Returns a list of all hotspots at the given line in all the chain's filters */
347};
348
349/** A filter chain which processes character images from terminal displays */
351{
352public:
354 ~TerminalImageFilterChain() override;
355
356 /**
357 * Set the current terminal image to @p image.
358 *
359 * @param image The terminal image
360 * @param lines The number of lines in the terminal image
361 * @param columns The number of columns in the terminal image
362 * @param lineProperties The line properties to set for image
363 */
364 void setImage(std::span<const Character> image, int lines, int columns, const QVector<LineProperty> &lineProperties);
365
366private:
367 QString *_buffer;
368 QList<int> *_linePositions;
369};
370
371}
372
373typedef Konsole::Filter Filter;
374
375#endif // FILTER_H
A chain which allows a group of filters to be processed as one.
Definition Filter.h:320
void process()
Processes each filter in the chain.
Definition Filter.cpp:83
bool containsFilter(Filter *filter)
Returns true if the chain contains filter.
Definition Filter.cpp:59
void addFilter(std::unique_ptr< Filter > &&filter)
Adds a new filter to the chain.
Definition Filter.cpp:47
void removeFilter(Filter *filter)
Removes a filter from the chain.
Definition Filter.cpp:52
void reset()
Resets each filter in the chain.
Definition Filter.cpp:69
Filter::HotSpot * hotSpotAt(int line, int column) const
Returns the first hotspot which occurs at line, column or 0 if no hotspot was found.
Definition Filter.cpp:90
QList< Filter::HotSpot > hotSpotsAtLine(int line) const
Returns a list of all hotspots at the given line in all the chain's filters.
QList< Filter::HotSpot * > hotSpots() const
Returns a list of all the hotspots in all the chain's filters.
Definition Filter.cpp:102
void setBuffer(const QString *buffer, const QList< int > *linePositions)
Sets the buffer for each filter in the chain to process.
Definition Filter.cpp:76
Represents an area of text which matched the pattern a particular filter has been looking for.
Definition Filter.h:69
virtual void activate(const QString &action=QString())=0
Causes the an action associated with a hotspot to be triggered.
int endLine() const
Returns the line where the hotspot area ends.
Definition Filter.cpp:283
int startLine() const
Returns the line when the hotspot area starts.
Definition Filter.cpp:279
int endColumn() const
Returns the column on endLine() where the hotspot area ends.
Definition Filter.cpp:291
virtual QList< QAction * > actions()
Returns a list of actions associated with the hotspot which can be used in a menu or toolbar.
Definition Filter.cpp:275
void setType(Type type)
Sets the type of a hotspot.
Definition Filter.cpp:299
HotSpot(int startLine, int startColumn, int endLine, int endColumn)
Constructs a new hotspot which covers the area from (startLine,startColumn) to (endLine,...
Definition Filter.cpp:267
int startColumn() const
Returns the column on startLine() where the hotspot area starts.
Definition Filter.cpp:287
Type type() const
Returns the type of the hotspot.
Definition Filter.cpp:295
A filter processes blocks of text looking for certain patterns (such as URLs or keywords from a list)...
Definition Filter.h:54
void setBuffer(const QString *buffer, const QList< int > *linePositions)
TODO: Document me.
Definition Filter.cpp:188
const std::vector< std::unique_ptr< HotSpot > > & hotSpots() const
Returns the list of hotspots identified by the filter.
Definition Filter.cpp:237
QList< HotSpot * > hotSpotsAtLine(int line) const
Returns the list of hotspots identified by the filter which occur on a given line.
Definition Filter.cpp:242
HotSpot * hotSpotAt(int line, int column) const
Adds a new line of text to the filter and increments the line count.
Definition Filter.cpp:251
const QString * buffer()
Returns the internal buffer.
Definition Filter.cpp:221
void addHotSpot(std::unique_ptr< HotSpot > &&)
Adds a new hotspot to the list.
Definition Filter.cpp:228
virtual void process()=0
Causes the filter to process the block of text currently in its internal buffer.
void reset()
Empties the filters internal buffer and resets the line count back to 0.
Definition Filter.cpp:182
void getLineColumn(int position, int &startLine, int &startColumn)
Converts a character position within buffer() to a line and column.
Definition Filter.cpp:194
Filter()
Constructs a new filter.
Type of hotspot created by RegExpFilter.
Definition Filter.h:188
void activate(const QString &action=QString()) override
Causes the an action associated with a hotspot to be triggered.
Definition Filter.cpp:314
QStringList capturedTexts() const
Returns the texts found by the filter when matching the filter's regular expression.
Definition Filter.cpp:322
void setCapturedTexts(const QStringList &texts)
Sets the captured texts associated with this hotspot.
Definition Filter.cpp:318
A filter which searches for sections of text matching a regular expression and creates a new RegExpFi...
Definition Filter.h:181
void setRegExp(const QRegExp &text)
Sets the regular expression which the filter searches for in blocks of text.
Definition Filter.cpp:327
void process() override
Reimplemented to search the filter's text buffer for text matching regExp()
Definition Filter.cpp:339
virtual std::unique_ptr< HotSpot > newHotSpot(int startLine, int startColumn, int endLine, int endColumn)
Called when a match for the regular expression is encountered.
Definition Filter.cpp:377
QRegExp regExp() const
Returns the regular expression which the filter searches for in blocks of text.
Definition Filter.cpp:331
RegExpFilter()
Constructs a new regular expression filter.
Definition Filter.cpp:304
A filter chain which processes character images from terminal displays.
Definition Filter.h:351
void setImage(std::span< const Character > image, int lines, int columns, const QVector< LineProperty > &lineProperties)
Set the current terminal image to image.
Definition Filter.cpp:126
Hotspot type created by UrlFilter instances.
Definition Filter.h:246
void activate(const QString &action=QString()) override
Open a web browser at the current URL.
Definition Filter.cpp:408
QList< QAction * > actions() override
Returns a list of actions associated with the hotspot which can be used in a menu or toolbar.
Definition Filter.cpp:475
A filter which matches URLs in blocks of text.
Definition Filter.h:238
std::unique_ptr< RegExpFilter::HotSpot > newHotSpot(int, int, int, int) override
Called when a match for the regular expression is encountered.
Definition Filter.cpp:382
Q_OBJECTQ_OBJECT
Q_SIGNALSQ_SIGNALS
Q_SLOTSQ_SLOTS
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.