Commit 910eb9b4 authored by Leena Miettinen's avatar Leena Miettinen
Browse files

Doc: move info about Qt Designer and Qt widgets to a separate folder

Change-Id: I92efa66d0dc1f8ed35e16f7f8b5293806355a400
Reviewed-on: http://codereview.qt-project.org/5614

Reviewed-by: default avatarQt Sanity Bot <qt_sanity_bot@ovi.com>
Reviewed-by: default avatarEike Ziller <eike.ziller@nokia.com>
Reviewed-by: default avatarCasper van Donderen <casper.vandonderen@nokia.com>
parent c9f0988e
\section1 Qt Designer Integration Questions
\bold {Why are custom widgets not loaded in Design mode even though it
works in standalone Qt Designer?}
Qt Designer fetches plugins from standard locations and loads the plugins
that match its build key. The locations are different for standalone and
integrated Qt Designer.
For more information, see \l{Adding Qt Designer Plugins}.
/****************************************************************************
**
** This file is part of Qt Creator
**
** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies).
**
** Contact: Nokia Corporation (info@qt.nokia.com)
**
**
** 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 info@qt.nokia.com.
**
****************************************************************************/
// **********************************************************************
// NOTE: the sections are not ordered by their logical order to avoid
// reshuffling the file each time the index order changes (i.e., often).
// Run the fixnavi.pl script to adjust the links to the index order.
// **********************************************************************
/*!
\contentspage index.html
\previouspage creator-qml-components-example.html
\page creator-writing-program.html
\nextpage creator-mobile-example.html
\title Creating a Qt Widget Based Application
This tutorial describes how to use \QC to create a small Qt application,
Text Finder. It is a simplified version of the QtUiTools
\l{http://doc.qt.nokia.com/4.7/uitools-textfinder.html}{Text Finder}
example. The application user interface is constructed from Qt widgets by
using \QD. The application logic is written in C++ by using the code editor.
\image qtcreator-textfinder-screenshot.png
\section1 Creating the Text Finder Project
\note Create the project with two instances of \QC open and the \gui{Help}
mode active in one of them so that you can follow these instructions while
you work.
\list 1
\o Select \gui{File > New File or Project > Qt Widget Project > Qt Gui
Application > Choose}.
\image qtcreator-new-qt-gui-application.png "New File or Project dialog"
The \gui{Introduction and Project Location} dialog opens.
\image qtcreator-intro-and-location-qt-gui.png "Introduction and Project Location dialog"
\o In the \gui{Name} field, type \bold {TextFinder}.
\o In the \gui {Create in} field, enter the path for the project files.
For example, \c {C:\Qt\examples}, and then click \gui{Next}.
The \gui {Target Setup} dialog opens.
\image qtcreator-new-project-qt-versions-qt-gui.png "Target Setup dialog"
\o Select the Qt versions to use as build targets for your project,
and click \gui{Next}.
\note If you have only one Qt version installed, this dialog is
skipped.
The \gui{Class Information} dialog opens.
\image qtcreator-class-info-qt-gui.png "Class Information dialog"
\o In the \gui{Class name} field, type \bold {TextFinder} as the class
name.
\o In the \gui{Base class} list, select \bold {QWidget} as the base
class type.
\note The \gui{Header file}, \gui{Source file} and \gui{Form file}
fields are automatically updated to match the name of the class.
\o Click \gui{Next}.
The \gui{Project Management} dialog opens.
\image qtcreator-new-project-summary-qt-gui.png "Project Management dialog"
\o Review the project settings, and click \gui{Finish} to create the
project.
\endlist
The TextFinder project now contains the following files:
\list
\o textfinder.h
\o textfinder.cpp
\o main.cpp
\o textfinder.ui
\o textfinder.pro
\endlist
\image qtcreator-textfinder-contents.png "TextFinder project contents"
The .h and .cpp files come with the necessary boiler plate code.
The .pro file is complete.
\section1 Filling in the Missing Pieces
Begin by designing the user interface and then move on to filling
in the missing code. Finally, add the find functionality.
\section2 Designing the User Interface
\image qtcreator-textfinder-ui.png "Text Finder UI"
\list 1
\o In the \gui{Editor} mode, double-click the textfinder.ui file in the
\gui{Projects} view to launch the integrated \QD.
\o Drag and drop the following widgets to the form:
\list
\o \gui{Label} (QLabel)
\o \gui{Line Edit} (QLineEdit)
\o \gui{Push Button} (QPushButton)
\endlist
\image qtcreator-textfinder-ui-widgets.png "Adding widgets to Text Finder UI"
\note To easily locate the widgets, use the search box at the top of the
\gui Sidebar. For example, to find the \gui Label widget, start typing
the word \bold label.
\image qtcreator-texfinder-filter.png "Filter field"
\o Double-click the \gui{Label} widget and enter the text
\bold{Keyword}.
\o Double-click the \gui{Push Button} widget and enter the text
\bold{Find}.
\o In the \gui Properties pane, change the \gui objectName to
\bold findButton.
\image qtcreator-textfinder-objectname.png "Changing object names"
\o Press \key {Ctrl+A} to select the widgets and click
\gui{Lay out Horizontally} (or press \gui{Ctrl+H}) to apply a
horizontal layout (QHBoxLayout).
\image qtcreator-texfinder-ui-horizontal-layout.png "Applying horizontal layout"
\o Drag and drop a \gui{Text Edit} widget (QTextEdit) to the form.
\o Select the screen area and click \gui{Lay out Vertically} (or press
\gui{Ctrl+L}) to apply a vertical layout (QVBoxLayout).
\image qtcreator-textfinder-ui.png "Text Finder UI"
Applying the horizontal and vertical layouts ensures that the
application UI scales to different screen sizes.
\o To call a find function when users press the \gui Find button, you
use the Qt signals and slots mechanism. A signal is emitted when a
particular event occurs and a slot is a function that is called in
response to a particular signal. Qt widgets have predefined signals
and slots that you can use directly from \QD. To add a slot for the
find function:
\list
\o Right-click the \gui Find button to open a context-menu.
\o Select \gui {Go to Slot > clicked()}, and then select
\gui OK.
A private slot, \c{on_findButton_clicked()}, is added to the
header file, textfinder.h and a private function,
\c{TextFinder::on_findButton_clicked()}, is added to the
source file, textfinder.cpp.
\endlist
\o Press \gui{Ctrl+S} to save your changes.
\endlist
For more information about designing forms with \QD, see the
\l{http://doc.qt.nokia.com/4.7/designer-manual.html}{Qt Designer Manual}.
\section2 Completing the Header File
The textfinder.h file already has the necessary #includes, a constructor,
a destructor, and the \c{Ui} object. You need to add a private function,
\c{loadTextFile()}, to read and display the contents of the input text file
in the QTextEdit.
\list 1
\o In the \gui{Projects} pane in the \gui {Edit view}, double-click the
\c{textfinder.h} file to open it for editing.
\o Add a private function to the \c{private} section, after the
\c{Ui::TextFinder} pointer, as illustrated by the following code
snippet:
\snippet examples/textfinder/textfinder.h 0
\endlist
\section2 Completing the Source File
Now that the header file is complete, move on to the source file,
textfinder.cpp.
\list 1
\o In the \gui{Projects} pane in the \gui Edit view, double-click the
textfinder.cpp file to open it for editing.
\o Add code to load a text file using QFile, read it with QTextStream,
and then display it on \c{textEdit} with
\l{http://doc.qt.nokia.com/4.7/qtextedit.html#plainText-prop}
{setPlainText()}.
This is illustrated by the following code snippet:
\snippet examples/textfinder/textfinder.cpp 0
\o To use QFile and QTextStream, add the following #includes to
textfinder.cpp:
\snippet examples/textfinder/textfinder.cpp 1
\o For the \c{on_findButton_clicked()} slot, add code to extract the
search string and use the
\l{http://doc.qt.nokia.com/4.7/qtextedit.html#find}{find()} function
to look for the search string within the text file. This is
illustrated by the following code snippet:
\snippet examples/textfinder/textfinder.cpp 2
\o Once both of these functions are complete, add a line to call
\c{loadTextFile()} in the constructor, as illustrated by the
following code snippet:
\snippet examples/textfinder/textfinder.cpp 3
\endlist
The \c{on_findButton_clicked()} slot is called automatically in
the uic generated ui_textfinder.h file by this line of code:
\code
QMetaObject::connectSlotsByName(TextFinder);
\endcode
\section2 Creating a Resource File
You need a resource file (.qrc) within which you embed the input
text file. The input file can be any .txt file with a paragraph of text.
Create a text file called input.txt and store it in the textfinder
folder.
To add a resource file:
\list 1
\o Select \gui{File > New File or Project > Qt > Qt Resource File >
Choose}.
\image qtcreator-add-resource-wizard.png "New File or Project dialog"
The \gui {Choose the Location} dialog opens.
\image qtcreator-add-resource-wizard2.png "Choose the Location dialog"
\o In the \gui{Name} field, enter \bold{textfinder}.
\o In the \gui{Path} field, enter \c{C:\Qt\examples\TextFinder},
and click \gui{Next}.
The \gui{Project Management} dialog opens.
\image qtcreator-add-resource-wizard3.png "Project Management dialog"
\o In the \gui{Add to project} field, select \bold{TextFinder.pro}
and click \gui{Finish} to open the file in the code editor.
\o Select \gui{Add > Add Prefix}.
\o In the \gui{Prefix} field, replace the default prefix with a slash
(/).
\o Select \gui{Add > Add Files}, to locate and add input.txt.
\image qtcreator-add-resource.png "Editing resource files"
\endlist
\section1 Compiling and Running Your Program
Now that you have all the necessary files, click the
\inlineimage qtcreator-run.png
button to compile and run your program.
*/
/****************************************************************************
**
** This file is part of Qt Creator
**
** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies).
**
** Contact: Nokia Corporation (info@qt.nokia.com)
**
**
** 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 info@qt.nokia.com.
**
****************************************************************************/
// **********************************************************************
// NOTE: the sections are not ordered by their logical order to avoid
// reshuffling the file each time the index order changes (i.e., often).
// Run the fixnavi.pl script to adjust the links to the index order.
// **********************************************************************
/*!
\contentspage index.html
\previouspage creator-writing-program.html
\page creator-mobile-example.html
\nextpage creator-project-managing.html
\title Creating a Qt Widget Based Mobile Application
\note To complete this tutorial, you must install \QSDK.
The installation program installs and configures the necessary tool chains
for mobile application development.
This tutorial describes how to use \QC to create a small Qt
application, Battery Indicator, that uses the System Information
Mobility API to fetch battery information from the device.
The user interface for the application is designed using Qt widgets. This
enforces a platform look and feel for Symbian devices and Maemo 5 devices.
However, to achieve a platform look and feel for MeeGo Harmattan devices,
\l{Creating Qt Quick Applications}{create a Qt Quick Application} and use
the Qt Quick components for MeeGo.
\image qtcreator-batteryindicator-screenshot.png
\section1 Creating the Battery Indicator Project
\note Create the project with the \gui{Help} mode active so that you can
follow these instructions while you work.
\list 1
\o Select \gui{File > New File or Project > Qt Widget Project > Mobile
Qt Application > Choose}.
\image qtcreator-new-mobile-project.png "New File or Project dialog"
The \gui{Introduction and Project Location} dialog opens.
\image qtcreator-mobile-intro-and-location.png "Introduction and Project Location dialog"
\o In the \gui{Name} field, type \bold {BatteryIndicator}.
\o In the \gui {Create in} field, enter the path for the project files.
For example, \c {C:\Qt\examples}, and then click \gui{Next}.
The \gui{Target Setup} dialog opens.
\image qtcreator-mobile-project-qt-versions.png "Target Setup dialog"
\o Select \gui {Symbian Device}, \gui {Maemo5}, \gui Harmattan, and
\gui {Qt Simulator} targets, and click \gui{Next}.
\note Targets are listed if you installed the appropriate
development environment, for example, as part of the \QSDK. You can
add targets later in the \gui Projects mode.
The \gui {Mobile Options} dialog opens.
\image qtcreator-mobile-project-app-options.png "Mobile Options dialog"
\o In the \gui {Orientation behavior} field, determine how the
application behaves when the orientation of the device display
rotates between portrait and landscape, and then click \gui{Next}.
\note This dialog opens only if you select \gui Maemo5 or
\gui {Symbian Device} target in the \gui {Target Setup} dialog. On
Harmattan, the Qt Quick Components for MeeGo provide native-looking
rotation.
The \gui {Symbian Specific} dialog opens.
\image qtcreator-mobile-project-symbian-options.png "Symbian Specific dialog"
\note \QC contains a default program icon and generates an
\l{Application UID}, for testing the application on a device. You
only need to change the icon and UID if you deliver the application
for public use.
\o Click \gui Next.
The \gui {Maemo Specific} dialog opens.
\image qtcreator-mobile-project-maemo-options.png "Maemo Specific dialog"
\o In the \gui {Application icon} field, select the application
icon to use on Maemo 5 or Harmattan targets, or click \gui Next to
use the default icon.
The \gui{Project Management} dialog opens.
\image qtcreator-mobile-project-summary.png "Project Management dialog"
\o Review the project settings, and click \gui{Finish} to create the
project.
\endlist
The BatteryIndicator project now contains the following files:
\list
\o BatteryIndicator.pro
\o main.cpp
\o BatteryIndicator.svg
\o BatteryIndicator.png
\o BatteryIndicator.desktop
\o deployment.pri
\o mainwindow.cpp
\o mainwindow.ui
\o mainwindow.h
\o templates for Debian deployment files
\endlist
\image qtcreator-mobile-project-contents.png "Project contents"
The files come with the necessary boiler plate code that you must
modify, as described in the following sections.
\section1 Declaring the Qt Mobility API
To use the Qt Mobility APIs or develop applications for Symbian
devices, you must modify the .pro file to declare the Qt Mobility APIs
that you use.
This example uses the System Info API, so you must declare it, as
illustrated by the following code snippet:
\code
CONFIG += mobility
MOBILITY = systeminfo
\endcode
Each Mobility API has its corresponding value that you have to add
as a value of MOBILITY to use the API. For a list of the APIs and the
corresponding values that you can assign to MOBILITY, see the
\l {http://doc.qt.nokia.com/qtmobility/quickstart.html}{Quickstart Example}.
\section1 Designing the User Interface
\list 1
\o In the \gui{Editor} mode, double-click the mainwindow.ui
file in the \gui{Projects} view to launch the integrated \QD.
\o Drag and drop a \gui{Progress Bar}
(\l{http://doc.qt.nokia.com/4.7/qprogressbar.html}{QProgressBar})
widget to the form.
\image qtcreator-mobile-project-widgets.png "Adding widgets to the UI"
\o In the \gui Properties pane, change the \gui objectName to
\bold batteryLevelBar.
\o Right-click the \gui MainWindow object and select
\gui {Lay Out > Lay Out Horizontally} to ensure that the battery
indicator widget size is adjusted correctly on Maemo devices.
\endlist
\section1 Completing the Header File
The mainwindow.h file contains some of the necessary #includes, a
constructor, a destructor, and the \c{Ui} object. You must include
the System Info header file, add a shortcut to the mobility name
space, and add a private function to update the battery level value in
the indicator when the battery power level changes.
\list 1
\o In the \gui{Projects} view, double-click the \c{mainwindow.h} file
to open it for editing.
\o Include the System Device Info header file, as illustrated by the
following code snippet:
\snippet examples/batteryindicator/mainwindow.h 1
\o Add a shortcut to the mobility name space, as illustrated by the
following code snippet:
\snippet examples/batteryindicator/mainwindow.h 2
\o Declare a private function in the \c{private} section, after the
\c{Ui::MainWindow} function, as illustrated by the following code
snippet:
\snippet examples/batteryindicator/mainwindow.h 3
\endlist
\section1 Completing the Source File
Now that the header file is complete, move on to the source file,
mainwindow.cpp.
\list 1
\o In the \gui{Projects} view, double-click the mainwindow.cpp file
to open it for editing.
\o Create a QSystemDeviceInfo object and set its value. Then connect
the signal that indicates that battery level changed to the
\c setValue slot of the progress bar. This is illustrated by the
following code snippet:
\snippet examples/batteryindicator/mainwindow.cpp 1
\o Use the constructor to set initial values and make sure that the
created object is in a defined state, as illustrated by the
following code snippet:
\snippet examples/batteryindicator/mainwindow.cpp 2
\endlist
\section1 Compiling and Running Your Program
Now that you have all the necessary code, select \gui {Qt Simulator}
as the target and click the
\inlineimage qtcreator-run.png
button to build your program and run it in the Qt Simulator.
In Qt Simulator, run the runOutOfBattery.qs example script
to see the value change in the Battery Indicator application.
Select \gui {Scripting > examples > runOutOfBattery.qs > Run}.
\image qtcreator-mobile-simulated.png "Mobile example in Qt Simulator"
\section1 Testing on a Symbian Device
You also need to test the application on real devices. Before you can
start testing on Symbian devices, you must connect them to the development
PC by using a USB cable and install an on-device debugging agent on them.
\list 1
\o Install the necessary software on the device. For more information,
see \l{Connecting Symbian Devices}.
\o Start the CODA debugging agent on the device.
\o Click the \gui {Target Selector} and select \gui {Symbian Device}.
\o Click \gui Run to build the application for the Symbian device.
\endlist
\section1 Testing on the Maemo or MeeGo Harmattan Emulator
The Maemo 5 (Fremantle) and MeeGo Harmattan emulator are installed as part
of the \QSDK. After they are installed, you can start them from \QC.
The Maemo emulator emulates the Nokia N900 device environment. You can test
applications in conditions practically identical to running the application
on a Nokia N900 device with the software update release 1.3 (V20.2010.36-2).
The MeeGo Harmattan emulator emulates the Nokia N9 device environment.
For more information, see \l{Using Maemo or MeeGo Harmattan Emulator}.
*/
/****************************************************************************
**
** This file is part of Qt Creator
**