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 <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 enum DefaultStyle { 27 // 28 // normal text 29 // 30 /** Default for normal text and source code. */ 31 dsNormal = 0, 32 /** Used for language keywords. */ 33 dsKeyword, 34 /** Used for function definitions and function calls. */ 35 dsFunction, 36 /** Used for variables, if applicable. */ 37 dsVariable, 38 /** Used for control flow highlighting, e.g., if, then, else, return, continue. */ 39 dsControlFlow, 40 /** Used for operators such as +, -, *, / and :: etc. */ 41 dsOperator, 42 /** Used for built-in language classes and functions. */ 43 dsBuiltIn, 44 /** Used for extensions, such as Qt or boost. */ 45 dsExtension, 46 /** Used for preprocessor statements. */ 47 dsPreprocessor, 48 /** Used for attributes of a function, e.g. \@override in Java. */ 49 dsAttribute, 50 51 // 52 // Strings & Characters 53 // 54 /** Used for a single character. */ 55 dsChar, 56 /** Used for an escaped character. */ 57 dsSpecialChar, 58 /** Used for strings. */ 59 dsString, 60 /** Used for verbatim strings such as HERE docs. */ 61 dsVerbatimString, 62 /** Used for special strings such as regular expressions or LaTeX math mode. */ 63 dsSpecialString, 64 /** Used for includes, imports and modules. */ 65 dsImport, 66 67 // 68 // Number, Types & Constants 69 // 70 /** Used for data types such as int, char, float etc. */ 71 dsDataType, 72 /** Used for decimal values. */ 73 dsDecVal, 74 /** Used for numbers with base other than 10. */ 75 dsBaseN, 76 /** Used for floating point numbers. */ 77 dsFloat, 78 /** Used for language constants. */ 79 dsConstant, 80 81 // 82 // Comments & Documentation 83 // 84 /** Used for normal comments. */ 85 dsComment, 86 /** Used for comments that reflect API documentation. */ 87 dsDocumentation, 88 /** Used for annotations in comments, e.g. \@param in Doxygen or JavaDoc. */ 89 dsAnnotation, 90 /** Used to refer to variables in a comment, e.g. after \@param in Doxygen or JavaDoc. */ 91 dsCommentVar, 92 /** Used for region markers, typically defined by BEGIN/END. */ 93 dsRegionMarker, 94 /** Used for information, e.g. the keyword \@note in Doxygen. */ 95 dsInformation, 96 /** Used for warnings, e.g. the keyword \@warning in Doxygen. */ 97 dsWarning, 98 /** Used for comment specials TODO and WARNING in comments. */ 99 dsAlert, 100 101 // 102 // Misc 103 // 104 /** Used for attributes that do not match any of the other default styles. */ 105 dsOthers, 106 /** Used to indicate wrong syntax. */ 107 dsError 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 \<rodda@kde.org\> 141 */ 142 class KTEXTEDITOR_EXPORT Attribute : public QTextCharFormat, public QSharedData 143 { 144 public: 145 /** 146 * Shared data pointer for Attribute 147 */ 148 typedef QExplicitlySharedDataPointer<Attribute> Ptr; 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 */ 336 enum ActivationType { 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 */ 398 class AttributeBlock 399 { 400 public: 401 /** 402 * Constructor of AttributeBlock. 403 */ AttributeBlock(int _start,int _length,const Attribute::Ptr & _attribute)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 */ 424 Attribute::Ptr attribute; 425 }; 426 427 } 428 429 Q_DECLARE_TYPEINFO(KTextEditor::AttributeBlock, Q_MOVABLE_TYPE); 430 431 #endif 432