talksik/MinimalQml
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update README file

Browse Source
This commit is contained in:
Rasim Labibov
2018-01-29 17:07:31 +02:00
parent 8583b6f45f
commit 004ca563ca
1 changed files with 82 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+82 -72
View File
@@ -5,26 +5,30 @@ interface. The tutorial uses CMake as the project format and C++ as the language
of source code. The application created is simple in design and consists of sole of source code. The application created is simple in design and consists of sole
window. window.
QtQuick is a user interface library that provides ways to create declarative QtQuick is a user interface library for creating declarative
user interface separated from the programming logic. It's framework is user interfaces that are separated from programming logic. This framework is
implemented as a part of the Qt library set. QML is a user interface implemented as a part of the Qt library set. QML is a user interface
specification and programming language. specification and programming language.
CMake is the project generator for many platforms and build systems. CMake uses CMake is the project generator for many platforms and build systems. The CMake build system uses
the unified file format and is able to generate makefiles, Visual Studio the unified file format and is able to generate makefiles, Visual Studio
solutions and projects for many other build systems from the same project file. solutions, and projects for many other build systems from the same project file.
You can check out some [CMake examples](https://cmake.org/examples/) on the official website if you want to learn more.
## Prerequisites ## Prerequisites
Compiling and running the sample project requires GCC, CMake, GNU Make and Qt In order to develop an application using CMake with Qt QML,
development libraries with Qt Quick enabled. This tutorial specifies the way to we first need to make sure that we have all the necessary tools.
install pre-compiled packages from the standard repositories.
Compiling and running the sample project requires GCC, CMake, GNU Make and the Qt
development libraries with Qt Quick enabled. This tutorial specifies how to
install pre-compiled packages from standard repositories.
## Environment Setup ## Environment Setup
### Debian-based Systems ### Debian-based Systems
The following instructions are applied to these operating systems: The following instructions apply to:
* Ubuntu 16.04 * Ubuntu 16.04
* Debian 9 * Debian 9
@@ -41,9 +45,9 @@ sudo apt-get install -y \
### RedHat-based Systems ### RedHat-based Systems
The following instructions are applied to these operating systems: The following instructions apply to:
* Fedora >=22 * Fedora 22 and higher
``` ```
sudo dnf groupinstall -y \ sudo dnf groupinstall -y \
@@ -74,7 +78,7 @@ sudo yum install -y \
## Directory Structure ## Directory Structure
The directory of the project is laid out as follows. The directory of the project is laid out as follows:
``` ```
$ tree $ tree
@@ -89,19 +93,19 @@ $ tree
1 directory, 5 files 1 directory, 5 files
``` ```
All source files for the project will go in src and main project specifications All source files for the project go in `src`, and main project specifications
in CMake format are in the `CMakeLists.txt` file. Larger projects tend to be in CMake format go in `CMakeLists.txt`. Larger projects tend to be
organised in sub-directories for modules, executables and libraries, each with organised in sub-directories for modules, executables and libraries, each with
its individual sub-directory and `CMakeLists.txt` file within. its individual sub-directory and `CMakeLists.txt` file.
## Main Window GUI File ## Main Window GUI File
Start with declarative file for user interface that is specified in the file With this example, we start with the declarative file for the user interface, which is specified in
`src/main.qml`. The code creates a small window without any controls. `src/main.qml`. The code below creates a small window without any controls:
[src/main.qml](src/main.qml) [src/main.qml](src/main.qml)
Necessary modules are imported. The exact version of the `QtQuick` library is not The next code imports all necessary modules. The exact version of `QtQuick` is not
the same as the version of the Qt framework used. `QtQuick.Controls` library the same as the version of the Qt framework used. `QtQuick.Controls` library
contains some basic controls for the user interface. contains some basic controls for the user interface.
@@ -120,9 +124,9 @@ ApplicationWindow
} }
``` ```
There are four attributes of the main window that specify the size and title of There are four attributes of the main window that specify its size and title.
the window. The `visible` attribute is required to specify that the window should The `visible` aattribute specifies that the window should
be shown in the screen right after launch. be shown right after launch.
``` ```
visible: true visible: true
@@ -133,9 +137,9 @@ title: qsTr("Minimal Qml")
## QML Resource File ## QML Resource File
This is the QML resource file for the application that consists of sole QML file Next, let’s look at the QML resource file for an application that consists of sole QML file
named `main.qml`. The file is XML with `RCC` element as root and `qresource` as named `main.qml`. The file is written in XML with the `RCC` element as root and `qresource` as
element for group of resources. This project contains only one group that is the the element for group of resources. This project contains only one group that's
root (i.e. `/`). Larger projects may contain additional `qresource` elements for root (i.e. `/`). Larger projects may contain additional `qresource` elements for
each resource subgroup (e.g. `customControls`, `customWindows`, etc.). each resource subgroup (e.g. `customControls`, `customWindows`, etc.).
@@ -148,16 +152,16 @@ Quick user interface.
[src/main.qml](src/main.cpp) [src/main.qml](src/main.cpp)
Standard object for Qt application is constructed. The following code constructs a standard object for a Qt application:
``` ```
QApplication app(argc, argv); QApplication app(argc, argv);
``` ```
Here the QML parsing object is initiated for the application. This object In the next section, the QML parsing object is initiated for the application. This object
receives the string with address of the main QML resource as the construction receives the string with the address of the main QML resource as the construction
parameter. In this case `qrc:/main.qml` is the address specified in the `qml.qrc` parameter. In this case, `qrc:/main.qml` is the address specified in the `qml.qrc`
file. `qrc:` is the default prefix for the QML resource, `/main.qml` stands for file. `qrc` is the default prefix for the QML resource, and `/main.qml` references the
resource named `main.qml` in the root resource directory (`/`). resource named `main.qml` in the root resource directory (`/`).
``` ```
@@ -165,7 +169,7 @@ QQmlApplicationEngine engine;
engine.load(QUrl(QStringLiteral("qrc:/main.qml"))); engine.load(QUrl(QStringLiteral("qrc:/main.qml")));
``` ```
The `exec` method starts Qt application. The `exec` method starts the Qt application:
``` ```
return app.exec(); return app.exec();
@@ -173,22 +177,22 @@ return app.exec();
## Project Files ## Project Files
This section shows deployment of Qt Quick application using CMake project Now we’ll show you how to deploy a Qt Quick application using the CMake project
format. format.
This is the main project file. The first line sets the minimum version of CMake Let’s look at the main project file. The first line sets the minimum version of CMake
for the project. It includes Qt5 framework into the application and concludes for the project. It then includes the Qt5 framework into the application
with the further inclusion of the `src` subdirectory so that CMake would search as well as the `src` subdirectory so that CMake will search
for the project file (`CMakeLists.txt`) there. for the project file (`CMakeLists.txt`) there.
[CMakeLists.txt](CMakeLists.txt) [CMakeLists.txt](CMakeLists.txt)
This is the project file for the executable. This is the project file for the executable:
[src/CMakeLists.txt](src/CMakeLists.txt) [src/CMakeLists.txt](src/CMakeLists.txt)
The header files of the Qt project should be included into the project so that The header files of the Qt project should be included into the project so that the
makefiles generated will have them specified in the corresponding compilation makefiles generated will specify them in the corresponding compilation
commands. There Qt5Widgets stands the header files for the Qt Framework and commands. There Qt5Widgets stands the header files for the Qt Framework and
QtQml invokes special files for QML functions. QtQml invokes special files for QML functions.
@@ -196,7 +200,7 @@ QtQml invokes special files for QML functions.
include_directories(${Qt5Widgets_INCLUDE_DIRS} ${QtQml_INCLUDE_DIRS}) include_directories(${Qt5Widgets_INCLUDE_DIRS} ${QtQml_INCLUDE_DIRS})
``` ```
The definitions as well as Qt include files should be specified in the makefile The definitions as well as the Qt include files should be specified in the makefile
compilation commands. compilation commands.
``` ```
@@ -206,14 +210,14 @@ add_definitions(${Qt5Widgets_DEFINITIONS} ${QtQml_DEFINITIONS}
The Qt framework requires the code to be created from the Qt resource files. The Qt framework requires the code to be created from the Qt resource files.
This is achieved using the special `qt5_add_resources` command. The QML resource This is achieved using the special `qt5_add_resources` command. The QML resource
file path relative to this file is passed as an argument here. file path relative to this file is passed as an argument:
``` ```
qt5_add_resources(QT_RESOURCES qml.qrc) qt5_add_resources(QT_RESOURCES qml.qrc)
``` ```
For Qt projects with graphical user interface the compiler should receive For Qt projects with graphical user interface, the compiler should receive
special parameters for compilation special parameters in order to compile:
``` ```
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${Qt5Widgets_EXECUTABLE_COMPILE_FLAGS}") set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${Qt5Widgets_EXECUTABLE_COMPILE_FLAGS}")
@@ -228,23 +232,23 @@ set(CMAKE_AUTORCC ON)
set(CMAKE_AUTOUIC ON) set(CMAKE_AUTOUIC ON)
``` ```
The name of the project that will be used as a name of the compiled executable The name of the project that will be used as the name of the compiled executable,
is specified using the set command that receives the name of a variable (i.e. is specified using the `set` command, which receives the name of a variable (i.e.
`PROJECT`) and it's value. `PROJECT`) and it's value.
``` ```
set(PROJECT "MinimalQml") set(PROJECT "MinimalQml")
``` ```
The project command sets the current project within the CMake file. It receives The `project` command sets the current project within the CMake file and receives
the value of the variable defined above. the value of the variable defined above:
``` ```
project(${PROJECT}) project(${PROJECT})
``` ```
The compiler flags for compiling C++ sources are set below. These flags stands The compiler flags for compiling C++ sources are set below. These flags set
for very strict compilation rules and help to detect and locate a lot of very strict compilation rules and help to detect and locate a lot of
potential issues during compilation. potential issues during compilation.
``` ```
@@ -253,12 +257,12 @@ set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall -Werror -std=c++11
-Wno-unused-variable") -Wno-unused-variable")
``` ```
There are conditional commands in the CMake project language. The code below There are also conditional commands in the CMake. The code below
detects if there are `HEADERS` in the project. If the header files were not set detects if there are `HEADERS` in the project. If the header files were not previously set,
before the `file(GLOB ... .h)` command creates a list of all header files in the the `file(GLOB ... .h)` command creates a list of all header files in the
current directory and passes them as header files of the current project. The current directory and passes them as header files of the current project. The
same applies to the `.cpp` sources that will be stored in the `SOURCES` variable if same applies to the `.cpp` sources that are stored in the `SOURCES` variable if
it was not defined. that was not defined.
``` ```
if(NOT DEFINED HEADERS) if(NOT DEFINED HEADERS)
@@ -270,28 +274,27 @@ if(NOT DEFINED SOURCES)
endif() endif()
``` ```
The `source_group` definition creates a group of files that will be placed in some The `source_group` definition creates a group of files that are placed in some
build systems (e.g. there will be project sub-directories in Visual Studio build systems (e.g. project sub-directories in Visual Studio).
solution).
``` ```
source_group("Header Files" FILES ${HEADERS}) source_group("Header Files" FILES ${HEADERS})
source_group("Source Files" FILES ${SOURCES}) source_group("Source Files" FILES ${SOURCES})
``` ```
This command states an executable file is the result of the project. The first This command states that the project results in an executable file. The first
parameter receives the name of an executable file that is the same as the name parameter receives the name of an executable file (which in this case is the same as the name
of the project in this case. The rest of the arguments are project sources, of the project). The rest of the arguments are project sources,
headers and compiled Qt resources. headers, and compiled Qt resources.
``` ```
add_executable(${PROJECT} ${HEADERS} ${SOURCES} ${QT_RESOURCES}) add_executable(${PROJECT} ${HEADERS} ${SOURCES} ${QT_RESOURCES})
``` ```
The set of libraries that will be linked with the executable above is set with The set of libraries that will be linked with the executable above is set with
the `target_link_libraries` command. Like the command above it receives the name the `target_link_libraries` command. Like the command above, it receives the name
of project's executable and the list of libraries. In this case the project uses of project's executable and a list of libraries. In this case, the project uses only
Qt framework libraries only. Qt framework libraries.
``` ```
target_link_libraries(${PROJECT} target_link_libraries(${PROJECT}
@@ -303,9 +306,11 @@ target_link_libraries(${PROJECT}
## Building Project ## Building Project
The program is built with the commands below. CMake requires the directory Now it’s time for building with CMake.
with the main project's `CMakeLists.txt` file as an argument. Then the CMake
creates the build files for the GNU make which build an executable. You can build your program using the commands below. CMake takes a directory
with the main project's `CMakeLists.txt` file as an argument. Then it
creates build files for GNU make, which builds an executable.
``` ```
cd <PathToProject> cd <PathToProject>
@@ -314,26 +319,31 @@ cmake ..
make make
``` ```
After the successful build the binary `MinimalQml` will end up in `build/src/`. After a successful build, the binary `MinimalQml` will end up in `build/src/`.
``` ```
./src/MinimalQml ./src/MinimalQml
``` ```
## Working with Project with Qt Creator ## Working on a Project with Qt Creator
You can probably avoid working with Qt Creator by creating a Qt QML C++ plugin with CMake,
but we prefer going the traditional route.
If you want to know more about Qt Creator, you can find the [official manual](http://doc.qt.io/qtcreator/).
Now, let’s look into how we can use Qt Creator with our Qt CMake example project.
Go to the *Welcome* tab *(1)* in the main window and select *Open Project* *(2)*. Go to the *Welcome* tab *(1)* in the main window and select *Open Project* *(2)*.
![Qt Creator Welcome Page](img/qt101.png) ![Qt Creator Welcome Page](img/qt101.png)
In the opened dialog locate the `CMakeLists.txt` file in the root directory of the In the dialog box that opens, locate the `CMakeLists.txt` file in the project’s root directory.
project.
![Opening Project File](img/qt102.png) ![Opening Project File](img/qt102.png)
After that select the version of the *Qt framework* that will be used for Next, select the version of *Qt framework* that you’ll use to
compiling the project. In case there are multiple frameworks installed in the compile the project. If you have multiple frameworks installed,
system it is possible to select several of them. it’s possible to select several.
![Selecting Qt Frameworks](img/qt103.png) ![Selecting Qt Frameworks](img/qt103.png)
@@ -350,7 +360,7 @@ QRC resource files are opened as a resource tree.
![Opened QRC Resource File](img/qt106.png) ![Opened QRC Resource File](img/qt106.png)
From the resource tree it is possible to open QML files of the project. From the resource tree, you can open QML files for the project.
![Editing QML File](img/qt107.png) ![Editing QML File](img/qt107.png)