[FEATURE] Introduction of QGIS Quick library

This pull request is a subset of #6490 This adds a new library for creation of applications based on Qt Quick framework. It contains reusable QML / Qt Quick components based on QGIS core library. The initial work introduces MapCanvas To enable compilation of the library, use WITH_QUICK=TRUE Further documentation of the library is located in doc/qgsquick.dox For background information see the associated QEP: qgis/QGIS-Enhancement-Proposals#109 The initial implementation is largely based on the work of Matthias Kuhn and Marco Bernasocchi on QField probject - kudos to them for the great job!
qgis · Apr 26, 2018 · b1bf9b2 · b1bf9b2
1 parent f816588
commit b1bf9b2
Show file tree

Hide file tree

Showing 37 changed files with 3,287 additions and 3 deletions.
diff --git a/.ci/travis/linux/docker-build-test.sh b/.ci/travis/linux/docker-build-test.sh
@@ -40,6 +40,7 @@ echo "${bold}Running cmake...${endbold}"
 cmake \
  -GNinja \
  -DUSE_CCACHE=OFF \
+ -DWITH_QUICK=ON \
  -DWITH_3D=ON \
  -DWITH_STAGED_PLUGINS=ON \
  -DWITH_GRASS=OFF \

diff --git a/.docker/qgis3-build-deps.dockerfile b/.docker/qgis3-build-deps.dockerfile
@@ -33,11 +33,17 @@ RUN  apt-get update \
     libqca-qt5-2-dev \
     libqca-qt5-2-plugins \
     libqt53drender5 \
+    libqt5concurrent5 \
     libqt5opengl5-dev \
+    libqt5positioning5 \
+    libqt5qml5 \
+    libqt5quick5 \
+    libqt5quickcontrols2-5 \
     libqt5scintilla2-dev \
     libqt5sql5-sqlite \
     libqt5svg5-dev \
     libqt5webkit5-dev \
+    libqt5xml5 \
     libqt5xmlpatterns5-dev \
     libqwt-qt5-dev \
     libspatialindex-dev \
@@ -77,6 +83,8 @@ RUN  apt-get update \
     qt3d-scene2d-plugin \
     qt5keychain-dev \
     qtbase5-dev \
+    qtdeclarative5-dev-tools \
+    qtdeclarative5-qtquick2-plugin \
     qtpositioning5-dev \
     qttools5-dev \
     qttools5-dev-tools \

diff --git a/.gitignore b/.gitignore
@@ -30,6 +30,8 @@ desktop.ini
 doc/INSTALL.tex
 i18n/*.qm
 Makefile
+*.pro.user
+*.stash
 ms-windows/*.exe*
 ms-windows/Installer-Files/postinstall.bat
 ms-windows/Installer-Files/preremove.bat

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -71,6 +71,8 @@ IF(WITH_CORE)
 
   SET (WITH_3D FALSE CACHE BOOL "Determines whether QGIS 3D library should be built")
 
+  SET (WITH_QUICK FALSE CACHE BOOL "Determines whether QGIS Quick library should be built")
+
   # server disabled default because it needs FastCGI (which is optional dependency)
   SET (WITH_SERVER FALSE CACHE BOOL "Determines whether QGIS server should be built")
   IF(WITH_SERVER)
@@ -322,6 +324,18 @@ IF(WITH_CORE)
   ENDIF (WITH_3D)
   INCLUDE("cmake/modules/ECMQt4To5Porting.cmake")
   MESSAGE(STATUS "Found Qt version: ${Qt5Core_VERSION_STRING}")
+  IF (WITH_QUICK)
+    FIND_PACKAGE(Qt5Qml REQUIRED)
+    FIND_PACKAGE(Qt5Quick REQUIRED)
+    IF(${CMAKE_SYSTEM_NAME} MATCHES "Android")
+        FIND_PACKAGE(Qt5AndroidExtras)
+    ELSE(${CMAKE_SYSTEM_NAME} MATCHES "Android")
+        FIND_PACKAGE(QtQmlTools REQUIRED)
+    ENDIF(${CMAKE_SYSTEM_NAME} MATCHES "Android")
+
+    # following variable is used in qgsconfig.h
+    SET (HAVE_QUICK TRUE)
+  ENDIF (WITH_QUICK)
 
   IF(WITH_QTWEBKIT)
     SET(OPTIONAL_QTWEBKIT ${Qt5WebKitWidgets_LIBRARIES})
@@ -373,6 +387,9 @@ ENDIF(WITH_CORE)
 # build our version of astyle
 SET (WITH_ASTYLE FALSE CACHE BOOL "If you plan to contribute you should reindent with scripts/prepare-commit.sh (using 'our' astyle)")
 
+# QML
+SET(QML_IMPORT_PATH "${CMAKE_RUNTIME_OUTPUT_DIRECTORY}" CACHE PATH "QML directory for QML autocomplete")
+
 #############################################################
 # testing
 # whether unit tests should be build
@@ -513,6 +530,7 @@ IF (WITH_CORE)
     SET (DEFAULT_DATA_SUBDIR    .)
     SET (DEFAULT_PLUGIN_SUBDIR  plugins)
     SET (DEFAULT_INCLUDE_SUBDIR include)
+    SET (DEFAULT_QML_SUBDIR     qml)
 
     SET (DEFAULT_SERVER_MODULE_SUBDIR server)
 
@@ -583,6 +601,7 @@ IF (WITH_CORE)
       SET (DEFAULT_PLUGIN_SUBDIR   ../PlugIns/qgis)
       SET (QGIS_PLUGIN_SUBDIR_REV  ../../MacOS)
       SET (DEFAULT_INCLUDE_SUBDIR  include/qgis)
+      SET (DEFAULT_QML_SUBDIR     qml)
 
       # Set server moodules path to DEFAULT_LIBEXEC_SUBDIR+'/server'
       SET (DEFAULT_SERVER_MODULE_SUBDIR ${DEFAULT_LIBEXEC_SUBDIR}/server)
@@ -610,6 +629,7 @@ IF (WITH_CORE)
       SET (DEFAULT_LIBEXEC_SUBDIR lib${LIB_SUFFIX}/qgis)
       SET (DEFAULT_PLUGIN_SUBDIR  lib${LIB_SUFFIX}/qgis/plugins)
       SET (DEFAULT_INCLUDE_SUBDIR include/qgis)
+      SET (DEFAULT_QML_SUBDIR     qml)
 
       SET (DEFAULT_SERVER_MODULE_SUBDIR ${DEFAULT_LIBEXEC_SUBDIR}/server)
     ENDIF (APPLE)
@@ -658,6 +678,7 @@ SET (QGIS_LIBEXEC_SUBDIR ${DEFAULT_LIBEXEC_SUBDIR} CACHE STRING "Subdirectory wh
 SET (QGIS_DATA_SUBDIR    ${DEFAULT_DATA_SUBDIR}    CACHE STRING "Subdirectory where QGIS data will be installed")
 SET (QGIS_PLUGIN_SUBDIR  ${DEFAULT_PLUGIN_SUBDIR}  CACHE STRING "Subdirectory where plugins will be installed")
 SET (QGIS_INCLUDE_SUBDIR ${DEFAULT_INCLUDE_SUBDIR} CACHE STRING "Subdirectory where header files will be installed")
+SET (QGIS_QML_SUBDIR     ${DEFAULT_QML_SUBDIR}     CACHE STRING "Subdirectory where qml files/libraries will be installed")
 
 SET (QGIS_SERVER_MODULE_SUBDIR  ${DEFAULT_SERVER_MODULE_SUBDIR}  CACHE STRING "Subdirectory where server modules will be installed")
 
@@ -673,6 +694,7 @@ SET (QGIS_LIBEXEC_DIR ${QGIS_LIBEXEC_SUBDIR})
 SET (QGIS_DATA_DIR    ${QGIS_DATA_SUBDIR})
 SET (QGIS_PLUGIN_DIR  ${QGIS_PLUGIN_SUBDIR})
 SET (QGIS_INCLUDE_DIR ${QGIS_INCLUDE_SUBDIR})
+SET (QGIS_QML_DIR     ${QGIS_QML_SUBDIR})
 
 SET (QGIS_SERVER_MODULE_DIR ${QGIS_SERVER_MODULE_SUBDIR})
 

diff --git a/cmake/FindQtQmlTools.cmake b/cmake/FindQtQmlTools.cmake
@@ -0,0 +1,47 @@
+# Qt QML Tools
+# ~~~~~~~~~~~~
+# 
+# To generate qmltypes files required by Qt Creator to allow QML code inspection
+# (http://doc.qt.io/qtcreator/creator-qml-modules-with-plugins.html#generating-qmltypes-files)
+# we need to have installed qmlplugindump unity (shipped with Qt 4.8 and later)
+# http://doc.qt.io/qtcreator/creator-qml-modules-with-plugins.html#dumping-plugins-automatically
+#
+# Find the installed version of qmlplugindump utility. 
+# FindQtQmlTools should be called after Qt5 has been found
+#
+# This file defines the following variables:
+#
+# QMLPLUGINDUMP_FOUND - system has qmlplugindump
+# QMLPLUGINDUMP_EXECUTABLE - Path to qmlplugindump executable
+#
+# Also defines MACRO to create qmltypes file, when QML directory is supplied
+# 
+# Copyright (c) 2017, Peter Petrik <zilolv at gmail dot com>
+# Redistribution and use is allowed according to the terms of the BSD license.
+# For details see the accompanying COPYING-CMAKE-SCRIPTS file.
+
+MACRO(FIND_QMLPLUGINDUMP)
+  IF(NOT QMLPLUGINDUMP_EXECUTABLE)
+    IF (MSVC)
+      FIND_PROGRAM(QMLPLUGINDUMP_EXECUTABLE qmlplugindump.exe)
+    ELSE (MSVC)
+      FIND_PROGRAM(QMLPLUGINDUMP_EXECUTABLE qmlplugindump)
+    ENDIF (MSVC)
+  ENDIF(NOT QMLPLUGINDUMP_EXECUTABLE)
+
+  IF (QMLPLUGINDUMP_EXECUTABLE)
+    SET(QMLPLUGINDUMP_FOUND TRUE)
+    MESSAGE(STATUS "Found qmlplugindump: ${QMLPLUGINDUMP_EXECUTABLE}")
+  ELSE()
+    SET(QMLPLUGINDUMP_FOUND FALSE)
+    IF (QMLPLUGINDUMP_FIND_REQUIRED)
+      MESSAGE(FATAL_ERROR "Could not find qmlplugindump")
+    ELSE (QMLPLUGINDUMP_FIND_REQUIRED)
+      MESSAGE(WARNING "Could not find qmlplugindump")
+    ENDIF (QMLPLUGINDUMP_FIND_REQUIRED)
+  ENDIF (QMLPLUGINDUMP_EXECUTABLE)
+ENDMACRO(FIND_QMLPLUGINDUMP)
+
+IF (NOT QMLPLUGINDUMP_FOUND)
+  FIND_QMLPLUGINDUMP()
+ENDIF (NOT QMLPLUGINDUMP_FOUND)
diff --git a/cmake_templates/qgsconfig.h.in b/cmake_templates/qgsconfig.h.in
@@ -25,6 +25,7 @@
 #define QGIS_DATA_SUBDIR "${QGIS_DATA_SUBDIR}"
 #define QGIS_LIBEXEC_SUBDIR "${QGIS_LIBEXEC_SUBDIR}"
 #define QGIS_LIB_SUBDIR "${QGIS_LIB_SUBDIR}"
+#define QGIS_QML_SUBDIR "${QGIS_QML_SUBDIR}"
 #define CMAKE_INSTALL_PREFIX "${CMAKE_INSTALL_PREFIX}"
 #define CMAKE_SOURCE_DIR "${CMAKE_SOURCE_DIR}"
 
@@ -64,5 +65,7 @@
 
 #cmakedefine QGISDEBUG
 
+#cmakedefine HAVE_QUICK
+
 #endif
 
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
@@ -100,6 +100,8 @@ IF(WITH_APIDOC)
       ${CMAKE_SOURCE_DIR}/src/3d/symbols
       ${CMAKE_SOURCE_DIR}/src/3d/terrain
       ${CMAKE_SOURCE_DIR}/src/plugins
+      ${CMAKE_SOURCE_DIR}/src/quickgui
+      ${CMAKE_SOURCE_DIR}/src/quickgui/plugin
     )
 
     IF(WITH_SERVER_PLUGINS)

diff --git a/doc/CONTRIBUTORS b/doc/CONTRIBUTORS
@@ -71,6 +71,7 @@ Nikos Alexandris
 Paolo Cavallini
 Paul Blottiere
 Paul Ramsey
+Peter Petrik
 Pierre Auckenthaler
 Raymond Nijssen
 Richard Duivenvoorde

diff --git a/doc/index.dox b/doc/index.dox
@@ -45,6 +45,10 @@ website:
 <a href="https://qgis.org/api/1.7">1.7</a> and
 <a href="https://qgis.org/api/1.6">1.6</a>
 
+\section qgsquick_docs QgsQuick library documentation
+
+See \ref qgsquick for information about QGIS Quick (QML) components library
+
 \section index_maillist Mailing Lists
 
 For support we encourage you to join our <a

diff --git a/doc/modules.dox b/doc/modules.dox
@@ -37,3 +37,8 @@ Contains classes related to implementation of QGIS plugins.
 
 */
 
+/** @defgroup quick QgsQuick library
+
+The QgsQuick library is built on top of the CORE library and Qt Quick/QML framework. It adds reusable GUI Quick Components, mainly for mobile devices.
+
+*/
diff --git a/doc/qgsquick.dox b/doc/qgsquick.dox
@@ -0,0 +1,61 @@
+/*! \page qgsquick QGIS Quick Documentation
+
+\tableofcontents
+
+\section qgsquick_overview Overview
+
+QGIS Quick is a QT Quick based GUI library primarily for mobile/tablet devices. Covering basic GIS components (e.g. MapCanvas, Scalebar),
+it simplifies creation of a mobile applications for surveys, data gathering or other on-site work. Qt Quick provides tools
+to create a rich application with a fluid and dynamic user interface. Additionally, Qt Quick Controls 2 provides highly
+optimized controls for embedded/mobile devices with limited resources.
+
+QGIS Quick consists of a Qt plugin that provides the QML components and of a shared library that can be used from C++ code.
+
+\subsection qgsquick_overview_widgets QML Classes
+\subsubsection qgsquick_overview_widgets_mapcanvas MapCanvas
+
+\section qgsquick_styling Styling
+
+Since the QGIS Quick library is meant to be reusable for a wide variety of applications with different styles/themes of the user
+interface, some effort has been done to allow developers customize the colors and layouts of the components. Individual
+components either have attributes for customization (e.g. ScaleBar has "barColor", "barBackgroundColor" properties) or more complex
+components accept a custom styling object (e.g. FeatureForm has "style" property of type FeatureFormStyling with a hierarchy of color
+and layout properties).
+
+\section qgsquick_versioning_api Versioning and API stability
+
+QML engine supports versioning of individual components with libraries - a single component may be available in multiple versions
+with slightly different set of features. This is allows QML libraries to keep API compatibility with older code.
+
+QGIS Quick library is currently in version 0.1 and since it is still a very new library, there are no API stability guarantees:
+the following releases of QGIS may ship updates to components while keeping the same version or even remove some components.
+Over time we expect that as the library will become stable, we will deliver stable API just like with the other QGIS libraries.
+
+\section qgsquick_gui Designing scalable applications
+
+Qt Quick uses pixel sizes for the visual items. When building applications that may run on devices with varying screen DPI,
+this is a problem as the absolute pixel values make the application look different depending on the screen pixel density.
+We recommend to use values device independent pixels ("dp"). It is a concept used on mobile devices, where an item of width of 10dp
+will have always the same physical size (e.g. in millimeters) regardless of the screen density. To set width of an item to 10dp
+in QML, one would write: "width: 10 * QgsQuick.Utils.dp".
+
+\section qgsquick_lib Building the library
+
+The QGIS Quick library is not built by default because QGIS application currently does not use it. In order to build the library
+please make sure that WITH_QUICK variable in CMake configuration is set to ON.
+
+It is recommended to build with CMake variable ENABLE_TESTS set to ON because that will also build a small example application
+that uses Qt Quick components. In the generated project you should see target "qgis_quickapp".
+
+The built QML plugin is installed to a dedicated directory - see QgsApplication::qmlImportPath(). When using QGIS Quick components,
+it is necessary to either use QQmlEngine::addImportPath() to add that directory or to specify QML2_IMPORT_PATH environment variable.
+
+\section qgsquick_demo_app Demo application
+
+A demo application with some basic componets and functionality is available on https://github.com/lutraconsulting/qgis-quick-demo-app
+
+The demo application repository contains also instructions on how to build the application, QGIS Quick and other dependencies on Android.
+
+*/
+
+
diff --git a/python/core/qgsapplication.sip.in b/python/core/qgsapplication.sip.in
@@ -432,6 +432,14 @@ Returns the path containing qgis_core, qgis_gui, qgispython (and other) librarie
     static QString libexecPath();
 %Docstring
 Returns the path with utility executables (help viewer, crssync, ...)
+%End
+
+    static QString qmlImportPath();
+%Docstring
+Returns the path where QML components are installed for QGIS Quick library. Returns
+empty string when QGIS is built without Quick support
+
+.. versionadded:: 3.2
 %End
 
     static void setPrefixPath( const QString &prefixPath, bool useDefaultPaths = false );

diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
@@ -35,3 +35,6 @@ IF (WITH_CUSTOM_WIDGETS)
   ADD_SUBDIRECTORY(customwidgets)
 ENDIF (WITH_CUSTOM_WIDGETS)
 
+IF (WITH_QUICK)
+  ADD_SUBDIRECTORY(quickgui)
+ENDIF (WITH_QUICK)
diff --git a/src/core/qgsapplication.cpp b/src/core/qgsapplication.cpp
@@ -90,6 +90,7 @@ QString ABISYM( QgsApplication::mPluginPath );
 QString ABISYM( QgsApplication::mPkgDataPath );
 QString ABISYM( QgsApplication::mLibraryPath );
 QString ABISYM( QgsApplication::mLibexecPath );
+QString ABISYM( QgsApplication::mQmlImportPath );
 QString ABISYM( QgsApplication::mThemeName );
 QString ABISYM( QgsApplication::mUIThemeName );
 QString ABISYM( QgsApplication::mProfilePath );
@@ -204,6 +205,9 @@ void QgsApplication::init( QString profileFolder )
     ABISYM( mLibexecPath ) = ABISYM( mBuildOutputPath ) + '/' + QGIS_LIBEXEC_SUBDIR + '/' + ABISYM( mCfgIntDir ) + '/';
 #else
     ABISYM( mLibexecPath ) = ABISYM( mBuildOutputPath ) + '/' + QGIS_LIBEXEC_SUBDIR + '/';
+#endif
+#if defined( HAVE_QUICK )
+    ABISYM( mQmlImportPath ) = ABISYM( mBuildOutputPath ) + '/' + QGIS_QML_SUBDIR + '/';
 #endif
   }
   else
@@ -396,6 +400,9 @@ void QgsApplication::setPrefixPath( const QString &prefixPath, bool useDefaultPa
   }
   ABISYM( mLibraryPath ) = ABISYM( mPrefixPath ) + '/' + QGIS_LIB_SUBDIR + '/';
   ABISYM( mLibexecPath ) = ABISYM( mPrefixPath ) + '/' + QGIS_LIBEXEC_SUBDIR + '/';
+#if defined( HAVE_QUICK )
+  ABISYM( mQmlImportPath ) = ABISYM( mPrefixPath ) + '/' + QGIS_QML_SUBDIR + '/';
+#endif
 }
 
 void QgsApplication::setPluginPath( const QString &pluginPath )
@@ -1001,6 +1008,11 @@ QString QgsApplication::libexecPath()
   return ABISYM( mLibexecPath );
 }
 
+QString QgsApplication::qmlImportPath()
+{
+  return ABISYM( mQmlImportPath );
+}
+
 QgsApplication::endian_t QgsApplication::endian()
 {
   return ( htonl( 1 ) == 1 ) ? XDR : NDR;

diff --git a/src/core/qgsapplication.h b/src/core/qgsapplication.h
@@ -405,6 +405,14 @@ class CORE_EXPORT QgsApplication : public QApplication
     //! Returns the path with utility executables (help viewer, crssync, ...)
     static QString libexecPath();
 
+    /**
+     * Returns the path where QML components are installed for QGIS Quick library. Returns
+     * empty string when QGIS is built without Quick support
+     *
+     * \since QGIS 3.2
+     */
+    static QString qmlImportPath();
+
     //! Alters prefix path - used by 3rd party apps
     static void setPrefixPath( const QString &prefixPath, bool useDefaultPaths = false );
 
@@ -752,6 +760,7 @@ class CORE_EXPORT QgsApplication : public QApplication
     static QString ABISYM( mPkgDataPath );
     static QString ABISYM( mLibraryPath );
     static QString ABISYM( mLibexecPath );
+    static QString ABISYM( mQmlImportPath );
     static QString ABISYM( mThemeName );
     static QStringList ABISYM( mDefaultSvgPaths );
     static QMap<QString, QString> ABISYM( mSystemEnvVars );

diff --git a/src/core/qgsrelationmanager.cpp b/src/core/qgsrelationmanager.cpp
@@ -25,9 +25,12 @@ QgsRelationManager::QgsRelationManager( QgsProject *project )
   : QObject( project )
   , mProject( project )
 {
-  connect( project, &QgsProject::readProject, this, &QgsRelationManager::readProject );
-  connect( project, &QgsProject::writeProject, this, &QgsRelationManager::writeProject );
-  connect( project, &QgsProject::layersRemoved, this, &QgsRelationManager::layersRemoved );
+  if ( mProject )
+  {
+    connect( project, &QgsProject::readProject, this, &QgsRelationManager::readProject );
+    connect( project, &QgsProject::writeProject, this, &QgsRelationManager::writeProject );
+    connect( project, &QgsProject::layersRemoved, this, &QgsRelationManager::layersRemoved );
+  }
 }
 
 void QgsRelationManager::setRelations( const QList<QgsRelation> &relations )
-Original file line number
+Diff line change
@@ Expand Up / @@ -37,3 +37,8 @@ Contains classes related to implementation of QGIS plugins. @@
     */
+    /** @defgroup quick QgsQuick library
+    The QgsQuick library is built on top of the CORE library and Qt Quick/QML framework. It adds reusable GUI Quick Components, mainly for mobile devices.
+    */