Doc: Adding Qt Quick Controls "Getting Started".

-A new Getting Started guide that uses the Qt Designer and Qt Creator
workflow.
-Uses Controls, Layouts, and Window QML types.
-Written with Qt Creator 3.3 and Qt 5.4.

Task-number: QTBUG-33595
Change-Id: I75fe5d6b439255d867de75b6b5c7c26bc82491e0
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@theqtcompany.com>

23 files changed, 1190 insertions, 2 deletions

diff --git a/doc/config/qtdoc.qdocconf b/doc/config/qtdoc.qdocconf
index b4cf38582..01d381b7d 100644
--- a/doc/config/qtdoc.qdocconf
+++ b/doc/config/qtdoc.qdocconf
@@ -65,11 +65,13 @@ imagedirs   += ../src/images \
                ../images
 
 sourcedirs  += \
-    ../src
+    ../src \
+    ../../examples
 
 exampledirs += \
     ../src \
-    ../snippets
+    ../snippets \
+    ../../examples
 
 # Don't parse files in snippets directory
 excludedirs += \
diff --git a/doc/images/controlstexteditor/controlstexteditor_designer.png b/doc/images/controlstexteditor/controlstexteditor_designer.png
new file mode 100644
index 000000000..729b6d6fa
--- /dev/null
+++ b/doc/images/controlstexteditor/controlstexteditor_designer.png
diff --git a/doc/images/controlstexteditor/controlstexteditor_main.png b/doc/images/controlstexteditor/controlstexteditor_main.png
new file mode 100644
index 000000000..81c16f74c
--- /dev/null
+++ b/doc/images/controlstexteditor/controlstexteditor_main.png
diff --git a/doc/images/controlstexteditor/controlstexteditor_navigator.png b/doc/images/controlstexteditor/controlstexteditor_navigator.png
new file mode 100644
index 000000000..4dd26c792
--- /dev/null
+++ b/doc/images/controlstexteditor/controlstexteditor_navigator.png
diff --git a/doc/images/controlstexteditor/controlstexteditor_newproperties.png b/doc/images/controlstexteditor/controlstexteditor_newproperties.png
new file mode 100644
index 000000000..eea00c35a
--- /dev/null
+++ b/doc/images/controlstexteditor/controlstexteditor_newproperties.png
diff --git a/doc/images/controlstexteditor/controlstexteditor_openproperties.png b/doc/images/controlstexteditor/controlstexteditor_openproperties.png
new file mode 100644
index 000000000..a8b32275d
--- /dev/null
+++ b/doc/images/controlstexteditor/controlstexteditor_openproperties.png
diff --git a/doc/images/controlstexteditor/controlstexteditor_rowproperties.png b/doc/images/controlstexteditor/controlstexteditor_rowproperties.png
new file mode 100644
index 000000000..83a56702f
--- /dev/null
+++ b/doc/images/controlstexteditor/controlstexteditor_rowproperties.png
diff --git a/doc/images/qtcreator/qtcreator-run.png b/doc/images/qtcreator/qtcreator-run.png
new file mode 100644
index 000000000..a4c24365d
--- /dev/null
+++ b/doc/images/qtcreator/qtcreator-run.png
diff --git a/doc/src/examples.qdoc b/doc/src/examples.qdoc
index 1c3709e4b..2e0f03451 100644
--- a/doc/src/examples.qdoc
+++ b/doc/src/examples.qdoc
@@ -90,6 +90,7 @@
         \li \l{Qt Creator: Developing Qt Quick Applications}{Developing Qt Quick Applications}
         \li \l{Qt Quick Controls - Gallery}{Controls Gallery}
         \li \l{QML Advanced Tutorial}{SameGame}
+        \li \l{Qt Quick Text Editor Guide}
         \endlist
         \list
         \li \l{Qt Quick Examples and Tutorials}{See more}
diff --git a/doc/src/getting-started/controls-texteditor.qdoc b/doc/src/getting-started/controls-texteditor.qdoc
new file mode 100644
index 000000000..b5a4d7489
--- /dev/null
+++ b/doc/src/getting-started/controls-texteditor.qdoc
@@ -0,0 +1,685 @@
+/****************************************************************************
+**
+** Copyright (C) 2015 The Qt Company Ltd.
+** Contact: http://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see http://www.qt.io/terms-conditions. For further
+** information use the contact form at http://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** 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. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\page qtquickcontrols-texteditor.html
+\title Qt Quick Text Editor Guide
+\nextpage Qt Quick Text Editor Guide - UI
+\brief Walkthrough of an application built with Qt Quick Controls.
+
+\section1 Application Design
+
+The \e{Text Editor} example is a simple example of creating an application
+with Qt. Specifically, the example uses QML to set up the user interface,
+C++ to implement the file operations, and the Qt tools to manage the project
+files and build environment.
+
+We will use Qt Quick Designer to add QML controls onto our application and set
+up the controls and resources. We will also implement the logic and connect
+the user interface to a C++ backend that will handle the saving and loading of
+text files.
+
+This guide assumes that you have downloaded Qt and are able to install, open,
+and run the basic examples found in Qt Creator's \uicontrol{Welcome Mode}. If
+not, here are the pages that will help you:
+
+\list
+\li \l{Getting Started with Qt}
+\endlist
+
+The guide attempts to be self-contained but will refer to topics in the Qt
+reference documentation. Feel free to click on the links, but it is not
+necessary to leave the guide to find the information necessary to develop
+the application.
+
+The files are part of the Qt package and are available when searched for
+\uicontrol{Qt Quick Text Editor} in Qt Creator's \uicontrol{Welcome mode}.
+All files used in the application are listed for viewing in the
+\l{Qt Quick Controls Text Editor Example} page.
+
+\section1 Setting Up the Environment and Project
+
+We can start by creating the project in Qt Creator. Our application has the
+name \e{Text Editor} and it is a Qt Quick Application. Qt Creator has a wizard
+that can create the project for you.
+
+\list 1
+    \li Select \uicontrol File > \uicontrol {New File or Project} > \uicontrol Applications >
+        \uicontrol {Qt Quick Application} > \uicontrol Choose.
+    \li In the \uicontrol Name field, enter \uicontrol TextEditor and select \uicontrol Next.
+    \li In the \uicontrol {Qt Quick component set} field, select
+        \uicontrol{Qt Quick Controls 1.2} > \uicontrol Next.
+    \li In the \uicontrol{Kit Selection} page, select \uicontrol Next.
+    \li In the \uicontrol{Summary} page, select \uicontrol Finish.
+\endlist
+
+The wizard creates the project and you can run it by clicking on the run button,
+\inlineimage{qtcreator/qtcreator-run.png}
+. The application is an empty shell but it contains the basic window and layout
+on which we can build. Make sure that you can run the basic application and if
+not, make sure that your build environment and Qt version are configured.
+
+\section2 Project Files
+
+The wizard creates the project files used to build the project. To view them,
+select the \uicontrol{Edit mode}. The following project files are modified
+later in the guide:
+
+\list
+\li \uicontrol TextEdit.pro - the project file used to create the build files.
+    Also sets the paths that are visible to the project.
+\li \uicontrol Sources - contains the C++ implementation files (\c{.cpp}).
+\li \uicontrol Resources - contains a resource file that configures the application
+    assets and how the application resolves the location of the assets. The QML
+    file is also found here.
+\li \uicontrol Headers - contains the C++ header files (\c{.h}). The default
+    project does not have any header files, therefore this is not visible.
+\endlist
+
+\section2 Resource Files
+
+The text editor uses several icons to represent various actions. The icons are
+in the \e images directory which is directly under the \e TextEditor project
+directory. The images as well as the project files are also listed in the
+reference documentation on the \l{Qt Quick Controls Text Editor Example} page.
+
+We first need to register the image files into the project's resource file,
+\e qml.qrc. The resource files compact the images into the binary packages.
+The resource files provide a streamlined directory structure, which is
+cross-platform. It is beneficial especially on mobile platforms, where each
+platform manages the application resources differently.
+
+\list
+\li To register the image files, in the \uicontrol Edit mode, right-click the
+    \e qml.qrc file and select \uicontrol{Open in Editor}.
+\li Click the \uicontrol Add button and select \uicontrol{Add Files}.
+\li In the file manager, select the files to be added. You can select
+    all the images in the \e images directory at once.
+\endlist
+
+You can refer to the images from QML by referring directly to the filename.
+For example, \c{images/editcopy.png} is the name of the \e editcopy.png file.
+We will use these images later in the guide.
+
+Qt Creator then packages the images alongside your application in a single
+binary. For more information about resource files, see the
+\l{Managing Resource Files with the Qt Resource System} and the
+\l{Qt Resource System} pages.
+
+\section1 Example Files
+
+The accompanying examples files are listed in the following page:
+\list
+\li \l{Qt Quick Controls Text Editor Example}
+\endlist
+
+*/
+
+/*!
+\page qtquickcontrols-texteditor-ui.html
+\title Qt Quick Text Editor Guide - UI
+\previouspage Qt Quick Text Editor Guide
+\nextpage Qt Quick Text Editor Guide - Logic
+\brief Walkthrough of an application built with Qt Quick Controls.
+
+Qt Quick Designer is integrated into Qt Creator, allowing you to switch between
+\uicontrol Edit and \uicontrol Design modes. To start using Qt Quick Designer,
+select the QML file, \e main.qml, and click the \uicontrol Design button on the
+left panel.
+
+It is important to familiarize yourself with the windows in Qt Quick Designer.
+This guide uses Qt Quick Designer to add and set up the layout.
+
+\image controlstexteditor/controlstexteditor_designer.png
+
+\note The default kit for the project must be a Desktop kit, as Qt Quick
+Designer cannot yet emulate the styles for a mobile platform.
+
+To start, we can customize the default application created by the wizard. You
+can delete the \uicontrol MainForm.ui.qml file and remove the following lines
+from the \uicontrol main.qml file:
+\qml
+    MainForm {
+        anchors.fill: parent
+        button1.onClicked: messageDialog.show(qsTr("Button 1 pressed"))
+        button2.onClicked: messageDialog.show(qsTr("Button 2 pressed"))
+        button3.onClicked: messageDialog.show(qsTr("Button 3 pressed"))
+    }
+
+    MessageDialog {
+        id: messageDialog
+        title: qsTr("May I have your attention, please?")
+
+        function show(caption) {
+            messageDialog.text = caption;
+            messageDialog.open();
+        }
+    }
+\endqml
+
+The default dimension of the \c ApplicationWindow may remain but
+you can change the \c title property to a relevant name such as:
+
+\qml
+title: qsTr("Text Editor Example")
+\endqml
+
+\note The example uses the \c qsTr() function to facilitate translation. For
+more information, visit the \l{Internationalization and Localization with Qt Quick}
+page.
+
+Make sure that \uicontrol Resources tab contains the images from the
+\l{Resource Files}{previous page}.
+
+\section1 Defining the Application Layout
+
+Our application has a simple layout, which consists of a \e{tool bar} and a
+\e{text area}. The tool bar contains the \e{tool buttons} that the user can
+choose to manipulate the text area contents. At the top, there are menus, which
+perform actions such as saving and opening files to edit.
+
+\section1 Adding the Controls
+
+To add a control, you have the following options:
+
+\list 1
+\li Drag and drop a control from the \uicontrol{QML Types} window onto the
+    main design window. This allows you to drop the control onto a specific
+    area of the layout.
+\li Drag and drop a control from the \uicontrol{QML Types} window onto the
+    \uicontrol Navigator window. This allows you to set the layout hierarchy.
+\endlist
+
+Both these actions give you several options to quickly set up the layout.
+Whichever method you use, designer gives you a more direct way of setting up a
+particular aspect of the control, such as the scene hierarchy or the position
+of the control.
+
+Afterwards, the various properties are set from within the
+\uicontrol Properties window on the right side of Qt Creator window.
+
+\section1 Setting Up the Tool Bar
+
+First, we need to add the tool bar. We can do this in the
+\e Edit mode and typing in a \l ToolBar type inside the ApplicationWindow type.
+This configures the ApplicationWindow object as the tool bar's parent.
+
+\badcode
+ApplicationWindow {
+
+    ToolBar {
+        id: toolBar
+    }
+}
+\endcode
+
+In the \uicontrol Design mode, the \uicontrol Properties window lets us set the
+tool bar \uicontrol id to \c toolbar.
+
+In the \uicontrol Navigator window, make sure that the tool bar is a child of the
+application window. To make the tool bar a child of the window, simply drag the tool bar
+underneath the application window.
+
+Within the tool bar, we need a \e{row} layout. Drag the \l{Row Layout} into the
+\uicontrol Navigator window and set it to be a child of the tool bar.
+
+Similarly, set these layout properties:
+\list
+\li \uicontrol id - set it to \c rowToolbar
+\li click on the fill area button to set the fill area to \e parent. The parent should
+    be the tool bar.
+\endlist
+
+\image controlstexteditor/controlstexteditor_rowproperties.png
+
+\section2 Adding the Tool Buttons
+
+\e{Tool buttons} exist within a tool bar and specifically use the layout within the tool bar.
+\e{Text Editor} has six tool buttons, each performing a specific action, such as
+\e copy and \e paste to and from the clipboard.
+
+The steps for adding the six tool buttons are mainly the same:
+\list
+\li Drag and drop the \uicontrol{Tool Button} type as a child of the row layout.
+\li The \uicontrol id should be set to a unique name that is related to the
+    tool button's action.
+    The parent is set to \uicontrol parent and set the \uicontrol margin to \c 0.
+
+    \image controlstexteditor/controlstexteditor_newproperties.png
+\li The first tool button, for example \uicontrol New, should have the left anchor
+    set to the row layout.
+\li The subsequent tool buttons should have the left anchor set to their previous
+    sibling and the \uicontrol margin to \c 0. These settings makes sure that
+    the tool buttons are adjacent to each other.
+\li Set the \uicontrol iconName and \uicontrol iconSource properties in the
+    \uicontrol ToolButton tab. The \uicontrol iconName should be set to a unique name
+    identifying the icon name while the \uicontrol iconSource property should
+    be set to the name of the icon for the tool button.
+\endlist
+
+For example, the \uicontrol New tool button has \c newIcon set as its \uicontrol iconName and
+\c images/filenew.png set to the \uicontrol iconSource property. The icons are also viewable in the
+\uicontrol Resources inside the \uicontrol Library window.
+
+Similarly for the \uicontrol Open tool button, the margins are set to \c 0
+but the left anchor is set to the \uicontrol New tool button.
+
+\image controlstexteditor/controlstexteditor_openproperties.png
+
+\note Dragging and dropping the images from the \uicontrol Resources onto
+the scene adds the image into the scene as an \l Image object, instead
+of setting the iconSource property.
+
+\section1 Setting Up the Text Area
+
+Next, add a \uicontrol{Text Area} onto the scene as a child of the application
+window and a sibling of \c toolBar. The tool bar should be above the text area.
+Similarly, set the following text area properties:
+
+\list
+\li \uicontrol id - set it to \c textArea
+\li set the left, right, and bottom margin to the parent and the top margin
+    to \c toolBar.bottom and set the margins to \c 0.
+    \qml
+    anchors.top: toolBar.bottom
+    anchors.right: parent.right
+    anchors.bottom: parent.bottom
+    anchors.left: parent.left
+    \endqml
+\endlist
+
+Verify that you have the parent, margins, and icons set up. Your
+\uicontrol Navigator should look similar to:
+
+\image controlstexteditor/controlstexteditor_navigator.png
+
+Running the application should result in this layout:
+\image controlstexteditor/controlstexteditor_main.png
+
+We are now ready to go back to \uicontrol Edit and set the handlers and
+actions. A QML \e handler is called when the buttons are pressed and
+triggers the necessary action associated with the tool buttons. An
+\e action collects various QML logic into one code block so it may be
+reused by several handlers. For more information, visit the \l Action
+QML type and \l{Signal and Handler Event System}.
+
+\section1 Example Files
+
+The accompanying examples files are found in the following page:
+\list
+\li \l{Qt Quick Controls Text Editor Example}
+\endlist
+
+*/
+
+/*!
+\page qtquickcontrols-texteditor-logic.html
+\title Qt Quick Text Editor Guide - Logic
+\previouspage Qt Quick Text Editor Guide - UI
+\nextpage qtquickcontrols-texteditor-action.html
+\brief Walkthrough of an application built with Qt Quick Controls.
+
+This part of the guide is about adding logic and backend to the
+text editor example. At this stage, the user interface is
+set up from the \l{Qt Quick Text Editor - Logic}{previous} stage.
+
+\section1 Implementing the Logic and C++ Backend
+
+\e{Text Editor} has a QML user interface and a C++ backend to
+implement the document handling. To connect QML and C++,
+we need to create \e actions associated to the tool buttons,
+which will call the document handling logic in C++.
+
+\section1 Creating the Document Handler
+
+The document handler implements the file loading and file
+saving logic with Qt's C++ APIs. First, we need to create the
+header file and the implementation file in Qt Creator's
+\uicontrol Edit mode.
+
+\list
+\li Right-click a folder, and select \uicontrol{Add New}.
+\li Follow the wizard and create a new \uicontrol{C++ Class}.
+\li Create a class called \uicontrol DocumentHandler and select
+\uicontrol{Inherits QObject} in the \uicontrol{Type information}.
+\li You can use default values for the rest and finish the wizard.
+\endlist
+
+The wizard creates a \uicontrol DocumentHandler class in two files,
+\e documenthandler.h and \e documenthandler.cpp.
+
+There are two functionalities we can expose to QML, the file loading and
+saving. We can do this by creating \e properties and binding them to C++
+functions through \l{Qt Property System}.
+
+In the \e documenthandler.h header file, add the following functions with their
+respective access modifier:
+
+\code
+    Q_PROPERTY(QUrl fileUrl READ fileUrl WRITE setFileUrl NOTIFY fileUrlChanged)
+    Q_PROPERTY(QString text READ text WRITE setText NOTIFY textChanged)
+    Q_PROPERTY(QString documentTitle READ documentTitle WRITE setDocumentTitle NOTIFY documentTitleChanged)
+
+public:
+    QUrl fileUrl() const;
+    QString text() const;
+    QString documentTitle() const;
+
+public slots:
+    void setFileUrl(const QUrl &arg);
+    void setText(const QString &arg);
+    void setDocumentTitle(QString arg);
+
+signals:
+    void fileUrlChanged();
+    void textChanged();
+    void documentTitleChanged();
+\endcode
+
+The lines with \c Q_PROPERTY() macro declares the \e property and its \e write
+and \e read methods as well as its \e notify signal. For example, setting the
+\c fileUrl property calls \c setFileUrl() and reading the property calls the
+\c fileUrl() function. Similarly, when the value of fileUrl changes the
+\c fileUrlChanged() function is called.
+
+Internally, the properties are represented by private member variables. For our
+needs, here are the three variables in \e documenthandler.h which correspond to the properties:
+\code
+private:
+    QUrl m_fileUrl;
+    QString m_text;
+    QString m_documentTitle;
+\endcode
+
+Implementing the read functions is straightforward. They simply return
+the private member variables. For example, the implementation of
+\c documentTitle() in \e documenthandler.cpp is:
+\code
+QString DocumentHandler::documentTitle() const
+{
+    return m_documentTitle;
+}
+\endcode
+
+Implementing the write (\c setText(), for example) functions is also straightforward as they simply
+assign a value to a private member variable. They also handle basic error handling
+and they emit their respective notify signals. For example, the \c setDocumentTitle() function
+is implemented in \e documenthandler.cpp as:
+
+\code
+void DocumentHandler::setDocumentTitle(QString arg)
+{
+    if (m_documentTitle != arg) {
+        m_documentTitle = arg;
+        emit documentTitleChanged();
+    }
+}
+\endcode
+
+The opening of the file is done in the \c setFileUrl() function:
+\code
+void DocumentHandler::setFileUrl(const QUrl &arg)
+{
+    if (m_fileUrl != arg) {
+        m_fileUrl = arg;
+        QString fileName = arg.fileName();
+        QFile file(arg.toLocalFile());
+        if (file.open(QFile::ReadOnly)) {
+            setText(QString(file.readAll()));
+            if (fileName.isEmpty())
+                m_documentTitle = QStringLiteral("untitled");
+            else
+                m_documentTitle = fileName;
+            emit textChanged();
+            emit documentTitleChanged();
+        }
+        emit fileUrlChanged();
+    }
+}
+\endcode
+
+Note how the function emits the notify signals with the \c emit keyword.
+
+Similarly, we use QFile and text streams to save files. The function signature in
+\e documenthandler.h is placed under \c{public slots} because that is one
+way to expose functions to the QML engine. \c saveFile() is called from the
+QML file during saving.
+\code
+public slots:
+
+    Q_INVOKABLE void saveFile(const QUrl &arg) const;
+\endcode
+
+The implementation of \c saveFile() is in documenthandler.cpp:
+\code
+void DocumentHandler::saveFile(const QUrl &arg) const
+{
+    QFile file(arg.toLocalFile());
+    if (file.open(QFile::WriteOnly | QFile::Truncate)) {
+        QTextStream out(&file);
+        out << text();
+    }
+}
+\endcode
+
+For information about reading files and data storage, visit the QFile
+and the \l{Data Storage} documentation.
+
+\section1 Registering the DocumentHandler Class
+
+We now need to let the QML engine know about the \c DocumentHandler and its
+type. The \c qmlRegisterType() function is called in the application's \c main()
+function in \e main.cpp:
+
+\code
+    qmlRegisterType<DocumentHandler>("org.qtproject.example", 1, 0, "DocumentHandler");
+\endcode
+
+The \c org.qtproject.example is the library with the version \c 1.0 and the
+QML type registered is \c DocumentHandler. The import statement for the
+DocumentHandler QML type is then
+\code
+import org.qtproject.example 1.0
+\endcode
+
+\note The \c qmlRegisterType() function should be called before the engine loads the QML file.
+
+\section1 Using the DocumentHandler QML type
+
+With the basic loading implemented, we can use the functionalities in the
+QML file by creating an instance of the DocumentHandler class and by accessing
+its properties.
+
+The \l{Qt Quick Text Editor - Connecting Actions}{next page} is about using
+these C++ functions in QML files.
+
+\section1 Example Files
+
+The accompanying examples files are found in the following page:
+\list
+\li \l{Qt Quick Controls Text Editor Example}
+\endlist
+
+*/
+
+/*!
+\page qtquickcontrols-texteditor-action.html
+\title Qt Quick Text Editor - Connecting Actions
+\previouspage Qt Quick Text Editor Guide - Logic
+
+Earlier in the \l{Qt Quick Text Editor Guide}, we created a \e main.qml file
+containing the description of our user interface in QML. The user interface
+contains tool buttons in a tool bar on top of a text area. Afterwards, we
+created a DocumentHandler class in C++ that will handle the file loading
+and saving.
+
+Now we shall use the DocumentHandler in the QML file through \e actions. There
+is an \l Action QML type that we can connect to the tool buttons which in turn
+calls the DocumentHandler functions.
+
+\section1 Importing the DocumentHandler QML Type
+
+With the \c qmlRegisterType() function, we declared that the DocumentHandler
+QML type is imported from the \c org.qtproject.example library.
+
+The following code is taken from the \e main.cpp file from the previous stage.
+\code
+    qmlRegisterType<DocumentHandler>("org.qtproject.example", 1, 0, "DocumentHandler");
+\endcode
+
+In the \e main.qml file, enter the following import statement:
+\qml
+import org.qtproject.example 1.0
+\endqml
+The DocumentHandler type is then available and we can create an object directly by adding it at
+the bottom of the application window.
+\qml
+    DocumentHandler {
+        id: document
+    }
+\endqml
+
+\section1 Assigning Actions
+
+As mentioned, the tool buttons are associated with an \e action, for example, the cut button
+is associated with the cut action. The cut action embodies the events that define the action,
+for example, the calling of the appropriate function in the text area.
+
+For our application, we have six actions, which may be placed inside the application window.
+
+\qml
+    Action {
+        id: cutaction
+        text: "Cut"
+        shortcut: "ctrl+x"
+        iconSource: "images/editcut.png"
+        iconName: "edit-cut"
+        onTriggered: textarea.cut()
+    }
+
+    Action {
+        id: copyaction
+        text: "Copy"
+        shortcut: "Ctrl+C"
+        iconSource: "images/editcopy.png"
+        iconName: "edit-copy"
+        onTriggered: textarea.copy()
+    }
+
+    Action {
+        id: pasteaction
+        text: "Paste"
+        shortcut: "ctrl+v"
+        iconSource: "qrc:images/editpaste.png"
+        iconName: "edit-paste"
+        onTriggered: textarea.paste()
+    }
+
+    Action {
+        id: fileopenaction
+        iconSource: "images/fileopen.png"
+        iconName: "document-open"
+        text: "Open"
+        onTriggered: fileDialog.open()
+    }
+\endqml
+
+These actions call the appropriate function and assign a specific icon and name to the
+action. To connect the \c cutaction to the cut tool button, add the following to the
+tool button
+
+\qml
+ToolButton {
+            id: cut_toolbutton
+            iconSource: "images/editcut.png"
+            iconName: "cut_icon"
+            anchors.left: save_toolbutton.right
+            action: cutaction;
+}
+\endqml
+
+For the open and save actions, we require that the user choose an existing file
+or create a new file. To do this, we can pop up a file dialog and ask the user
+to select the file to open from or save onto. We can create two file dialogs,
+one for opening a file and one for saving the file, each setting their own
+titles.
+
+\qml
+    FileDialog {
+        id: fileOpenDialog
+        title: "Please choose a file to open"
+        nameFilters: ["Text files (*.txt)"]
+        onAccepted: document.fileUrl = fileUrl
+    }
+
+    FileDialog {
+        id: fileSaveDialog
+        title: "Please enter the file to save"
+        nameFilters: ["Text files (*.txt)"]
+        selectExisting: false
+        onAccepted: document.saveFile(fileUrl)
+    }
+\endqml
+
+Setting the FileDialog's \c selectExisting property to \c false allows us to
+save new files.
+
+The \l FileDialog type is from the \l{Qt Quick Dialogs} and is imported with
+\qml
+import QtQuick.Dialogs 1.2
+\endqml
+
+\section1 Deploying TextEditor
+
+Deploying the TextEditor depends on the platform on which the application is run. The process is simple
+and Qt provides several tools for packaging applications for a given platform. The
+\l{Deploying Qt Applications} page lists the instructions for the supported platforms.
+For this guide, we will deploy on Windows desktop platform with the
+\c windeploytool to create a directory with the required dependent libraries.
+
+To package TextEditor,
+\list 1
+\li Copy the \e texteditor.exe file from the release directory to another directory which
+    serves as the destination folder.
+\li Run the \e windeployqt.exe file which resolves and copies the Qt libraries into
+    the destination folder. \e windeployqt.exe is found in the \e bin directory of the installation.
+    \code
+    C:\Qt\5.3\msvc2012_opengl\bin>windeployqt.exe <path to destination folder>
+    \endcode
+\endlist
+
+The destination folder can now be packaged and the binary file is executable. The images
+and QML file are already packaged into the binary file.
+
+\section1 Example Files
+
+The accompanying examples files are found in the following page:
+\list
+\li \l{Qt Quick Controls Text Editor Example}
+\endlist
+
+*/
diff --git a/examples/texteditor/documenthandler.cpp b/examples/texteditor/documenthandler.cpp
new file mode 100644
index 000000000..fd2aa2bac
--- /dev/null
+++ b/examples/texteditor/documenthandler.cpp
@@ -0,0 +1,123 @@
+/****************************************************************************
+**
+** Copyright (C) 2015 The Qt Company Ltd.
+** Contact: http://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of The Qt Company Ltd nor the names of its
+**     contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include "documenthandler.h"
+
+DocumentHandler::DocumentHandler(QObject *parent) :
+    QObject(parent)
+{
+}
+
+/*
+ * Returns the current file's URL.
+ */
+QUrl DocumentHandler::fileUrl() const
+{
+    return m_fileUrl;
+}
+
+/*
+ * Returns the currently opened document's content.
+ */
+QString DocumentHandler::text() const
+{
+    return m_text;
+}
+
+/*
+ * Returns the currently opened document's title.
+ */
+QString DocumentHandler::documentTitle() const
+{
+    return m_documentTitle;
+}
+
+/*
+ * Saves the current content with the given file URL.
+ */
+void DocumentHandler::saveFile(const QUrl &arg) const
+{
+    QFile file(arg.toLocalFile());
+    if (file.open(QFile::WriteOnly | QFile::Truncate)) {
+        QTextStream out(&file);
+        out << text();
+    }
+}
+
+/*
+ * Sets the file's URL. Called when a file is opened.
+ */
+void DocumentHandler::setFileUrl(const QUrl &arg)
+{
+    if (m_fileUrl != arg) {
+        m_fileUrl = arg;
+        QString fileName = arg.fileName();
+        QFile file(arg.toLocalFile());
+        if (file.open(QFile::ReadOnly)) {
+            setText(QString(file.readAll()));
+            if (fileName.isEmpty())
+                m_documentTitle = QStringLiteral("untitled");
+            else
+                m_documentTitle = fileName;
+            emit textChanged();
+            emit documentTitleChanged();
+        }
+        emit fileUrlChanged();
+    }
+}
+
+/*!
+ * Sets the currently opened document's content.
+ *
+ */
+void DocumentHandler::setText(const QString &arg)
+{
+    m_text = arg;
+    emit textChanged();
+}
+
+/*
+ *  Sets the currently opened document's title.
+ */
+void DocumentHandler::setDocumentTitle(QString arg)
+{
+    m_documentTitle = arg;
+    emit documentTitleChanged();
+}
diff --git a/examples/texteditor/documenthandler.h b/examples/texteditor/documenthandler.h
new file mode 100644
index 000000000..74c0992dc
--- /dev/null
+++ b/examples/texteditor/documenthandler.h
@@ -0,0 +1,87 @@
+/****************************************************************************
+**
+** Copyright (C) 2015 The Qt Company Ltd.
+** Contact: http://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of The Qt Company Ltd nor the names of its
+**     contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#ifndef DOCUMENTHANDLER_H
+#define DOCUMENTHANDLER_H
+
+#include <QObject>
+#include <QUrl>
+#include <QString>
+#include <QQuickTextDocument>
+
+#include <QtGui/QTextCharFormat>
+#include <QtCore/QTextCodec>
+
+#include <qqmlfile.h>
+
+class DocumentHandler : public QObject
+{
+    Q_OBJECT
+public:
+    explicit DocumentHandler(QObject *parent = 0);
+
+    Q_PROPERTY(QUrl fileUrl READ fileUrl WRITE setFileUrl NOTIFY fileUrlChanged)
+    Q_PROPERTY(QString text READ text WRITE setText NOTIFY textChanged)
+    Q_PROPERTY(QString documentTitle READ documentTitle WRITE setDocumentTitle NOTIFY documentTitleChanged)
+
+public:
+    QUrl fileUrl() const;
+    QString text() const;
+    QString documentTitle() const;
+
+public Q_SLOTS:
+    void setFileUrl(const QUrl &arg);
+    void setText(const QString &arg);
+    void setDocumentTitle(QString arg);
+
+    void saveFile(const QUrl &arg) const;
+
+Q_SIGNALS:
+    void fileUrlChanged();
+    void textChanged();
+    void documentTitleChanged();
+
+private:
+    QUrl m_fileUrl;
+    QString m_text;
+    QString m_documentTitle;
+};
+
+#endif // DOCUMENTHANDLER_H
diff --git a/examples/texteditor/images/editcopy.png b/examples/texteditor/images/editcopy.png
new file mode 100644
index 000000000..f55136446
--- /dev/null
+++ b/examples/texteditor/images/editcopy.png
diff --git a/examples/texteditor/images/editcut.png b/examples/texteditor/images/editcut.png
new file mode 100644
index 000000000..a784fd570
--- /dev/null
+++ b/examples/texteditor/images/editcut.png
diff --git a/examples/texteditor/images/editpaste.png b/examples/texteditor/images/editpaste.png
new file mode 100644
index 000000000..64c0b2d6a
--- /dev/null
+++ b/examples/texteditor/images/editpaste.png
diff --git a/examples/texteditor/images/filenew.png b/examples/texteditor/images/filenew.png
new file mode 100644
index 000000000..d3882c7b3
--- /dev/null
+++ b/examples/texteditor/images/filenew.png
diff --git a/examples/texteditor/images/fileopen.png b/examples/texteditor/images/fileopen.png
new file mode 100644
index 000000000..fc06c5ec6
--- /dev/null
+++ b/examples/texteditor/images/fileopen.png
diff --git a/examples/texteditor/images/filesave.png b/examples/texteditor/images/filesave.png
new file mode 100644
index 000000000..b41ecf531
--- /dev/null
+++ b/examples/texteditor/images/filesave.png
diff --git a/examples/texteditor/images/qt-logo.png b/examples/texteditor/images/qt-logo.png
new file mode 100644
index 000000000..6dedc8bf0
--- /dev/null
+++ b/examples/texteditor/images/qt-logo.png
diff --git a/examples/texteditor/main.cpp b/examples/texteditor/main.cpp
new file mode 100644
index 000000000..4083e185e
--- /dev/null
+++ b/examples/texteditor/main.cpp
@@ -0,0 +1,58 @@
+/****************************************************************************
+**
+** Copyright (C) 2015 The Qt Company Ltd.
+** Contact: http://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of The Qt Company Ltd nor the names of its
+**     contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include <QApplication>
+#include <QQmlApplicationEngine>
+#include "documenthandler.h"
+#include <QQmlEngine>
+
+
+int main(int argc, char *argv[])
+{
+    QApplication app(argc, argv);
+
+    QQmlApplicationEngine engine;
+
+    //register the DocumentHandler QML type from the org.qtproject.example namespace
+    qmlRegisterType<DocumentHandler>("org.qtproject.example", 1, 0, "DocumentHandler");
+    engine.load(QUrl(QStringLiteral("qrc:/main.qml")));
+
+    return app.exec();
+}
diff --git a/examples/texteditor/main.qml b/examples/texteditor/main.qml
new file mode 100644
index 000000000..085e4c7d7
--- /dev/null
+++ b/examples/texteditor/main.qml
@@ -0,0 +1,203 @@
+/****************************************************************************
+**
+** Copyright (C) 2015 The Qt Company Ltd.
+** Contact: http://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of The Qt Company Ltd nor the names of its
+**     contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//QML import statements
+import QtQuick 2.3
+import QtQuick.Controls 1.2
+import QtQuick.Window 2.1
+import QtQuick.Layouts 1.0
+import org.qtproject.example 1.0
+import QtQuick.Dialogs 1.2
+
+//main window
+ApplicationWindow {
+    id: applicationWindow1
+    visible: true
+    width: 640
+    height: 480
+    title: qsTr(document.documentTitle + " Text Editor Example")
+
+    menuBar: MenuBar {
+        Menu {
+            title: qsTr("File")
+            MenuItem {
+                text: qsTr("&Open")
+                action: fileOpenAction
+            }
+            MenuItem {
+                text: qsTr("&Save")
+                action: fileSaveAction
+            }
+            MenuItem {
+                text: qsTr("Exit")
+                onTriggered: Qt.quit();
+            }
+        }
+    }
+    toolBar: ToolBar {
+        id: toolBar
+
+        RowLayout {
+            id: rowToolBar
+            spacing: 0.3
+
+            ToolButton {
+                id: newToolButton
+                anchors.left: parent.left
+                iconName: "new_icon"
+                iconSource: "images/filenew.png"
+                action: newAction
+            }
+
+            ToolButton {
+                id: openToolButton
+                anchors.left: newToolButton.right
+                transformOrigin: Item.Center
+                iconSource: "images/fileopen.png"
+                iconName: "open_icon"
+                action: fileOpenAction
+            }
+
+            ToolButton {
+                id: saveToolButton
+                text: qsTr("")
+                iconSource: "images/filesave.png"
+                iconName: "save_icon"
+                isDefault: false
+                visible: true
+                checkable: false
+                anchors.left: openToolButton.right
+                action: fileSaveAction
+            }
+
+            ToolButton {
+                id: cutToolButton
+                iconSource: "images/editcut.png"
+                iconName: "cut_icon"
+                anchors.left: saveToolButton.right
+                action: cutAction;
+            }
+
+            ToolButton {
+                id: copyToolButton
+                iconSource: "images/editcopy.png"
+                iconName: "copy_icon"
+                anchors.left: cutToolButton.right
+                action: copyAction
+            }
+
+            ToolButton {
+                id: pasteToolbutton
+                iconSource: "images/editpaste.png"
+                iconName: "paste_icon"
+                anchors.left: copyToolButton.right
+                action: pasteAction
+            }
+        }
+    }
+
+    TextArea {
+        id: textArea
+        text: document.text
+        anchors.fill: parent
+    }
+
+    DocumentHandler {
+        id: document
+    }
+
+    Action {
+        id: newAction
+        text: "New"
+        shortcut: StandardKey.New
+        onTriggered: textArea.text = qsTr("")
+    }
+
+    Action {
+        id: cutAction
+        text: "Cut"
+        shortcut: StandardKey.Cut
+        onTriggered: textArea.cut()
+    }
+
+    Action {
+        id: copyAction
+        text: "Copy"
+        shortcut: StandardKey.Copy
+        onTriggered: textArea.copy()
+    }
+
+    Action {
+        id: pasteAction
+        text: "Paste"
+        shortcut: StandardKey.Paste
+        onTriggered: textArea.paste()
+    }
+
+    Action {
+        id: fileOpenAction
+        text: "Open"
+        shortcut: StandardKey.Open
+        onTriggered: fileOpenDialog.open()
+    }
+
+    Action {
+        id: fileSaveAction
+        text: "Open"
+        shortcut: StandardKey.Save
+        onTriggered: fileSaveDialog.open()
+    }
+
+    FileDialog {
+        id: fileOpenDialog
+        title: "Please choose a file to open"
+        nameFilters: ["Text files (*.txt)"]
+        onAccepted: document.fileUrl = fileUrl
+    }
+
+    FileDialog {
+        id: fileSaveDialog
+        title: "Please enter the file to save"
+        nameFilters: ["Text files (*.txt)"]
+        selectExisting: false
+        onAccepted: document.saveFile(fileUrl)
+    }
+
+}
diff --git a/examples/texteditor/qml.qrc b/examples/texteditor/qml.qrc
new file mode 100644
index 000000000..455b940de
--- /dev/null
+++ b/examples/texteditor/qml.qrc
@@ -0,0 +1,12 @@
+<RCC>
+    <qresource prefix="/">
+        <file>main.qml</file>
+        <file>images/editcopy.png</file>
+        <file>images/editcut.png</file>
+        <file>images/editpaste.png</file>
+        <file>images/filenew.png</file>
+        <file>images/fileopen.png</file>
+        <file>images/filesave.png</file>
+        <file>images/qt-logo.png</file>
+    </qresource>
+</RCC>
diff --git a/examples/texteditor/texteditor.pro b/examples/texteditor/texteditor.pro
new file mode 100644
index 000000000..f0a2e4aa9
--- /dev/null
+++ b/examples/texteditor/texteditor.pro
@@ -0,0 +1,17 @@
+TEMPLATE = app
+
+QT += qml quick widgets
+
+SOURCES += main.cpp \
+    documenthandler.cpp
+
+RESOURCES += qml.qrc
+
+# Additional import path used to resolve QML modules in Qt Creator's code model
+QML_IMPORT_PATH =
+
+# Default rules for deployment.
+include(deployment.pri)
+
+HEADERS += \
+    documenthandler.h