QGIS Quick library [dockerdeps]

.ci/travis/linux/docker-build-test.sh

@@ -40,6 +40,7 @@ echo "${bold}Running cmake...${endbold}"
 cmake \
  -GNinja \
  -DWITH_3D=ON \
+ -DWITH_QUICK=ON \
  -DWITH_STAGED_PLUGINS=ON \
  -DWITH_GRASS=OFF \
  -DSUPPRESS_QT_WARNINGS=ON \

.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 \

.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

CMakeLists.txt

@@ -61,6 +61,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)
@@ -302,6 +304,15 @@ 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")
+  ENDIF (WITH_QUICK)
 
   IF(WITH_QTWEBKIT)
     SET(OPTIONAL_QTWEBKIT ${Qt5WebKitWidgets_LIBRARIES})
@@ -353,6 +364,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
@@ -493,6 +507,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)
 
@@ -563,6 +578,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)
@@ -590,6 +606,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)
@@ -638,12 +655,13 @@ 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")
 
 # mark *_SUBDIR variables as advanced as this is not something
 # that an average user would use
-MARK_AS_ADVANCED (QGIS_BIN_SUBDIR QGIS_CGIBIN_SUBDIR QGIS_LIB_SUBDIR QGIS_LIBEXEC_SUBDIR QGIS_DATA_SUBDIR QGIS_PLUGIN_SUBDIR QGIS_INCLUDE_SUBDIR)
+MARK_AS_ADVANCED (QGIS_BIN_SUBDIR QGIS_CGIBIN_SUBDIR QGIS_LIB_SUBDIR QGIS_LIBEXEC_SUBDIR QGIS_DATA_SUBDIR QGIS_PLUGIN_SUBDIR QGIS_INCLUDE_SUBDIR QGIS_QML_SUBDIR)
 
 # full paths for the installation
 SET (QGIS_BIN_DIR     ${QGIS_BIN_SUBDIR})
@@ -653,6 +671,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})
 

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)

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}"
 

doc/CMakeLists.txt

@@ -99,6 +99,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)

doc/CONTRIBUTORS

@@ -71,6 +71,7 @@ Nikos Alexandris
 Paolo Cavallini
 Paul Blottiere
 Paul Ramsey
+Peter Petrik
 Pierre Auckenthaler
 Raymond Nijssen
 Richard Duivenvoorde
@@ -85,6 +86,7 @@ Tamas Szekeres
 Tom Russo
 Tyler Mitchell
 Vita Cizek
+Viktor Sklencar
 Yann Chemin
 Yves Jacolin
 

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

doc/modules.dox

@@ -6,7 +6,7 @@ The CORE library contains all basic GIS functionality.
 
 /** @defgroup gui gui library
 
-The GUI library is build on top of the CORE library and adds reusable GUI widgets.
+The GUI library is built on top of the CORE library and adds reusable GUI widgets.
 
 */
 
@@ -27,7 +27,7 @@ components to QGIS.
 
 /** @defgroup 3d 3D library
 
-The 3D library is build on top of the CORE library and Qt 3D framework. It adds support for display of GIS data in 3D scenes.
+The 3D library is built on top of the CORE library and Qt 3D framework. It adds support for display of GIS data in 3D scenes.
 
 */
 
@@ -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.
+
+*/

doc/qgsquick.dox

@@ -0,0 +1,66 @@
+/*! \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
+\subsubsection qgsquick_overview_widgets_featureform FeatureForm
+\subsubsection qgsquick_overview_widgets_positionmarker PositionMarker
+\subsubsection qgsquick_overview_widgets_scalebar ScaleBar
+\subsubsection qgsquick_overview_widgets_messagelog MessageLog
+\subsubsection qgsquick_overview_widgets_photocapture PhotoCapture
+
+\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.
+
+*/
+
+

python/core/qgsapplication.sip.in

@@ -432,6 +432,13 @@ 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
+
+.. versionadded:: 3.2
 %End
 
     static void setPrefixPath( const QString &prefixPath, bool useDefaultPaths = false );

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)

src/core/qgsapplication.cpp

@@ -89,6 +89,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,7 @@ void QgsApplication::init( QString profileFolder )
 #else
     ABISYM( mLibexecPath ) = ABISYM( mBuildOutputPath ) + '/' + QGIS_LIBEXEC_SUBDIR + '/';
 #endif
+    ABISYM( mQmlImportPath ) = ABISYM( mBuildOutputPath ) + '/' + QGIS_QML_SUBDIR + '/';
   }
   else
   {
@@ -384,6 +386,7 @@ void QgsApplication::setPrefixPath( const QString &prefixPath, bool useDefaultPa
   }
   ABISYM( mLibraryPath ) = ABISYM( mPrefixPath ) + '/' + QGIS_LIB_SUBDIR + '/';
   ABISYM( mLibexecPath ) = ABISYM( mPrefixPath ) + '/' + QGIS_LIBEXEC_SUBDIR + '/';
+  ABISYM( mQmlImportPath ) = ABISYM( mPrefixPath ) + '/' + QGIS_QML_SUBDIR + '/';
 }
 
 void QgsApplication::setPluginPath( const QString &pluginPath )
@@ -989,6 +992,11 @@ QString QgsApplication::libexecPath()
   return ABISYM( mLibexecPath );
 }
 
+QString QgsApplication::qmlImportPath()
+{
+  return ABISYM( mQmlImportPath );
+}
+
 QgsApplication::endian_t QgsApplication::endian()
 {
   return ( htonl( 1 ) == 1 ) ? XDR : NDR;

src/core/qgsapplication.h

@@ -404,6 +404,12 @@ 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
+     * \since QGIS 3.2
+     */
+    static QString qmlImportPath();
+
     //! Alters prefix path - used by 3rd party apps
     static void setPrefixPath( const QString &prefixPath, bool useDefaultPaths = false );
 
@@ -745,6 +751,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 );