source: trunk/doc/src/examples/syntaxhighlighter.qdoc@ 846

Last change on this file since 846 was 846, checked in by Dmitry A. Kuminov, 14 years ago

trunk: Merged in qt 4.7.2 sources from branches/vendor/nokia/qt.
File size: 10.7 KB
RevLine 
[2]1/****************************************************************************
2**
[846]3** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
[561]4** All rights reserved.
5** Contact: Nokia Corporation ([email protected])
[2]6**
7** This file is part of the documentation of the Qt Toolkit.
8**
[846]9** $QT_BEGIN_LICENSE:FDL$
[2]10** Commercial Usage
11** Licensees holding valid Qt Commercial licenses may use this file in
12** accordance with the Qt Commercial License Agreement provided with the
[846]13** Software or, alternatively, in accordance with the terms contained in a
14** written agreement between you and Nokia.
[2]15**
[846]16** GNU Free Documentation License
17** Alternatively, this file may be used under the terms of the GNU Free
18** Documentation License version 1.3 as published by the Free Software
19** Foundation and appearing in the file included in the packaging of this
20** file.
[2]21**
[561]22** If you have questions regarding the use of this file, please contact
23** Nokia at [email protected].
[2]24** $QT_END_LICENSE$
25**
26****************************************************************************/
27
28/*!
29 \example richtext/syntaxhighlighter
30 \title Syntax Highlighter Example
31
32 The Syntax Highlighter example shows how to perform simple syntax
33 highlighting by subclassing the QSyntaxHighlighter class.
34
35 \image syntaxhighlighter-example.png
36
37 The Syntax Highlighter application displays C++ files with custom
38 syntax highlighting.
39
40 The example consists of two classes:
41
42 \list
43 \o The \c Highlighter class defines and applies the
44 highlighting rules.
45 \o The \c MainWindow widget is the application's main window.
46 \endlist
47
48 We will first review the \c Highlighter class to see how you can
49 customize the QSyntaxHighlighter class to fit your preferences,
50 then we will take a look at the relevant parts of the \c
51 MainWindow class to see how you can use your custom highlighter
52 class in an application.
53
54 \section1 Highlighter Class Definition
55
56 \snippet examples/richtext/syntaxhighlighter/highlighter.h 0
57
58 To provide your own syntax highlighting, you must subclass
59 QSyntaxHighlighter, reimplement the \l
60 {QSyntaxHighlighter::highlightBlock()}{highlightBlock()} function,
61 and define your own highlighting rules.
62
63 We have chosen to store our highlighting rules using a private
64 struct: A rule consists of a QRegExp pattern and a QTextCharFormat
65 instance. The various rules are then stored using a QVector.
66
67 The QTextCharFormat class provides formatting information for
68 characters in a QTextDocument specifying the visual properties of
69 the text, as well as information about its role in a hypertext
70 document. In this example, we will only define the font weight and
71 color using the QTextCharFormat::setFontWeight() and
72 QTextCharFormat::setForeground() functions.
73
74 \section1 Highlighter Class Implementation
75
76 When subclassing the QSyntaxHighlighter class you must pass the
77 parent parameter to the base class constructor. The parent is the
78 text document upon which the syntax highligning will be
79 applied. In this example, we have also chosen to define our
80 highlighting rules in the constructor:
81
82 \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 0
83 \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 1
84
85 First we define a keyword rule which recognizes the most common
86 C++ keywords. We give the \c keywordFormat a bold, dark blue
87 font. For each keyword, we assign the keyword and the specified
88 format to a HighlightingRule object and append the object to our
89 list of rules.
90
91 \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 2
92 \codeline
93 \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 4
94 \codeline
95 \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 5
96
97 Then we create a format that we will apply to Qt class names. The
98 class names will be rendered with a dark magenta color and a bold
99 style. We specify a string pattern that is actually a regular
100 expression capturing all Qt class names. Then we assign the
101 regular expression and the specified format to a HighlightingRule
102 object and append the object to our list of rules.
103
104 We also define highlighting rules for quotations and functions
105 using the same approach: The patterns have the form of regular
106 expressions and are stored in HighlightingRule objects with the
107 associated format.
108
109 \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 3
110 \codeline
111 \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 6
112
113 The C++ language has two variations of comments: The single line
114 comment (\c //) and the multiline comment (\c{/*...}\starslash). The single
115 line comment can easily be defined through a highlighting rule
116 similar to the previous ones. But the multiline comment needs
117 special care due to the design of the QSyntaxHighlighter class.