Initial import from the monolithic Qt.

This is the beginning of revision history for this module. If you
want to look at revision history older than this, please refer to the
Qt Git wiki for how to use Git history grafting. At the time of
writing, this wiki is located here:

http://qt.gitorious.org/qt/pages/GitIntroductionWithQt

If you have already performed the grafting and you don't see any
history beyond this commit, try running "git log" with the "--follow"
argument.

Branched from the monolithic repo, Qt master branch, at commit
896db169ea224deb96c59ce8af800d019de63f12

1 files changed, 195 insertions, 0 deletions

diff --git a/doc/src/examples/codeeditor.qdoc b/doc/src/examples/codeeditor.qdoc
new file mode 100644
index 00000000000..23a2fd41406
--- /dev/null
+++ b/doc/src/examples/codeeditor.qdoc
@@ -0,0 +1,195 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation ([email protected])
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** 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 Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of this
+** file.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at [email protected].
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example widgets/codeeditor
+    \title Code Editor Example
+
+    The Code Editor example shows how to create a simple editor that
+    has line numbers and that highlights the current line.
+
+    \image codeeditor-example.png
+
+    As can be seen from the image, the editor displays the line
+    numbers in an area to the left of the area for editing. The editor
+    will highlight the line containing the cursor.
+
+    We implement the editor in \c CodeEditor, which is a widget that
+    inherits QPlainTextEdit. We keep a separate widget in \c
+    CodeEditor (\c LineNumberArea) onto which we draw the line
+    numbers.
+
+    QPlainTextEdit inherits from QAbstractScrollArea, and editing
+    takes place within its \l{QAbstractScrollArea::}{viewport()}'s
+    margins. We make room for our line number area by setting the left
+    margin of the viewport to the size we need to draw the line
+    numbers.
+
+    When it comes to editing code, we prefer QPlainTextEdit over
+    QTextEdit because it is optimized for handling plain text. See
+    the QPlainTextEdit class description for details.
+
+    QPlainTextEdit lets us add selections in addition to the
+    selection the user can make with the mouse or keyboard. We use
+    this functionality to highlight the current line. More on this
+    later.
+
+    We will now move on to the definitions and implementations of \c
+    CodeEditor and \c LineNumberArea. Let's start with the \c
+    LineNumberArea class. 
+
+    \section1 The LineNumberArea Class
+
+    We paint the line numbers on this widget, and place it over the \c
+    CodeEditor's \l{QAbstractScrollArea::}{viewport()}'s left margin
+    area.
+
+    We need to use protected functions in QPlainTextEdit while
+    painting the area. So to keep things simple, we  paint the area in
+    the \c CodeEditor class. The area also asks the editor to
+    calculate its size hint.
+
+    Note that we could simply paint the line numbers directly on the
+    code editor, and drop the LineNumberArea class. However, the
+    QWidget class helps us to \l{QWidget::}{scroll()} its contents.
+    Also, having a separate widget is the right choice if we wish to
+    extend the editor with breakpoints or other code editor features.
+    The widget would then help in the handling of mouse events.
+
+    \snippet widgets/codeeditor/codeeditor.h extraarea
+
+    \section1 CodeEditor Class Definition
+
+    Here is the code editor's class definition:
+
+    \snippet widgets/codeeditor/codeeditor.h codeeditordefinition
+
+    In the editor we resize and draw the line numbers on the \c
+    LineNumberArea. We need to do this when the number of lines in the
+    editor changes, and when the editor's viewport() is scrolled. Of
+    course, it is also done when the editor's size changes. We do
+    this in \c updateLineNumberWidth() and \c updateLineNumberArea().
+
+    Whenever, the cursor's position changes, we highlight the current
+    line in \c highlightCurrentLine().
+
+    \section1 CodeEditor Class Implementation
+
+    We will now go through the code editors implementation, starting
+    off with the constructor.
+
+    \snippet widgets/codeeditor/codeeditor.cpp constructor
+
+    In the constructor we connect our slots to signals in
+    QPlainTextEdit. It is necessary to calculate the line number area
+    width and highlight the first line when the editor is created.
+
+    \snippet widgets/codeeditor/codeeditor.cpp extraAreaWidth
+
+    The \c lineNumberAreaWidth() function calculates the width of the
+    \c LineNumberArea widget. We take the number of digits in the last
+    line of the editor and multiply that with the maximum width of a
+    digit.
+
+    \snippet widgets/codeeditor/codeeditor.cpp slotUpdateExtraAreaWidth
+
+    When we update the width of the line number area, we simply call
+    QAbstractScrollArea::setViewportMargins().
+
+    \snippet widgets/codeeditor/codeeditor.cpp slotUpdateRequest
+
+    This slot is invoked when the editors viewport has been scrolled.
+    The QRect given as argument is the part of the editing area that
+    is do be updated (redrawn). \c dy holds the number of pixels the
+    view has been scrolled vertically.
+
+    \snippet widgets/codeeditor/codeeditor.cpp resizeEvent
+
+    When the size of the editor changes, we also need to resize the
+    line number area. 
+
+    \snippet widgets/codeeditor/codeeditor.cpp cursorPositionChanged
+
+    When the cursor position changes, we highlight the current line,
+    i.e., the line containing the cursor.
+
+    QPlainTextEdit gives the possibility to have more than one
+    selection at the same time. we can set the character format
+    (QTextCharFormat) of these selections. We clear the cursors
+    selection before setting the new new
+    QPlainTextEdit::ExtraSelection, else several lines would get
+    highlighted when the user selects multiple lines with the mouse.
+    \omit ask someone how this works \endomit
+
+    One sets the selection with a text cursor. When using the
+    FullWidthSelection property, the current cursor text block (line)
+    will be selected. If you want to select just a portion of the text
+    block, the cursor should be moved with QTextCursor::movePosition()
+    from a position set with \l{QTextCursor::}{setPosition()}.
+
+    \snippet widgets/codeeditor/codeeditor.cpp extraAreaPaintEvent_0
+
+    The \c lineNumberAreaPaintEvent() is called from \c LineNumberArea
+    whenever it receives a paint event. We start off by painting the
+    widget's background. 
+
+    \snippet widgets/codeeditor/codeeditor.cpp extraAreaPaintEvent_1
+
+    We will now loop through all visible lines and paint the line
+    numbers in the extra area for each line. Notice that in a plain
+    text edit each line will consist of one QTextBlock; though, if
+    line wrapping is enabled, a line may span several rows in the text
+    edit's viewport. 
+
+    We get the top and bottom y-coordinate of the first text block,
+    and adjust these values by the height of the current text block in
+    each iteration in the loop. 
+
+    \snippet widgets/codeeditor/codeeditor.cpp extraAreaPaintEvent_2
+
+    Notice that we check if the block is visible in addition to check
+    if it is in the areas viewport - a block can, for example, be
+    hidden by a window placed over the text edit.
+
+    \section1 Suggestions for Extending the Code Editor
+
+    No self-respecting code editor is without a syntax
+    highligther; the \l{Syntax Highlighter Example} shows how to
+    create one.
+
+    In addition to line numbers, you can add more to the extra area,
+    for instance, break points.
+        
+    QSyntaxHighlighter gives the possibility to add user data to each
+    text block with
+    \l{QSyntaxHighlighter::}{setCurrentBlockUserData()}. This can be
+    used to implement parenthesis matching. In the \c
+    highlightCurrentLine(), the data of the currentBlock() can be
+    fetched with QTextBlock::userData(). Matching parentheses can be
+    highlighted with an extra selection.
+
+*/