/****************************************************************************

**

** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

** All rights reserved.

** Contact: Nokia Corporation (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 Technology Preview License Agreement accompanying

** this package.

**

** 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.1, included in the file LGPL_EXCEPTION.txt in this package.

**

** If you have questions regarding the use of this file, please contact

** Nokia at qt-info@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.

*/