Long live Qt 4.5!

1 files changed, 256 insertions, 0 deletions

diff --git a/doc/src/examples/syntaxhighlighter.qdoc b/doc/src/examples/syntaxhighlighter.qdoc
new file mode 100644
index 0000000000..7cc9e61f53
--- /dev/null
+++ b/doc/src/examples/syntaxhighlighter.qdoc
@@ -0,0 +1,256 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at qt-sales@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example richtext/syntaxhighlighter
+    \title Syntax Highlighter Example
+
+    The Syntax Highlighter example shows how to perform simple syntax
+    highlighting by subclassing the QSyntaxHighlighter class.
+
+    \image syntaxhighlighter-example.png
+
+    The Syntax Highlighter application displays C++ files with custom
+    syntax highlighting.
+
+    The example consists of two classes:
+
+    \list
+        \o The \c Highlighter class defines and applies the
+           highlighting rules.
+        \o The \c MainWindow widget is the application's main window.
+    \endlist
+
+    We will first review the \c Highlighter class to see how you can
+    customize the QSyntaxHighlighter class to fit your preferences,
+    then we will take a look at the relevant parts of the \c
+    MainWindow class to see how you can use your custom highlighter
+    class in an application.
+
+    \section1 Highlighter Class Definition
+
+    \snippet examples/richtext/syntaxhighlighter/highlighter.h 0
+
+    To provide your own syntax highlighting, you must subclass
+    QSyntaxHighlighter, reimplement the \l
+    {QSyntaxHighlighter::highlightBlock()}{highlightBlock()} function,
+    and define your own highlighting rules.
+
+    We have chosen to store our highlighting rules using a private
+    struct: A rule consists of a QRegExp pattern and a QTextCharFormat
+    instance. The various rules are then stored using a QVector.
+
+    The QTextCharFormat class provides formatting information for
+    characters in a QTextDocument specifying the visual properties of
+    the text, as well as information about its role in a hypertext
+    document. In this example, we will only define the font weight and
+    color using the QTextCharFormat::setFontWeight() and
+    QTextCharFormat::setForeground() functions.
+
+    \section1 Highlighter Class Implementation
+
+    When subclassing the QSyntaxHighlighter class you must pass the
+    parent parameter to the base class constructor. The parent is the
+    text document upon which the syntax highligning will be
+    applied. In this example, we have also chosen to define our
+    highlighting rules in the constructor:
+
+    \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 0
+    \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 1
+
+    First we define a keyword rule which recognizes the most common
+    C++ keywords. We give the \c keywordFormat a bold, dark blue
+    font. For each keyword, we assign the keyword and the specified
+    format to a HighlightingRule object and append the object to our
+    list of rules.
+
+    \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 2
+    \codeline
+    \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 4
+    \codeline
+    \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 5
+
+    Then we create a format that we will apply to Qt class names. The
+    class names will be rendered with a dark magenta color and a bold
+    style. We specify a string pattern that is actually a regular
+    expression capturing all Qt class names. Then we assign the
+    regular expression and the specified format to a HighlightingRule
+    object and append the object to our list of rules.
+
+    We also define highlighting rules for quotations and functions
+    using the same approach: The patterns have the form of regular
+    expressions and are stored in HighlightingRule objects with the
+    associated format.
+
+    \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 3
+    \codeline
+    \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 6
+
+    The C++ language has two variations of comments: The single line
+    comment (\c //) and the multiline comment (\c{/*...}\starslash). The single
+    line comment can easily be defined through a highlighting rule
+    similar to the previous ones. But the multiline comment needs
+    special care due to the design of the QSyntaxHighlighter class.
+
+    After a QSyntaxHighlighter object is created, its \l
+    {QSyntaxHighlighter::highlightBlock()}{highlightBlock()} function
+    will be called automatically whenever it is necessary by the rich
+    text engine, highlighting the given text block. The problem
+    appears when a comment spans several text blocks. We will take a
+    closer look at how this problem can be solved when reviewing the
+    implementation of the \c Highlighter::highlightBlock()
+    function. At this point we only specify the multiline comment's
+    color.
+
+    \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 7
+
+    The highlightBlock() function is called automatically whenever it
+    is necessary by the rich text engine, i.e. when there are text
+    blocks that have changed.
+
+    First we apply the syntax highlighting rules that we stored in the
+    \c highlightingRules vector. For each rule (i.e. for each
+    HighlightingRule object) we search for the pattern in the given
+    textblock using the QString::indexOf() function. When the first
+    occurrence of the pattern is found, we use the
+    QRegExp::matchedLength() function to determine the string that
+    will be formatted. QRegExp::matchedLength() returns the length of
+    the last matched string, or -1 if there was no match.
+
+    To perform the actual formatting the QSyntaxHighlighter class
+    provides the \l {QSyntaxHighlighter::setFormat()}{setFormat()}
+    function. This function operates on the text block that is passed
+    as argument to the \c highlightBlock() function. The specified
+    format is applied to the text from the given start position for
+    the given length. The formatting properties set in the given
+    format are merged at display time with the formatting information
+    stored directly in the document. Note that the document itself
+    remains unmodified by the format set through this function.
+
+    This process is repeated until the last occurrence of the pattern
+    in the current text block is found.
+
+    \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 8
+
+    To deal with constructs that can span several text blocks (like
+    the C++ multiline comment), it is necessary to know the end state
+    of the previous text block (e.g. "in comment"). Inside your \c
+    highlightBlock() implementation you can query the end state of the
+    previous text block using the
+    QSyntaxHighlighter::previousBlockState() function. After parsing
+    the block you can save the last state using
+    QSyntaxHighlighter::setCurrentBlockState().
+
+    The \l
+    {QSyntaxHighlighter::previousBlockState()}{previousBlockState()}
+    function return an int value. If no state is set, the returned
+    value is -1. You can designate any other value to identify any
+    given state using the \l
+    {QSyntaxHighlighter::setCurrentBlockState()}{setCurrentBlockState()}
+    function. Once the state is set, the QTextBlock keeps that value
+    until it is set again or until the corresponding paragraph of text
+    is deleted.
+
+    In this example we have chosen to use 0 to represent the "not in
+    comment" state, and 1 for the "in comment" state. When the stored
+    syntax highlighting rules are applied we initialize the current
+    block state to 0.
+
+    \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 9
+
+    If the previous block state was "in comment" (\c
+    {previousBlockState() == 1}), we start the search for an end
+    expression at the beginning of the text block. If the
+    previousBlockState() returns 0, we start the search at the
+    location of the first occurrence of a start expression.
+
+    \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 10
+    \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 11
+
+    When an end expression is found, we calculate the length of the
+    comment and apply the multiline comment format. Then we search for
+    the next occurrence of the start expression and repeat the
+    process.  If no end expression can be found in the current text
+    block we set the current block state to 1, i.e. "in comment".
+
+    This completes the \c Highlighter class implementation; it is now
+    ready for use.
+
+    \section1 MainWindow Class Definition
+
+    Using a QSyntaxHighlighter subclass is simple; just provide your
+    application with an instance of the class and pass it the document
+    upon which you want the highlighting to be applied.
+
+    \snippet examples/richtext/syntaxhighlighter/mainwindow.h 0
+
+    In this example we declare a pointer to a \c Highlighter instance
+    which we later will initialize in the private \c setupEditor()
+    function.
+
+    \section1 MainWindow Class Implementation
+
+    The constructor of the main window is straight forward. We first
+    set up the menus, then we initialize the editor and make it the
+    central widget of the application. Finally we set the main
+    window's title.
+
+    \snippet examples/richtext/syntaxhighlighter/mainwindow.cpp 0
+
+    We initialize and install the \c Highlighter object in the private
+    setupEditor() convenience function:
+
+    \snippet examples/richtext/syntaxhighlighter/mainwindow.cpp 1
+
+    First we create the font we want to use in the editor, then we
+    create the editor itself which is an instance of the QTextEdit
+    class. Before we initialize the editor with the \c MainWindow
+    class definition file, we create a \c Highlighter instance passing
+    the editor's document as argument. This is the document that the
+    highlighting will be applied to. Then we are done.
+
+    A QSyntaxHighlighter object can only be installed on one document
+    at the time, but you can easily reinstall the highlighter on
+    another document using the QSyntaxHighlighter::setDocument()
+    function. The QSyntaxHighlighter class also provides the \l
+    {QSyntaxHighlighter::document()}{document()} function which
+    returns the currently set document.
+*/