Skip to content

Commit

Permalink
[FEATURE] Introduction of QGIS Quick library
Browse files Browse the repository at this point in the history
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!
  • Loading branch information
PeterPetrik committed Apr 26, 2018
1 parent f816588 commit b1bf9b2
Show file tree
Hide file tree
Showing 37 changed files with 3,287 additions and 3 deletions.
1 change: 1 addition & 0 deletions .ci/travis/linux/docker-build-test.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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 \
Expand Down
8 changes: 8 additions & 0 deletions .docker/qgis3-build-deps.dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -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 \
Expand Down Expand Up @@ -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 \
Expand Down
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
22 changes: 22 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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})
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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)

Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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")

Expand All @@ -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})

Expand Down
47 changes: 47 additions & 0 deletions cmake/FindQtQmlTools.cmake
Original file line number Diff line number Diff line change
@@ -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)
3 changes: 3 additions & 0 deletions cmake_templates/qgsconfig.h.in
Original file line number Diff line number Diff line change
Expand Up @@ -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}"

Expand Down Expand Up @@ -64,5 +65,7 @@

#cmakedefine QGISDEBUG

#cmakedefine HAVE_QUICK

#endif

2 changes: 2 additions & 0 deletions doc/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
1 change: 1 addition & 0 deletions doc/CONTRIBUTORS
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,7 @@ Nikos Alexandris
Paolo Cavallini
Paul Blottiere
Paul Ramsey
Peter Petrik
Pierre Auckenthaler
Raymond Nijssen
Richard Duivenvoorde
Expand Down
4 changes: 4 additions & 0 deletions doc/index.dox
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 5 additions & 0 deletions doc/modules.dox
Original file line number Diff 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.

*/
61 changes: 61 additions & 0 deletions doc/qgsquick.dox
Original file line number Diff line number Diff line change
@@ -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.

*/


8 changes: 8 additions & 0 deletions python/core/qgsapplication.sip.in
Original file line number Diff line number Diff line change
Expand Up @@ -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 );
Expand Down
3 changes: 3 additions & 0 deletions src/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -35,3 +35,6 @@ IF (WITH_CUSTOM_WIDGETS)
ADD_SUBDIRECTORY(customwidgets)
ENDIF (WITH_CUSTOM_WIDGETS)

IF (WITH_QUICK)
ADD_SUBDIRECTORY(quickgui)
ENDIF (WITH_QUICK)
12 changes: 12 additions & 0 deletions src/core/qgsapplication.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -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 );
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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 )
Expand Down Expand Up @@ -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;
Expand Down
9 changes: 9 additions & 0 deletions src/core/qgsapplication.h
Original file line number Diff line number Diff line change
Expand Up @@ -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 );

Expand Down Expand Up @@ -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 );
Expand Down
9 changes: 6 additions & 3 deletions src/core/qgsrelationmanager.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -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 )
Expand Down

0 comments on commit b1bf9b2

Please sign in to comment.