1/* This file is part of the KDE libraries
2 * Copyright (C) 2003-2005 Hamish Rodda <rodda@kde.org>
3 *
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Library General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
8 *
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Library General Public License for more details.
13 *
14 * You should have received a copy of the GNU Library General Public License
15 * along with this library; see the file COPYING.LIB. If not, write to
16 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17 * Boston, MA 02110-1301, USA.
18 */
19
20#ifndef KTEXTEDITOR_ATTRIBUTE_H
21#define KTEXTEDITOR_ATTRIBUTE_H
22
23#include <QTextFormat>
24
25#include <QSharedData>
26#include <QExplicitlySharedDataPointer>
27
28#include <ktexteditor_export.h>
29
30class QAction;
31
32namespace KTextEditor
33{
34
35/**
36 * The following lists all valid default styles that are used for the syntax
37 * highlighting files in the itemData's defStyleNum attribute.
38 * Not all default styles are used by a syntax highlighting file.
39 */
40enum DefaultStyle {
41 //
42 // normal text
43 //
44 /** Default for normal text and source code. */
45 dsNormal = 0,
46 /** Used for language keywords. */
47 dsKeyword,
48 /** Used for function definitions and function calls. */
49 dsFunction,
50 /** Used for variables, if applicable. */
51 dsVariable,
52 /** Used for control flow highlighting, e.g., if, then, else, return, continue. */
53 dsControlFlow,
54 /** Used for operators such as +, -, *, / and :: etc. */
55 dsOperator,
56 /** Used for built-in language classes and functions. */
57 dsBuiltIn,
58 /** Used for extensions, such as Qt or boost. */
59 dsExtension,
60 /** Used for preprocessor statements. */
61 dsPreprocessor,
62 /** Used for attributes of a function, e.g. \@override in Java. */
63 dsAttribute,
64
65 //
66 // Strings & Characters
67 //
68 /** Used for a single character. */
69 dsChar,
70 /** Used for an escaped character. */
71 dsSpecialChar,
72 /** Used for strings. */
73 dsString,
74 /** Used for verbatim strings such as HERE docs. */
75 dsVerbatimString,
76 /** Used for special strings such as regular expressions or LaTeX math mode. */
77 dsSpecialString,
78 /** Used for includes, imports and modules. */
79 dsImport,
80
81 //
82 // Number, Types & Constants
83 //
84 /** Used for data types such as int, char, float etc. */
85 dsDataType,
86 /** Used for decimal values. */
87 dsDecVal,
88 /** Used for numbers with base other than 10. */
89 dsBaseN,
90 /** Used for floating point numbers. */
91 dsFloat,
92 /** Used for language constants. */
93 dsConstant,
94
95 //
96 // Comments & Documentation
97 //
98 /** Used for normal comments. */
99 dsComment,
100 /** Used for comments that reflect API documentation. */
101 dsDocumentation,
102 /** Used for annotations in comments, e.g. \@param in Doxygen or JavaDoc. */
103 dsAnnotation,
104 /** Used to refer to variables in a comment, e.g. after \@param in Doxygen or JavaDoc. */
105 dsCommentVar,
106 /** Used for region markers, typically defined by BEGIN/END. */
107 dsRegionMarker,
108 /** Used for information, e.g. the keyword \@note in Doxygen. */
109 dsInformation,
110 /** Used for warnings, e.g. the keyword \@warning in Doxygen. */
111 dsWarning,
112 /** Used for comment specials TODO and WARNING in comments. */
113 dsAlert,
114
115 //
116 // Misc
117 //
118 /** Used for attributes that do not match any of the other default styles. */
119 dsOthers,
120 /** Used to indicate wrong syntax. */
121 dsError
122
123 //
124 // WARNING: Whenever you add a default style to this list,
125 // make sure to adapt KateHlManager::defaultStyleCount()
126 //
127};
128
129/**
130 * \brief A class which provides customized text decorations.
131 *
132 * The Attribute class extends QTextCharFormat, the class which Qt
133 * uses internally to provide formatting information to characters
134 * in a text document.
135 *
136 * In addition to its inherited properties, it provides support for:
137 * \li several customized text formatting properties
138 * \li dynamic highlighting of associated ranges of text
139 * \li binding of actions with associated ranges of text (note: not currently implemented)
140 *
141 * Implementations are not required to support all properties.
142 * In particular, several properties are not supported for dynamic
143 * highlighting (notably: font() and fontBold()).
144 *
145 * Unfortunately, as QTextFormat's setProperty() is not virtual,
146 * changes that are made to this attribute cannot automatically be
147 * redrawn. Once you have finished changing properties, you should
148 * call changed() to force redrawing of affected ranges of text.
149 *
150 * \sa MovingInterface
151 *
152 * \author Hamish Rodda \<rodda@kde.org\>
153 */
154class KTEXTEDITOR_EXPORT Attribute : public QTextCharFormat, public QSharedData
155{
156public:
157 /**
158 * Shared data pointer for Attribute
159 */
160 typedef QExplicitlySharedDataPointer<Attribute> Ptr;
161
162 /**
163 * Default constructor.
164 * The resulting Attribute has no properties set to begin with.
165 */
166 Attribute();
167
168 /**
169 * Construct attribute with given name & default style properties.
170 * @param name attribute name
171 * @param style attribute default style
172 */
173 Attribute(const QString &name, DefaultStyle style);
174
175 /**
176 * Copy constructor.
177 */
178 Attribute(const Attribute &a);
179
180 /**
181 * Virtual destructor.
182 */
183 virtual ~Attribute();
184
185 //BEGIN custom properties
186
187 /**
188 * \name Custom properties
189 *
190 * The following functions provide custom properties which can be set for
191 * rendering by editor implementations.
192 * \{
193 */
194
195 /**
196 * Attribute name
197 *
198 * \return attribute name
199 */
200 QString name() const;
201
202 /**
203 * Set attribute name
204 *
205 * \param name new attribute name
206 */
207 void setName(const QString &name);
208
209 /**
210 * Default style of this attribute
211 *
212 * \return default style
213 */
214 DefaultStyle defaultStyle() const;
215
216 /**
217 * Set default style of this attribute
218 *
219 * \param style new default style
220 */
221 void setDefaultStyle(DefaultStyle style);
222
223 /**
224 * Should spellchecking be skipped?
225 *
226 * \return skip spellchecking?
227 */
228 bool skipSpellChecking() const;
229
230 /**
231 * Set if we should spellchecking be skipped?
232 *
233 * @param skipspellchecking should spellchecking be skipped?
234 */
235 void setSkipSpellChecking(bool skipspellchecking);
236
237 /**
238 * Find out if the font weight is set to QFont::Bold.
239 *
240 * \return \c true if the font weight is exactly QFont::Bold, otherwise \c false
241 *
242 * \see QTextCharFormat::fontWeight()
243 */
244 bool fontBold() const;
245
246 /**
247 * Set the font weight to QFont::Bold. If \a bold is \p false, the weight will be set to 0 (normal).
248 *
249 * \param bold whether the font weight should be bold or not.
250 *
251 * \see QTextCharFormat::setFontWeight()
252 */
253 void setFontBold(bool bold = true);
254
255 /**
256 * Get the brush used to draw an outline around text, if any.
257 *
258 * \return brush to be used to draw an outline, or Qt::NoBrush if no outline is set.
259 */
260 QBrush outline() const;
261
262 /**
263 * Set a brush to be used to draw an outline around text.
264 *
265 * Use \p clearProperty(Outline) to clear.
266 *
267 * \param brush brush to be used to draw an outline.
268 */
269 void setOutline(const QBrush &brush);
270
271 /**
272 * Get the brush used to draw text when it is selected, if any.
273 *
274 * \return brush to be used to draw selected text, or Qt::NoBrush if not set
275 */
276 QBrush selectedForeground() const;
277
278 /**
279 * Set a brush to be used to draw selected text.
280 *
281 * Use \p clearProperty(SelectedForeground) to clear.
282 *
283 * \param foreground brush to be used to draw selected text.
284 */
285 void setSelectedForeground(const QBrush &foreground);
286
287 /**
288 * Get the brush used to draw the background of selected text, if any.
289 *
290 * \return brush to be used to draw the background of selected text, or Qt::NoBrush if not set
291 */
292 QBrush selectedBackground() const;
293
294 /**
295 * Set a brush to be used to draw the background of selected text, if any.
296 *
297 * Use \p clearProperty(SelectedBackground) to clear.
298 *
299 * \param brush brush to be used to draw the background of selected text
300 */
301 void setSelectedBackground(const QBrush &brush);
302
303 /**
304 * Determine whether background color is drawn over whitespace. Defaults to true if not set.
305 *
306 * \return whether the background color should be drawn over whitespace
307 */
308 bool backgroundFillWhitespace() const;
309
310 /**
311 * Set whether background color is drawn over whitespace. Defaults to true if not set.
312 *
313 * Use \p clearProperty(BackgroundFillWhitespace) to clear.
314 *
315 * \param fillWhitespace whether the background should be drawn over whitespace.
316 */
317 void setBackgroundFillWhitespace(bool fillWhitespace);
318
319 /**
320 * Clear all set properties.
321 */
322 void clear();
323
324 /**
325 * Determine if any properties are set.
326 *
327 * \return \e true if any properties are set, otherwise \e false
328 */
329 bool hasAnyProperty() const;
330
331 //END
332
333 //BEGIN Dynamic highlighting
334
335 /**
336 * \name Dynamic highlighting
337 *
338 * The following functions allow for text to be highlighted dynamically based on
339 * several events.
340 * \{
341 */
342
343 /**
344 * Several automatic activation mechanisms exist for associated attributes.
345 * Using this you can conveniently have your ranges highlighted when either
346 * the mouse or cursor enter the range.
347 */
348 enum ActivationType {
349 /// Activate attribute on mouse in
350 ActivateMouseIn = 0,
351 /// Activate attribute on caret in
352 ActivateCaretIn
353 };
354
355 /**
356 * Return the attribute to use when the event referred to by \a type occurs.
357 *
358 * \param type the activation type for which to return the Attribute.
359 *
360 * \returns the attribute to be used for events specified by \a type, or null if none is set.
361 */
362 Attribute::Ptr dynamicAttribute(ActivationType type) const;
363
364 /**
365 * Set the attribute to use when the event referred to by \a type occurs.
366 *
367 * \note Nested dynamic attributes are ignored.
368 *
369 * \param type the activation type to set the attribute for
370 * \param attribute the attribute to assign. As attribute is refcounted, ownership is not an issue.
371 */
372 void setDynamicAttribute(ActivationType type, Attribute::Ptr attribute);
373
374 //!\}
375
376 //END
377
378 /**
379 * Addition assignment operator. Use this to merge another Attribute with this Attribute.
380 * Where both attributes have a particular property set, the property in \a a will
381 * be used.
382 *
383 * \param a attribute to merge into this attribute.
384 */
385 Attribute &operator+=(const Attribute &a);
386
387 /**
388 * Replacement assignment operator. Use this to overwrite this Attribute with another Attribute.
389 *
390 * \param a attribute to assign to this attribute.
391 */
392 Attribute &operator=(const Attribute &a);
393
394private:
395 /**
396 * Private d-pointer
397 */
398 class AttributePrivate *const d;
399};
400
401/**
402 * @brief Attribute%s of a part of a line.
403 *
404 * An AttributeBlock represents an Attribute spanning the interval
405 * [start, start + length) of a given line. An AttributeBlock is
406 * obtained by calling KTextEditor::View::lineAttributes().
407 *
408 * \see KTextEditor::View::lineAttributes()
409 */
410class AttributeBlock
411{
412public:
413 /**
414 * Constructor of AttributeBlock.
415 */
416 AttributeBlock(int _start, int _length, const Attribute::Ptr &_attribute)
417 : start(_start), length(_length), attribute(_attribute) {
418 }
419
420 /**
421 * The column this attribute starts at.
422 */
423 int start;
424
425 /**
426 * The number of columns this attribute spans.
427 */
428 int length;
429
430 /**
431 * The attribute for the current range.
432 */
433 Attribute::Ptr attribute;
434};
435
436}
437
438Q_DECLARE_TYPEINFO(KTextEditor::AttributeBlock, Q_MOVABLE_TYPE);
439
440#endif
441