KTextEditor

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

KDE's Doxygen guidelines are available online.