Skip to content
Permalink
Browse files

Expand docs

  • Loading branch information
nyalldawson committed Sep 15, 2017
1 parent 3c3848a commit 06ee6f68e1d6b70453034ad56993d2df3c0ab879
Showing with 76 additions and 21 deletions.
  1. +32 −9 python/gui/qgscustomdrophandler.sip
  2. +2 −2 src/app/qgisapp.cpp
  3. +6 −1 src/gui/qgscustomdrophandler.cpp
  4. +36 −9 src/gui/qgscustomdrophandler.h
@@ -12,12 +12,25 @@ class QgsCustomDropHandler : QObject
{
%Docstring
Abstract base class that may be implemented to handle new types of data to be dropped in QGIS.
Implementations will be used when a QgsMimeDataUtils.Uri has layerType equal to "custom",
and the providerKey is equal to key() returned by the implementation.

Alternatively, implementations can override the handleMimeData() or handleFileDrop()
methods to handle QMimeData and file drops directly. Reimplementation of these methods
does not rely on key() matching.
Implementations have three approaches they can use to handle drops.

1. The simplest approach is to implement handeFileDrop() when they need to handle
dropped files (i.e. with mime type "text/uri-list").

2. Reimplement handleCustomUriDrop() when they want to handle dropped custom
QgsMimeDataUtils.Uri entries, for instance handling dropping custom entries
from the browser tree (with mime type "application/x-vnd.qgis.qgis.uri"). In
this case the implementation's customUriProviderKey() must match the uri
entry's providerKey.

3. Reimplement handleMimeData() to directly handle dropped QMimeData.
Subclasses should take care when overriding this method. When a drop event
occurs, Qt will lock the source application of the drag for the duration
of the drop event handling via handleMimeData() (e.g. dragging files from
explorer to QGIS will lock the explorer window until the drop handling has
been complete). Accordingly handleMimeData() implementations must return
quickly and defer any intensive or slow processing.

.. versionadded:: 3.0
%End
@@ -28,15 +41,25 @@ class QgsCustomDropHandler : QObject
public:
virtual ~QgsCustomDropHandler();

virtual QString key() const = 0;
virtual QString customUriProviderKey() const;
%Docstring
Type of custom URI recognized by the handler
Type of custom URI recognized by the handler. This must match
the URI entry's providerKey in order for handleCustomUriDrop()
to be called.

.. seealso:: handleCustomUriDrop()
:rtype: str
%End

virtual void handleDrop( const QgsMimeDataUtils::Uri &uri ) const;
virtual void handleCustomUriDrop( const QgsMimeDataUtils::Uri &uri ) const;
%Docstring
Method called from QGIS after a drop event with custom URI known by the handler
Called from QGIS after a drop event with custom URI known by the handler.

In order for handleCustomUriDrop() to be called, subclasses must
also implement customUriProviderKey() to indicate the providerKey
value which the handler accepts.

.. seealso:: customUriProviderKey()
%End

virtual void handleMimeData( const QMimeData *data );
@@ -1491,9 +1491,9 @@ void QgisApp::handleDropUriList( const QgsMimeDataUtils::UriList &lst )
{
Q_FOREACH ( QgsCustomDropHandler *handler, mCustomDropHandlers )
{
if ( handler && handler->key() == u.providerKey )
if ( handler && handler->customUriProviderKey() == u.providerKey )
{
handler->handleDrop( u );
handler->handleCustomUriDrop( u );
break;
}
}
@@ -15,7 +15,12 @@

#include "qgscustomdrophandler.h"

void QgsCustomDropHandler::handleDrop( const QgsMimeDataUtils::Uri &uri ) const
QString QgsCustomDropHandler::customUriProviderKey() const
{
return QString();
}

void QgsCustomDropHandler::handleCustomUriDrop( const QgsMimeDataUtils::Uri &uri ) const
{
Q_UNUSED( uri );
}
@@ -21,12 +21,25 @@

/** \ingroup gui
* Abstract base class that may be implemented to handle new types of data to be dropped in QGIS.
* Implementations will be used when a QgsMimeDataUtils::Uri has layerType equal to "custom",
* and the providerKey is equal to key() returned by the implementation.
*
* Alternatively, implementations can override the handleMimeData() or handleFileDrop()
* methods to handle QMimeData and file drops directly. Reimplementation of these methods
* does not rely on key() matching.
* Implementations have three approaches they can use to handle drops.
*
* 1. The simplest approach is to implement handeFileDrop() when they need to handle
* dropped files (i.e. with mime type "text/uri-list").
*
* 2. Reimplement handleCustomUriDrop() when they want to handle dropped custom
* QgsMimeDataUtils::Uri entries, for instance handling dropping custom entries
* from the browser tree (with mime type "application/x-vnd.qgis.qgis.uri"). In
* this case the implementation's customUriProviderKey() must match the uri
* entry's providerKey.
*
* 3. Reimplement handleMimeData() to directly handle dropped QMimeData.
* Subclasses should take care when overriding this method. When a drop event
* occurs, Qt will lock the source application of the drag for the duration
* of the drop event handling via handleMimeData() (e.g. dragging files from
* explorer to QGIS will lock the explorer window until the drop handling has
* been complete). Accordingly handleMimeData() implementations must return
* quickly and defer any intensive or slow processing.
*
* \since QGIS 3.0
*/
@@ -37,11 +50,25 @@ class GUI_EXPORT QgsCustomDropHandler : public QObject
public:
virtual ~QgsCustomDropHandler() = default;

//! Type of custom URI recognized by the handler
virtual QString key() const = 0;
/**
* Type of custom URI recognized by the handler. This must match
* the URI entry's providerKey in order for handleCustomUriDrop()
* to be called.
*
* \see handleCustomUriDrop()
*/
virtual QString customUriProviderKey() const;

//! Method called from QGIS after a drop event with custom URI known by the handler
virtual void handleDrop( const QgsMimeDataUtils::Uri &uri ) const;
/**
* Called from QGIS after a drop event with custom URI known by the handler.
*
* In order for handleCustomUriDrop() to be called, subclasses must
* also implement customUriProviderKey() to indicate the providerKey
* value which the handler accepts.
*
* \see customUriProviderKey()
*/
virtual void handleCustomUriDrop( const QgsMimeDataUtils::Uri &uri ) const;

/**
* Called when the specified mime \a data has been dropped onto QGIS.

0 comments on commit 06ee6f6

Please sign in to comment.
You can’t perform that action at this time.