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

KDE's Doxygen guidelines are available online.