From 004ca563ca89cc1bb3cc4ab2514734885f4bafcb Mon Sep 17 00:00:00 2001 From: Rasim Labibov Date: Mon, 29 Jan 2018 17:07:31 +0200 Subject: [PATCH] Update README file --- README.md | 154 +++++++++++++++++++++++++++++------------------------- 1 file changed, 82 insertions(+), 72 deletions(-) diff --git a/README.md b/README.md index 971519e..0419603 100644 --- a/README.md +++ b/README.md @@ -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 window. -QtQuick is a user interface library that provides ways to create declarative -user interface separated from the programming logic. It's framework is +QtQuick is a user interface library for creating declarative +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 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 -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 -Compiling and running the sample project requires GCC, CMake, GNU Make and Qt -development libraries with Qt Quick enabled. This tutorial specifies the way to -install pre-compiled packages from the standard repositories. +In order to develop an application using CMake with Qt QML, +we first need to make sure that we have all the necessary tools. + +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 ### Debian-based Systems -The following instructions are applied to these operating systems: +The following instructions apply to: * Ubuntu 16.04 * Debian 9 @@ -41,9 +45,9 @@ sudo apt-get install -y \ ### 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 \ @@ -74,7 +78,7 @@ sudo yum install -y \ ## Directory Structure -The directory of the project is laid out as follows. +The directory of the project is laid out as follows: ``` $ tree @@ -89,19 +93,19 @@ $ tree 1 directory, 5 files ``` -All source files for the project will go in src and main project specifications -in CMake format are in the `CMakeLists.txt` file. Larger projects tend to be +All source files for the project go in `src`, and main project specifications +in CMake format go in `CMakeLists.txt`. Larger projects tend to be 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 -Start with declarative file for user interface that is specified in the file -`src/main.qml`. The code creates a small window without any controls. +With this example, we start with the declarative file for the user interface, which is specified in +`src/main.qml`. The code below creates a small window without any controls: [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 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 -the window. The `visible` attribute is required to specify that the window should -be shown in the screen right after launch. +There are four attributes of the main window that specify its size and title. +The `visible` aattribute specifies that the window should +be shown right after launch. ``` visible: true @@ -133,9 +137,9 @@ title: qsTr("Minimal Qml") ## QML Resource File -This is the QML resource file for the application that consists of sole QML file -named `main.qml`. The file is XML with `RCC` element as root and `qresource` as -element for group of resources. This project contains only one group that is the +Next, let’s look at the QML resource file for an application that consists of sole QML file +named `main.qml`. The file is written in XML with the `RCC` element as root and `qresource` as +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 each resource subgroup (e.g. `customControls`, `customWindows`, etc.). @@ -148,16 +152,16 @@ Quick user interface. [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); ``` -Here the QML parsing object is initiated for the application. This object -receives the string with address of the main QML resource as the construction -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 +In the next section, the QML parsing object is initiated for the application. This object +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` +file. `qrc` is the default prefix for the QML resource, and `/main.qml` references the resource named `main.qml` in the root resource directory (`/`). ``` @@ -165,7 +169,7 @@ QQmlApplicationEngine engine; engine.load(QUrl(QStringLiteral("qrc:/main.qml"))); ``` -The `exec` method starts Qt application. +The `exec` method starts the Qt application: ``` return app.exec(); @@ -173,22 +177,22 @@ return app.exec(); ## 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. -This is 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 -with the further inclusion of the `src` subdirectory so that CMake would search +Let’s look at the main project file. The first line sets the minimum version of CMake +for the project. It then includes the Qt5 framework into the application +as well as the `src` subdirectory so that CMake will search for the project file (`CMakeLists.txt`) there. [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) -The header files of the Qt project should be included into the project so that -makefiles generated will have them specified in the corresponding compilation +The header files of the Qt project should be included into the project so that the +makefiles generated will specify them in the corresponding compilation commands. There Qt5Widgets stands the header files for the Qt Framework and 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}) ``` -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. ``` @@ -206,14 +210,14 @@ add_definitions(${Qt5Widgets_DEFINITIONS} ${QtQml_DEFINITIONS} 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 -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) ``` -For Qt projects with graphical user interface the compiler should receive -special parameters for compilation +For Qt projects with graphical user interface, the compiler should receive +special parameters in order to compile: ``` set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${Qt5Widgets_EXECUTABLE_COMPILE_FLAGS}") @@ -228,23 +232,23 @@ set(CMAKE_AUTORCC ON) set(CMAKE_AUTOUIC ON) ``` -The name of the project that will be used as a name of the compiled executable -is specified using the set command that receives the name of a variable (i.e. +The name of the project that will be used as the name of the compiled executable, +is specified using the `set` command, which receives the name of a variable (i.e. `PROJECT`) and it's value. ``` set(PROJECT "MinimalQml") ``` -The project command sets the current project within the CMake file. It receives -the value of the variable defined above. +The `project` command sets the current project within the CMake file and receives +the value of the variable defined above: ``` project(${PROJECT}) ``` -The compiler flags for compiling C++ sources are set below. These flags stands -for very strict compilation rules and help to detect and locate a lot of +The compiler flags for compiling C++ sources are set below. These flags set +very strict compilation rules and help to detect and locate a lot of potential issues during compilation. ``` @@ -253,12 +257,12 @@ set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall -Werror -std=c++11 -Wno-unused-variable") ``` -There are conditional commands in the CMake project language. The code below -detects if there are `HEADERS` in the project. If the header files were not set -before the `file(GLOB ... .h)` command creates a list of all header files in the +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 previously set, +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 -same applies to the `.cpp` sources that will be stored in the `SOURCES` variable if -it was not defined. +same applies to the `.cpp` sources that are stored in the `SOURCES` variable if +that was not defined. ``` if(NOT DEFINED HEADERS) @@ -270,28 +274,27 @@ if(NOT DEFINED SOURCES) endif() ``` -The `source_group` definition creates a group of files that will be placed in some -build systems (e.g. there will be project sub-directories in Visual Studio -solution). +The `source_group` definition creates a group of files that are placed in some +build systems (e.g. project sub-directories in Visual Studio). ``` source_group("Header Files" FILES ${HEADERS}) source_group("Source Files" FILES ${SOURCES}) ``` -This command states an executable file is the result of the project. The first -parameter receives the name of an executable file that is the same as the name -of the project in this case. The rest of the arguments are project sources, -headers and compiled Qt resources. +This command states that the project results in an executable file. The first +parameter receives the name of an executable file (which in this case is the same as the name +of the project). The rest of the arguments are project sources, +headers, and compiled 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 `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 -Qt framework libraries only. +the `target_link_libraries` command. Like the command above, it receives the name +of project's executable and a list of libraries. In this case, the project uses only +Qt framework libraries. ``` target_link_libraries(${PROJECT} @@ -303,9 +306,11 @@ target_link_libraries(${PROJECT} ## Building Project -The program is built with the commands below. CMake requires the directory -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. +Now it’s time for building with CMake. + +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 @@ -314,26 +319,31 @@ cmake .. 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 ``` -## 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)*. ![Qt Creator Welcome Page](img/qt101.png) -In the opened dialog locate the `CMakeLists.txt` file in the root directory of the -project. +In the dialog box that opens, locate the `CMakeLists.txt` file in the project’s root directory. ![Opening Project File](img/qt102.png) -After that select the version of the *Qt framework* that will be used for -compiling the project. In case there are multiple frameworks installed in the -system it is possible to select several of them. +Next, select the version of *Qt framework* that you’ll use to +compile the project. If you have multiple frameworks installed, +it’s possible to select several. ![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) -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)