KTextEditor

attribute.h
1/*
2 SPDX-FileCopyrightText: 2003-2005 Hamish Rodda <rodda@kde.org>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5*/
6
7#ifndef KTEXTEDITOR_ATTRIBUTE_H
8#define KTEXTEDITOR_ATTRIBUTE_H
9
10#include <QExplicitlySharedDataPointer>
11#include <QSharedData>
12#include <QTextCharFormat>
13
14#include <KSyntaxHighlighting/Theme>
15
16#include <ktexteditor_export.h>
17
18class QAction;
19
20namespace KTextEditor
21{
22
23/**
24 * \class Attribute attribute.h <KTextEditor/Attribute>
25 *
26 * \brief A class which provides customized text decorations.
27 *
28 * The Attribute class extends QTextCharFormat, the class which Qt
29 * uses internally to provide formatting information to characters
30 * in a text document.
31 *
32 * In addition to its inherited properties, it provides support for:
33 * \li several customized text formatting properties
34 * \li dynamic highlighting of associated ranges of text
35 * \li binding of actions with associated ranges of text (note: not currently implemented)
36 *
37 * Implementations are not required to support all properties.
38 * In particular, several properties are not supported for dynamic
39 * highlighting (notably: font() and fontBold()).
40 *
41 * Unfortunately, as QTextFormat's setProperty() is not virtual,
42 * changes that are made to this attribute cannot automatically be
43 * redrawn. Once you have finished changing properties, you should
44 * call changed() to force redrawing of affected ranges of text.
45 *
46 * \sa MovingInterface
47 *
48 * \author Hamish Rodda <rodda@kde.org>
49 */
50class KTEXTEDITOR_EXPORT Attribute : public QTextCharFormat, public QSharedData
51{
52public:
53 /**
54 * Shared data pointer for Attribute
55 */
57
58 /**
59 * Default constructor.
60 * The resulting Attribute has no properties set to begin with.
61 */
62 Attribute();
63
64 /**
65 * Construct attribute with given name & default style properties.
66 * @param name attribute name
67 * @param style attribute default style
68 */
70
71 /**
72 * Copy constructor.
73 */
74 Attribute(const Attribute &a);
75
76 /**
77 * Virtual destructor.
78 */
79 virtual ~Attribute();
80
81 // BEGIN custom properties
82
83 /**
84 * \name Custom properties
85 *
86 * The following functions provide custom properties which can be set for
87 * rendering by editor implementations.
88 * \{
89 */
90
91 /**
92 * Attribute name
93 *
94 * \return attribute name
95 */
96 QString name() const;
97
98 /**
99 * Set attribute name
100 *
101 * \param name new attribute name
102 */
103 void setName(const QString &name);
104
105 /**
106 * Default style of this attribute
107 *
108 * \return default style
109 */
110 KSyntaxHighlighting::Theme::TextStyle defaultStyle() const;
111
112 /**
113 * Set default style of this attribute
114 *
115 * \param style new default style
116 */
117 void setDefaultStyle(KSyntaxHighlighting::Theme::TextStyle style);
118
119 /**
120 * Should spellchecking be skipped?
121 *
122 * \return skip spellchecking?
123 */
124 bool skipSpellChecking() const;
125
126 /**
127 * Set if we should spellchecking be skipped?
128 *
129 * @param skipspellchecking should spellchecking be skipped?
130 */
131 void setSkipSpellChecking(bool skipspellchecking);
132
133 /**
134 * Find out if the font weight is set to QFont::Bold.
135 *
136 * \return \c true if the font weight is exactly QFont::Bold, otherwise \c false
137 *
138 * \see QTextCharFormat::fontWeight()
139 */
140 bool fontBold() const;
141
142 /**
143 * Set the font weight to QFont::Bold. If \a bold is \p false, the weight will be set to 0 (normal).
144 *
145 * \param bold whether the font weight should be bold or not.
146 *
147 * \see QTextCharFormat::setFontWeight()
148 */
149 void setFontBold(bool bold = true);
150
151 /**
152 * Get the brush used to draw an outline around text, if any.
153 *
154 * \return brush to be used to draw an outline, or Qt::NoBrush if no outline is set.
155 */
156 QBrush outline() const;
157
158 /**
159 * Set a brush to be used to draw an outline around text.
160 *
161 * Use \p clearProperty(Outline) to clear.
162 *
163 * \param brush brush to be used to draw an outline.
164 */
165 void setOutline(const QBrush &brush);
166
167 /**
168 * Get the brush used to draw text when it is selected, if any.
169 *
170 * \return brush to be used to draw selected text, or Qt::NoBrush if not set
171 */
172 QBrush selectedForeground() const;
173
174 /**
175 * Set a brush to be used to draw selected text.
176 *
177 * Use \p clearProperty(SelectedForeground) to clear.
178 *
179 * \param foreground brush to be used to draw selected text.
180 */
181 void setSelectedForeground(const QBrush &foreground);
182
183 /**
184 * Get the brush used to draw the background of selected text, if any.
185 *
186 * \return brush to be used to draw the background of selected text, or Qt::NoBrush if not set
187 */
188 QBrush selectedBackground() const;
189
190 /**
191 * Set a brush to be used to draw the background of selected text, if any.
192 *
193 * Use \p clearProperty(SelectedBackground) to clear.
194 *
195 * \param brush brush to be used to draw the background of selected text
196 */
197 void setSelectedBackground(const QBrush &brush);
198
199 /**
200 * Determine whether background color is drawn over whitespace. Defaults to true if not set.
201 *
202 * \return whether the background color should be drawn over whitespace
203 */
204 bool backgroundFillWhitespace() const;
205
206 /**
207 * Set whether background color is drawn over whitespace. Defaults to true if not set.
208 *
209 * Use \p clearProperty(BackgroundFillWhitespace) to clear.
210 *
211 * \param fillWhitespace whether the background should be drawn over whitespace.
212 */
213 void setBackgroundFillWhitespace(bool fillWhitespace);
214
215 /**
216 * Clear all set properties.
217 */
218 void clear();
219
220 /**
221 * Determine if any properties are set.
222 *
223 * \return \e true if any properties are set, otherwise \e false
224 */
225 bool hasAnyProperty() const;
226
227 // END
228
229 // BEGIN Dynamic highlighting
230
231 /**
232 * \name Dynamic highlighting
233 *
234 * The following functions allow for text to be highlighted dynamically based on
235 * several events.
236 * \{
237 */
238
239 /**
240 * Several automatic activation mechanisms exist for associated attributes.
241 * Using this you can conveniently have your ranges highlighted when either
242 * the mouse or cursor enter the range.
243 */
245 /// Activate attribute on mouse in
246 ActivateMouseIn = 0,
247 /// Activate attribute on caret in
248 ActivateCaretIn
249 };
250
251 /**
252 * Return the attribute to use when the event referred to by \a type occurs.
253 *
254 * \param type the activation type for which to return the Attribute.
255 *
256 * \returns the attribute to be used for events specified by \a type, or null if none is set.
257 */
258 Attribute::Ptr dynamicAttribute(ActivationType type) const;
259
260 /**
261 * Set the attribute to use when the event referred to by \a type occurs.
262 *
263 * \note Nested dynamic attributes are ignored.
264 *
265 * \param type the activation type to set the attribute for
266 * \param attribute the attribute to assign. As attribute is refcounted, ownership is not an issue.
267 */
268 void setDynamicAttribute(ActivationType type, Attribute::Ptr attribute);
269
270 //!\}
271
272 // END
273
274 /**
275 * Addition assignment operator. Use this to merge another Attribute with this Attribute.
276 * Where both attributes have a particular property set, the property in \a a will
277 * be used.
278 *
279 * \param a attribute to merge into this attribute.
280 */
281 Attribute &operator+=(const Attribute &a);
282
283 /**
284 * Replacement assignment operator. Use this to overwrite this Attribute with another Attribute.
285 *
286 * \param a attribute to assign to this attribute.
287 */
288 Attribute &operator=(const Attribute &a);
289
290private:
291 /**
292 * Private d-pointer
293 */
294 class AttributePrivate *const d;
295};
296
297/**
298 * @brief Attribute%s of a part of a line.
299 *
300 * An AttributeBlock represents an Attribute spanning the interval
301 * [start, start + length) of a given line. An AttributeBlock is
302 * obtained by calling KTextEditor::View::lineAttributes().
303 *
304 * \see KTextEditor::View::lineAttributes()
305 */
307{
308public:
309 /**
310 * Constructor of AttributeBlock.
311 */
312 AttributeBlock(int _start, int _length, const Attribute::Ptr &_attribute)
313 : start(_start)
314 , length(_length)
315 , attribute(_attribute)
316 {
317 }
318
319 /**
320 * The column this attribute starts at.
321 */
322 int start;
323
324 /**
325 * The number of columns this attribute spans.
326 */
328
329 /**
330 * The attribute for the current range.
331 */
333};
334
335}
336
337Q_DECLARE_TYPEINFO(KTextEditor::AttributeBlock, Q_RELOCATABLE_TYPE);
338
339#endif
Attributes of a part of a line.
Definition attribute.h:307
Attribute::Ptr attribute
The attribute for the current range.
Definition attribute.h:332
int length
The number of columns this attribute spans.
Definition attribute.h:327
int start
The column this attribute starts at.
Definition attribute.h:322
AttributeBlock(int _start, int _length, const Attribute::Ptr &_attribute)
Constructor of AttributeBlock.
Definition attribute.h:312
A class which provides customized text decorations.
Definition attribute.h:51
ActivationType
Several automatic activation mechanisms exist for associated attributes.
Definition attribute.h:244
QExplicitlySharedDataPointer< Attribute > Ptr
Shared data pointer for Attribute.
Definition attribute.h:56
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 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.