qgslayoutitemregistry.h

Go to the documentation of this file.

/***************************************************************************
                            qgslayoutitemregistry.h
                            ------------------------
    begin                : June 2017
    copyright            : (C) 2017 by Nyall Dawson
    email                : nyall dot dawson at gmail dot com
 ***************************************************************************/
/***************************************************************************
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 ***************************************************************************/
#ifndef QGSLAYOUTITEMREGISTRY_H
#define QGSLAYOUTITEMREGISTRY_H
 
#include <functional>
 
#include "qgis_core.h"
#include "qgis_sip.h"
#include "qgsapplication.h"
#include "qgslayoutitem.h"
#include "qgspathresolver.h"
 
#include <QGraphicsItem>
#include <QIcon>
#include <QString>
 
using namespace Qt::StringLiterals;
 
class QgsLayout;
class QgsLayoutView;
class QgsLayoutItem;
class QgsFillSymbol;
class QgsLayoutMultiFrame;

class CORE_EXPORT QgsLayoutItemAbstractMetadata
{
  public:
    QgsLayoutItemAbstractMetadata( int type, const QString &visibleName, const QString &visiblePluralName = QString() )
      : mType( type )
      , mVisibleName( visibleName )
      , mVisibleNamePlural( visiblePluralName.isEmpty() ? visibleName : visiblePluralName )
    {}
 
    virtual ~QgsLayoutItemAbstractMetadata() = default;

    int type() const { return mType; }

    QString visibleName() const { return mVisibleName; }

    QString visiblePluralName() const { return mVisibleNamePlural; }
 
    /*
     * IMPORTANT: While it seems like /Factory/ would be the correct annotations here, that's not
     * the case.
     * As per Phil Thomson's advice on https://www.riverbankcomputing.com/pipermail/pyqt/2017-July/039450.html:
     *
     * "
     * /Factory/ is used when the instance returned is guaranteed to be new to Python.
     * In this case it isn't because it has already been seen when being returned by QgsProcessingAlgorithm::createInstance()
     * (However for a different sub-class implemented in C++ then it would be the first time it was seen
     * by Python so the /Factory/ on create() would be correct.)
     *
     * You might try using /TransferBack/ on create() instead - that might be the best compromise.
     * "
     */

    virtual QgsLayoutItem *createItem( QgsLayout *layout ) = 0 SIP_TRANSFERBACK;

    virtual void resolvePaths( QVariantMap &properties, const QgsPathResolver &pathResolver, bool saving )
    {
      Q_UNUSED( properties )
      Q_UNUSED( pathResolver )
      Q_UNUSED( saving )
    }
 
  private:
    int mType = -1;
    QString mVisibleName;
    QString mVisibleNamePlural;
};

typedef std::function<QgsLayoutItem *( QgsLayout * )> QgsLayoutItemCreateFunc SIP_SKIP;

typedef std::function<void( QVariantMap &, const QgsPathResolver &, bool )> QgsLayoutItemPathResolverFunc SIP_SKIP;
 
#ifndef SIP_RUN

class CORE_EXPORT QgsLayoutItemMetadata : public QgsLayoutItemAbstractMetadata
{
  public:
    QgsLayoutItemMetadata( int type, const QString &visibleName, const QString &visiblePluralName, const QgsLayoutItemCreateFunc &pfCreate, const QgsLayoutItemPathResolverFunc &pfPathResolver = nullptr )
      : QgsLayoutItemAbstractMetadata( type, visibleName, visiblePluralName )
      , mCreateFunc( pfCreate )
      , mPathResolverFunc( pfPathResolver )
    {}

    QgsLayoutItemCreateFunc createFunction() const { return mCreateFunc; }

    QgsLayoutItemPathResolverFunc pathResolverFunction() const { return mPathResolverFunc; }
 
    QgsLayoutItem *createItem( QgsLayout *layout ) override { return mCreateFunc ? mCreateFunc( layout ) : nullptr; }
 
    void resolvePaths( QVariantMap &properties, const QgsPathResolver &pathResolver, bool saving ) override
    {
      if ( mPathResolverFunc )
        mPathResolverFunc( properties, pathResolver, saving );
    }
 
  protected:
    QgsLayoutItemCreateFunc mCreateFunc = nullptr;
    QgsLayoutItemPathResolverFunc mPathResolverFunc = nullptr;
};
 
#endif

class CORE_EXPORT QgsLayoutMultiFrameAbstractMetadata
{
  public:
    QgsLayoutMultiFrameAbstractMetadata( int type, const QString &visibleName )
      : mType( type )
      , mVisibleName( visibleName )
    {}
 
    virtual ~QgsLayoutMultiFrameAbstractMetadata() = default;

    int type() const { return mType; }

    virtual QIcon icon() const { return QgsApplication::getThemeIcon( u"/mActionAddBasicRectangle.svg"_s ); }

    QString visibleName() const { return mVisibleName; }
 
    /*
     * IMPORTANT: While it seems like /Factory/ would be the correct annotations here, that's not
     * the case.
     * As per Phil Thomson's advice on https://www.riverbankcomputing.com/pipermail/pyqt/2017-July/039450.html:
     *
     * "
     * /Factory/ is used when the instance returned is guaranteed to be new to Python.
     * In this case it isn't because it has already been seen when being returned by QgsProcessingAlgorithm::createInstance()
     * (However for a different sub-class implemented in C++ then it would be the first time it was seen
     * by Python so the /Factory/ on create() would be correct.)
     *
     * You might try using /TransferBack/ on create() instead - that might be the best compromise.
     * "
     */

    virtual QgsLayoutMultiFrame *createMultiFrame( QgsLayout *layout ) = 0 SIP_TRANSFERBACK;

    virtual void resolvePaths( QVariantMap &properties, const QgsPathResolver &pathResolver, bool saving )
    {
      Q_UNUSED( properties )
      Q_UNUSED( pathResolver )
      Q_UNUSED( saving )
    }
 
  private:
    int mType = -1;
    QString mVisibleName;
};

typedef std::function<QgsLayoutMultiFrame *( QgsLayout * )> QgsLayoutMultiFrameCreateFunc SIP_SKIP;

typedef std::function<void( QVariantMap &, const QgsPathResolver &, bool )> QgsLayoutMultiFramePathResolverFunc SIP_SKIP;
 
#ifndef SIP_RUN

class CORE_EXPORT QgsLayoutMultiFrameMetadata : public QgsLayoutMultiFrameAbstractMetadata
{
  public:
    QgsLayoutMultiFrameMetadata( int type, const QString &visibleName, const QgsLayoutMultiFrameCreateFunc &pfCreate, const QgsLayoutMultiFramePathResolverFunc &pfPathResolver = nullptr )
      : QgsLayoutMultiFrameAbstractMetadata( type, visibleName )
      , mCreateFunc( pfCreate )
      , mPathResolverFunc( pfPathResolver )
    {}

    QgsLayoutMultiFrameCreateFunc createFunction() const { return mCreateFunc; }

    QgsLayoutMultiFramePathResolverFunc pathResolverFunction() const { return mPathResolverFunc; }
 
    QgsLayoutMultiFrame *createMultiFrame( QgsLayout *layout ) override { return mCreateFunc ? mCreateFunc( layout ) : nullptr; }
 
    void resolvePaths( QVariantMap &properties, const QgsPathResolver &pathResolver, bool saving ) override
    {
      if ( mPathResolverFunc )
        mPathResolverFunc( properties, pathResolver, saving );
    }
 
  protected:
    QgsLayoutMultiFrameCreateFunc mCreateFunc = nullptr;
    QgsLayoutMultiFramePathResolverFunc mPathResolverFunc = nullptr;
};
 
#endif
 

class CORE_EXPORT QgsLayoutItemRegistry : public QObject
{
    Q_OBJECT
 
  public:
    enum ItemType
    {
      LayoutItem = QGraphicsItem::UserType + 100, 
      LayoutGroup,                                
 
      // known item types
 
      // WARNING!!!! SIP CASTING OF QgsLayoutItem and QgsLayoutMultiFrame DEPENDS on these
      // values, and must be updated if any additional types are added
 
      LayoutPage,     
      LayoutMap,      
      LayoutPicture,  
      LayoutLabel,    
      LayoutLegend,   
      LayoutShape,    
      LayoutPolygon,  
      LayoutPolyline, 
      LayoutScaleBar, 
      LayoutFrame,    
 
      // known multi-frame types
 
      // WARNING!!!! SIP CASTING OF QgsLayoutItem and QgsLayoutMultiFrame DEPENDS on these
      // values, and must be updated if any additional types are added
 
      LayoutHtml,           
      LayoutAttributeTable, 
      LayoutTextTable,      
 
      Layout3DMap, 
 
      LayoutManualTable, 
      LayoutMarker,      
 
      LayoutElevationProfile, 
 
      LayoutChart, 
 
      // WARNING!!!! SIP CASTING OF QgsLayoutItem and QgsLayoutMultiFrame DEPENDS on these
      // values, and must be updated if any additional types are added
 
      // item types provided by plugins
      PluginItem = LayoutTextTable + 10000, 
    };

    QgsLayoutItemRegistry( QObject *parent = nullptr );
 
    ~QgsLayoutItemRegistry() override;

    bool populate();
 
    QgsLayoutItemRegistry( const QgsLayoutItemRegistry &rh ) = delete;
    QgsLayoutItemRegistry &operator=( const QgsLayoutItemRegistry &rh ) = delete;

    QgsLayoutItemAbstractMetadata *itemMetadata( int type ) const;

    QgsLayoutMultiFrameAbstractMetadata *multiFrameMetadata( int type ) const;
 
    /*
     * IMPORTANT: While it seems like /Factory/ would be the correct annotations here, that's not
     * the case.
     * As per Phil Thomson's advice on https://www.riverbankcomputing.com/pipermail/pyqt/2017-July/039450.html:
     *
     * "
     * /Factory/ is used when the instance returned is guaranteed to be new to Python.
     * In this case it isn't because it has already been seen when being returned by QgsProcessingAlgorithm::createInstance()
     * (However for a different sub-class implemented in C++ then it would be the first time it was seen
     * by Python so the /Factory/ on create() would be correct.)
     *
     * You might try using /TransferBack/ on create() instead - that might be the best compromise.
     * "
     */

    bool addLayoutItemType( QgsLayoutItemAbstractMetadata *metadata SIP_TRANSFER );

    bool removeLayoutItemType( int typeId );

    bool removeLayoutItemType( QgsLayoutItemAbstractMetadata *metadata );

    bool removeLayoutMultiFrameType( int typeId );

    bool removeLayoutMultiFrameType( QgsLayoutMultiFrameAbstractMetadata *metadata );

    bool addLayoutMultiFrameType( QgsLayoutMultiFrameAbstractMetadata *metadata SIP_TRANSFER );

    QgsLayoutItem *createItem( int type, QgsLayout *layout ) const SIP_TRANSFERBACK;

    QgsLayoutMultiFrame *createMultiFrame( int type, QgsLayout *layout ) const SIP_TRANSFERBACK;

    void resolvePaths( int type, QVariantMap &properties, const QgsPathResolver &pathResolver, bool saving ) const;

    QMap< int, QString> itemTypes() const;
 
  signals:

    void typeAdded( int type, const QString &name );

    void typeRemoved( int type );

    void multiFrameTypeAdded( int type, const QString &name );

    void multiFrameTypeRemoved( int type );
 
  private:
#ifdef SIP_RUN
    QgsLayoutItemRegistry( const QgsLayoutItemRegistry &rh );
#endif
 
    QMap<int, QgsLayoutItemAbstractMetadata *> mMetadata;
    QMap<int, QgsLayoutMultiFrameAbstractMetadata *> mMultiFrameMetadata;
};
 
#if 0
#ifndef SIP_RUN
//simple item for testing
#ifdef ANDROID
// For some reason, the Android NDK toolchain requires this to link properly.
// Note to self: Please try to remove this again once Qt ships their libs built with gcc-5
class CORE_EXPORT TestLayoutItem : public QgsLayoutItem
#else
class TestLayoutItem : public QgsLayoutItem
#endif
{
    Q_OBJECT
 
  public:
 
    TestLayoutItem( QgsLayout *layout );
    ~TestLayoutItem() = default;
 
    //implement pure virtual methods
    int type() const override { return QgsLayoutItemRegistry::LayoutItem + 1002; }
    void draw( QgsRenderContext &context, const QStyleOptionGraphicsItem *itemStyle = nullptr ) override;
 
  private:
    QColor mColor;
    QgsFillSymbol *mShapeStyleSymbol = nullptr;
};
#endif
#endif
 
#endif //QGSLAYOUTITEMREGISTRY_H