/****************************************************************************
**
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://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 https://www.qt.io/terms-conditions. For further
** information use the contact form at https://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: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\group qtquickcontrols_examples
\ingroup all-examples
\title Qt Quick Controls 1 Examples
\brief A Collection of examples for \l{Qt Quick Controls 1}, written in QML.
\deprecationwarning
These examples show how to create user interfaces using
\l{Qt Quick Controls 1}.
*/
/*!
\example gallery
\title Qt Quick Controls 1 - Gallery
\ingroup qtquickcontrols_examples
\brief A collection of components for a classic desktop-style UI.
\deprecationwarning
\raw HTML
\endraw
\image qtquickcontrols-example-gallery-osx.png
\caption \macos
\raw HTML
|
\endraw
\image qtquickcontrols-example-gallery-android.png
\caption Android - Nexus 5
\raw HTML
|
\endraw
This example project demonstrates the various UI components provided by
\l{Qt Quick Controls 1}.
\include examples-run.qdocinc
*/
/*!
\example uiforms
\title Qt Quick Controls 1 - UI Forms
\ingroup qtquickcontrols_examples
\brief Demonstrates how to separate the application logic from the UI.
\deprecationwarning
\image qtquickcontrols-example-uiforms.png
\e{UI Forms} demonstrates how to separate the application logic
from the UI using \e ui.qml files. The example is a simple interface to a customer
database, purely written in QML and JavaScript.
UI Forms are rigorously split into \e .qml and \e .js files that contain the business logic, and \e .ui.qml
files that only contain the purely declarative description of the UI.
The \e .ui.qml files act as forms and they should be only edited in the Design mode of Qt Creator.
\section1 Exporting Items from Forms
In all forms, items that are supposed to interact with the application logic are exported:
\code
property alias cancel: cancel
property alias save: save
property alias textArea: textArea
\endcode
This is the way the items are exported in \e NotesForm.ui.qml, so they can be used in
\e Notes.ui.qml to implement the logic as follows:
\code
function readData() {
CustomerModel.selection.forEach(function (rowIndex) {
form.textArea.text = CustomerModel.model.get(rowIndex).notes
})
save.enabled = true
cancel.enabled = true
form.textArea.enabled = true
}
function writeData() {
CustomerModel.selection.forEach(function (rowIndex) {
var data = CustomerModel.model.get(rowIndex)
data.notes = form.textArea.text
CustomerModel.model.set(rowIndex, data)
})
}
cancel.onClicked: readData()
save.onClicked: writeData()
\endcode
\section1 Implementing the Backend in a Singleton
Because the ListModel is accessed from several different \e .qml files, we access the
ListModel through a singleton defined in \e CustomerModel.qml and registered in \e main.ccp.
This way we do not have to rely on the QML context scoping rules to access the ListModel.
\include examples-run.qdocinc
*/
/*!
\example tableview
\title Qt Quick Controls 1 - Table View Example
\ingroup qtquickcontrols_examples
\brief An example for the TableView control.
\deprecationwarning
\image qtquickcontrols-example-tableview.png
This example project demonstrates the usage of \l {TableView} from
\l{Qt Quick Controls 1} - a control to display one or more columns of
information from a data list model. The example includes a model
that supports sorting and filtering.
The C++ class, SortFilterProxyModel, is registered as a QML type
under the namespace, "\c{org.qtproject.example 1.0}".
The following snippets show how the type is registered under
a namespace and later imported by \e main.qml.
QML type registration:
\code
#include
...
qmlRegisterType("org.qtproject.example", 1, 0, "SortFilterProxyModel");
...
\endcode
QML namespace import:
\code
import org.qtproject.example 1.0
\endcode
For more information about registering C++ classes as QML types, see
\l {Defining QML Types from C++}.
\include examples-run.qdocinc
*/
/*!
\example texteditor
\title Qt Quick Controls 1 - Text Editor Example
\ingroup qtquickcontrols_examples
\brief A QML app using Qt Quick Controls and a C++ class to
provide a fully-functional rich-text editor application.
\deprecationwarning
\image qtquickcontrols-example-text.png
The \e{Text Editor Example} presents a sample HTML file using the TextArea
control, preserving the HTML formatting. It uses a C++ class to handle the
document by providing options to open, format, and edit. The app also lets
you open and edit a plain text files.
The C++ class, DocumentHandler, extends QObject and is registered
as a QML type under the namespace, "\c{org.qtproject.example 1.0}".
The following snippets show how the type is registered under
a namespace and later imported by \e main.qml.
QML type registration:
\code
#include
...
qmlRegisterType("org.qtproject.example", 1, 0, "DocumentHandler");
...
\endcode
QML namespace import:
\code
import org.qtproject.example 1.0
\endcode
For more information about registering C++ classes as QML types, see
\l {Defining QML Types from C++}.
\include examples-run.qdocinc
*/
/*!
\example touch
\title Qt Quick Controls 1 - Touch Gallery
\ingroup qtquickcontrols_examples
\brief Demonstrates UI controls for a touch interface.
\deprecationwarning
\image qtquickcontrols-example-touch.png
\e {Touch Gallery} demonstrates how to implement a UI suitable for touch
input using the following \l{Qt Quick Controls 1}:
\list
\li \l ApplicationWindow
\li \l Button
\li \l ProgressBar
\li \l ScrollView
\li \l Slider
\li \l StackView
\li \l Switch
\li \l Tab
\li \l TabView
\li \l TextField
\endlist
The appearance of the controls is customized by using
\l {Qt Quick Controls 1 Styles}.
\include examples-run.qdocinc
\section1 Creating the Main Page
In the main.qml file, we use a \l Rectangle type within the
\l ApplicationWindow type to create the main page of the application:
\quotefromfile touch/main.qml
\skipto ApplicationWindow
\printuntil }
To use the Qt Quick Controls, we must import them:
\code
import QtQuick.Controls 1.2
\endcode
The \c toolBar property of the application window holds a BorderImage type
that we use to create a separator between the application name and a list of
additional pages:
\quotefromfile touch/main.qml
\skipto toolBar
\printuntil height
We use an \l Image type in a \l Rectangle type to create a back button. We
use the \c onClicked signal handler to call the StackView \c pop() function
that pops off the page when users tap the button:
\printuntil pop()
\printuntil }
\printuntil }
We use the \c opacity property to hide the back button on the main page.
We use a \l Text type to display the application name:
\printuntil text:
\printuntil }
The \c x position of the \l Text type is bound to the position and width of
the back button, and animated using a \l Behavior.
We use a ListModel type that contains ListElement definitions to define
titles and source files for the other pages in the application:
\skipto ListModel
\printuntil ListPage
\printuntil }
\printuntil }
\section1 Navigating in the Application
We implement a stack-based navigation model to link the application pages
together. Items are pushed onto the stack as users navigate deeper into the
application, and popped off again when they return to the main page.
In main.qml, we add a \l StackView type as a child of the application
window:
\skipto StackView
\printuntil }
The stack is used by invoking its navigation methods. To load the first item
in the stack view, we assign it to \c initialItem:
\printuntil /^\}/
We use a ListView type to display a list of the items provided by
\c pageModel. The \c AndroidDelegate custom type defines each item
instantiated by the view.
\section1 Creating Push Buttons and Switches
In ButtonPage.qml we use the \l Button type to create two buttons that
change color when users tap them and one that pops off the page and returns
the user to the main page:
\quotefromfile touch/content/ButtonPage.qml
\skipto Button
\printuntil stackView
\printuntil }
We use a \l Switch type to create two switches that users can turn on and
off. They are placed within a \l Row type to lay them out horizontally:
\printuntil switchStyle
\printuntil switchStyle
\printuntil }
\printuntil }
A \l ButtonStyle type creates a custom appearance for the buttons:
\skipto Component
\printuntil }
To use Qt Quick Controls Styles, we must import them:
\code
import QtQuick.Controls.Styles 1.1
\endcode
A \l SwitchStyle type creates a custom appearance for the switches:
\quotefromfile touch/content/ButtonPage.qml
\skipuntil Component
\skipto Component
\printuntil /^\}/
The \c groove property holds the background groove of the switch and the
\c handle property defines the switch handle.
\section1 Creating Sliders
In SliderPage.qml, we use a \l Slider type to create three horizontal
sliders that are placed within a \l Column type to lay them out in a column:
\quotefromfile touch/content/SliderPage.qml
\skipto Column
\printuntil 1.0
\printuntil }
\printuntil }
The \c value property holds the initial handle position on the slider.
A SliderStyle type creates a custom appearance for the sliders:
\printuntil /^\}/
The \c handle property defines the slider handle and the \c groove property
holds the background groove of the slider.
\section1 Indicating Progress
In ProgressBar.qml, we use a ProgressBar type to create three progress bars:
\quotefromfile touch/content/ProgressBarPage.qml
\skipto Column
\printuntil 1
\printuntil 400
\printuntil }
We use a NumberAnimation type with a SequentialAnimation type to run two
number animations in a sequence. We apply the animations on the \c progress
custom property to animate the current value on the progress bars:
\quotefromfile touch/content/ProgressBarPage.qml
\skipto progress
\printuntil }
\printuntil }
A ProgressBarStyle type creates a custom appearance for the progress bars:
\quotefromfile touch/content/ProgressBarPage.qml
\skipto Component
\printuntil /^\}/
\section1 Creating Tabs
In TabBarPage.qml, we use a TabView type with a \l Tab type to provide a
tab-based navigation model for our application. We use tabs to display the
ButtonPage, SliderPage, and ProgressBarPage on separate tab pages:
\quotefromfile touch/content/TabBarPage.qml
\skipto TabView
\printuntil ProgressBarPage
\printuntil }
A TabViewStyle type creates a custom appearance for the tabs:
\skipto Component
\printuntil /^\}/
\section1 Creating Text Input Fields
In the TextInputPage.qml, we use a TextField type to create an input field
and a read-only text field:
\quotefromfile touch/content/TextInputPage.qml
\skipto Column
\printuntil true
\printuntil }
\printuntil }
A TextFieldStyle creates a custom appearance for the text fields:
\printuntil /^\}/
We use a BorderImage type with an image to create borders for the fields.
\section1 Creating Scrolling Lists
In ListPage.qml, we use a ScrollView type to provide a scrolling page with a
vertical scoll bar:
\quotefromfile touch/content/ListPage.qml
\skipto ScrollView
\printuntil true
We use a ListView type to display a list of 100 items by specifying an
\l{Models and Views in Qt Quick#Integers as Models}{integer} as the value of
the \c model property. We reuse the \c AndroidDelegate custom type here to
define each item instantiated by the view. The \c text property adds the
string \c {Item #} to each list item:
\printuntil }
\printuntil }
A ScrollViewStyle type creates a custom appearance for the scroll view:
\printuntil /^\}/
The \c transientScrollBars property is set to \c true to make the scroll
bars appear when the content is scrolled and disappear when they are no
longer needed.
The \c handle property controls the appearance of the scroll bar handle and
the \c scrollBarBackground property that of the background.
*/
/*!
\example calendar
\title Qt Quick Controls 1 - Calendar Example
\ingroup qtquickcontrols_examples
\brief Demonstrates the use of Calendar control.
\deprecationwarning
\image qtquickcontrols-example-calendar.png
The Calendar example displays a Calendar control and an events list for
the selected date. It uses a C++ class to fetch the event details from an
SQLite database. The example app uses a custom CalendarStyle to highlight
the selected date and mark the dates that have events.
The following snippet from \e main.qml shows how the Calendar control is
used in the app:
\code
Calendar {
id: calendar
width: (parent.width > parent.height ? parent.width * 0.6 - parent.spacing : parent.width)
height: (parent.height > parent.width ? parent.height * 0.6 - parent.spacing : parent.height)
frameVisible: true
weekNumbersVisible: true
selectedDate: new Date(2014, 0, 1)
focus: true
style: CalendarStyle {
dayDelegate: Item {
...
}
}
}
\endcode
The C++ class, SqlEventModel, inherits SqlQueryModel to create a database
with dummy events for certain dates.
\quotefromfile calendar/src/sqleventmodel.cpp
\skipto SqlEventModel::SqlEventModel()
\printto QList
\skipto void SqlEventModel
\printuntil /^\}/
In \e main.qml, the SqlEventModel custom type is used to get the list of
events to mark the dates on the calendar.
\code
SqlEventModel {
id: eventModel
}
Calendar {
...
style: CalendarStyle {
dayDelegate: Item {
...
Image {
visible: eventModel.eventsForDate(styleData.date).length > 0
...
source: "qrc:/images/eventindicator.png"
}
}
}
}
\endcode
The app uses a Flow type to position the items, and manipulates the
items' width and height based on the orientation change on mobile devices.
\code
Calendar {
id: calendar
width: (parent.width > parent.height ? parent.width * 0.6 - parent.spacing : parent.width)
height: (parent.height > parent.width ? parent.height * 0.6 - parent.spacing : parent.height)
}
Rectangle {
width: (parent.width > parent.height ? parent.width * 0.4 - parent.spacing : parent.width)
height: (parent.height > parent.width ? parent.height * 0.4 - parent.spacing : parent.height)
border.color: Qt.darker(color, 1.2)
ListView {
...
}
}
\endcode
\include examples-run.qdocinc
*/
/*!
\example styles
\title Qt Quick Controls 1 - Styles Example
\ingroup qtquickcontrols_examples
\brief Demonstrates custom styles.
\deprecationwarning
\image qtquickcontrols-example-styles.png
This example shows how to create custom styles for \l{Qt Quick Controls 1}.
\include examples-run.qdocinc
*/
/*!
\example filesystembrowser
\title Qt Quick Controls 1 - File System Browser Example
\ingroup qtquickcontrols_examples
\brief An example for the TreeView control.
\deprecationwarning
\image qtquickcontrols-example-filesystembrowser.png
This example project demonstrates the usage of \l {TreeView} from
\l{Qt Quick Controls 1} - a control to display a tree representation of items
from a model derived from the QAbstractItemModel class.
The example displays the home path data given by the QFileSystemModel model.
*/