qgslayout.h

Go to the documentation of this file.

/***************************************************************************
                              qgslayout.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 QGSLAYOUT_H
#define QGSLAYOUT_H

#include "qgis_core.h"
#include <QGraphicsScene>
#include "qgslayoutsnapper.h"
#include "qgsexpressioncontextgenerator.h"
#include "qgslayoutgridsettings.h"
#include "qgslayoutguidecollection.h"
#include "qgslayoutexporter.h"
#include "qgsmasterlayoutinterface.h"

class QgsLayoutItemMap;
class QgsLayoutModel;
class QgsLayoutMultiFrame;
class QgsLayoutPageCollection;
class QgsLayoutUndoStack;
class QgsLayoutRenderContext;
class QgsLayoutReportContext;

class CORE_EXPORT QgsLayout : public QGraphicsScene, public QgsExpressionContextGenerator, public QgsLayoutUndoObjectInterface
{
    Q_OBJECT

  public:

    enum ZValues
    {
      ZPage = 0, 
      ZItem = 1, 
      ZGrid = 9997, 
      ZGuide = 9998, 
      ZSmartGuide = 9999, 
      ZMouseHandles = 10000, 
      ZViewTool = 10001, 
      ZSnapIndicator = 10002, 
    };

    enum UndoCommand
    {
      UndoLayoutDpi, 
      UndoNone = -1, 
    };

    QgsLayout( QgsProject *project );

    ~QgsLayout() override;

    QgsLayout *clone() const SIP_FACTORY;

    void initializeDefaults();

    void clear();

    QgsProject *project() const;

    QgsLayoutModel *itemsModel();

    template<class T> void layoutItems( QList<T *> &itemList ) const SIP_SKIP
    {
      itemList.clear();
      QList<QGraphicsItem *> graphicsItemList = items();
      QList<QGraphicsItem *>::iterator itemIt = graphicsItemList.begin();
      for ( ; itemIt != graphicsItemList.end(); ++itemIt )
      {
        T *item = dynamic_cast<T *>( *itemIt );
        if ( item )
        {
          itemList.push_back( item );
        }
      }
    }

    template<class T> void layoutObjects( QList<T *> &objectList ) const SIP_SKIP
    {
      objectList.clear();
      const QList<QGraphicsItem *> itemList( items() );
      const QList<QgsLayoutMultiFrame *> frameList( multiFrames() );
      for ( const auto &obj :  itemList )
      {
        T *item = dynamic_cast<T *>( obj );
        if ( item )
        {
          objectList.push_back( item );
        }
      }
      for ( const auto &obj :  frameList )
      {
        T *item = dynamic_cast<T *>( obj );
        if ( item )
        {
          objectList.push_back( item );
        }
      }
    }

    QList<QgsLayoutItem *> selectedLayoutItems( bool includeLockedItems = true );

    void setSelectedItem( QgsLayoutItem *item );

    void deselectAll();

    bool raiseItem( QgsLayoutItem *item, bool deferUpdate = false );

    bool lowerItem( QgsLayoutItem *item, bool deferUpdate = false );

    bool moveItemToTop( QgsLayoutItem *item, bool deferUpdate = false );

    bool moveItemToBottom( QgsLayoutItem *item, bool deferUpdate = false );

    void updateZValues( bool addUndoCommands = true );

    QgsLayoutItem *itemByUuid( const QString &uuid, bool includeTemplateUuids = false ) const;

    QgsLayoutItem *itemByTemplateUuid( const QString &uuid ) const;

    QgsLayoutItem *itemById( const QString &id ) const;

    QgsLayoutMultiFrame *multiFrameByUuid( const QString &uuid, bool includeTemplateUuids = false ) const;

    QgsLayoutItem *layoutItemAt( QPointF position, bool ignoreLocked = false ) const;

    QgsLayoutItem *layoutItemAt( QPointF position, const QgsLayoutItem *belowItem, bool ignoreLocked = false ) const;

    void setUnits( QgsUnitTypes::LayoutUnit units ) { mUnits = units; }

    QgsUnitTypes::LayoutUnit units() const { return mUnits; }

    double convertToLayoutUnits( const QgsLayoutMeasurement &measurement ) const;

    QSizeF convertToLayoutUnits( const QgsLayoutSize &size ) const;

    QPointF convertToLayoutUnits( const QgsLayoutPoint &point ) const;

    QgsLayoutMeasurement convertFromLayoutUnits( double length, QgsUnitTypes::LayoutUnit unit ) const;

    QgsLayoutSize convertFromLayoutUnits( const QSizeF &size, QgsUnitTypes::LayoutUnit unit ) const;

    QgsLayoutPoint convertFromLayoutUnits( const QPointF &point, QgsUnitTypes::LayoutUnit unit ) const;

    QgsLayoutRenderContext &renderContext();

    SIP_SKIP const QgsLayoutRenderContext &renderContext() const;

    QgsLayoutReportContext &reportContext();

    SIP_SKIP const QgsLayoutReportContext &reportContext() const;

    QgsLayoutSnapper &snapper() { return mSnapper; }

    SIP_SKIP const QgsLayoutSnapper &snapper() const { return mSnapper; }

    QgsLayoutGridSettings &gridSettings() { return mGridSettings; }

    SIP_SKIP const QgsLayoutGridSettings &gridSettings() const { return mGridSettings; }

    void reloadSettings();

    QgsLayoutGuideCollection &guides();

    SIP_SKIP const QgsLayoutGuideCollection &guides() const;

    QgsExpressionContext createExpressionContext() const override;

    void setCustomProperty( const QString &key, const QVariant &value );

    QVariant customProperty( const QString &key, const QVariant &defaultValue = QVariant() ) const;

    void removeCustomProperty( const QString &key );

    QStringList customProperties() const;

    QgsLayoutItemMap *referenceMap() const;

    void setReferenceMap( QgsLayoutItemMap *map );

    QgsLayoutPageCollection *pageCollection();

    SIP_SKIP const QgsLayoutPageCollection *pageCollection() const;

    QRectF layoutBounds( bool ignorePages = false, double margin = 0.0 ) const;

    QRectF pageItemBounds( int page, bool visibleOnly = false ) const;

    void addLayoutItem( QgsLayoutItem *item SIP_TRANSFER );

    void removeLayoutItem( QgsLayoutItem *item );

    void addMultiFrame( QgsLayoutMultiFrame *multiFrame SIP_TRANSFER );

    void removeMultiFrame( QgsLayoutMultiFrame *multiFrame );

    QList< QgsLayoutMultiFrame * > multiFrames() const;

    bool saveAsTemplate( const QString &path, const QgsReadWriteContext &context ) const;

    QList< QgsLayoutItem * > loadFromTemplate( const QDomDocument &document, const QgsReadWriteContext &context, bool clearExisting = true, bool *ok SIP_OUT = nullptr );

    virtual QDomElement writeXml( QDomDocument &document, const QgsReadWriteContext &context ) const;

    virtual bool readXml( const QDomElement &layoutElement, const QDomDocument &document, const QgsReadWriteContext &context );

    QList< QgsLayoutItem * > addItemsFromXml( const QDomElement &parentElement, const QDomDocument &document,
        const QgsReadWriteContext &context,
        QPointF *position = nullptr, bool pasteInPlace = false );

    QgsLayoutUndoStack *undoStack();

    SIP_SKIP const QgsLayoutUndoStack *undoStack() const;

    QgsAbstractLayoutUndoCommand *createCommand( const QString &text, int id = 0, QUndoCommand *parent = nullptr ) SIP_FACTORY override;

    QgsLayoutItemGroup *groupItems( const QList<QgsLayoutItem *> &items );

    QList<QgsLayoutItem *> ungroupItems( QgsLayoutItemGroup *group );

  public slots:

    void refresh();

    void updateBounds();

  signals:

    void changed();

    void variablesChanged();

    void selectedItemChanged( QgsLayoutItem *selected );

    void refreshed();

  private:

    QgsProject *mProject = nullptr;
    std::unique_ptr< QgsLayoutModel > mItemsModel;

    QgsObjectCustomProperties mCustomProperties;

    QgsUnitTypes::LayoutUnit mUnits = QgsUnitTypes::LayoutMillimeters;
    QgsLayoutRenderContext *mRenderContext = nullptr;
    QgsLayoutReportContext *mReportContext = nullptr;
    QgsLayoutSnapper mSnapper;
    QgsLayoutGridSettings mGridSettings;

    std::unique_ptr< QgsLayoutPageCollection > mPageCollection;
    std::unique_ptr< QgsLayoutUndoStack > mUndoStack;

    QList<QgsLayoutMultiFrame *> mMultiFrames;

    QString mWorldFileMapId;

    void writeXmlLayoutSettings( QDomElement &element, QDomDocument &document, const QgsReadWriteContext &context ) const;
    bool readXmlLayoutSettings( const QDomElement &layoutElement, const QDomDocument &document, const QgsReadWriteContext &context );

    void addLayoutItemPrivate( QgsLayoutItem *item );

    void removeLayoutItemPrivate( QgsLayoutItem *item );

    void deleteAndRemoveMultiFrames();

    QPointF minPointFromXml( const QDomElement &elem ) const;

    friend class QgsLayoutItemAddItemCommand;
    friend class QgsLayoutItemDeleteUndoCommand;
    friend class QgsLayoutItemUndoCommand;
    friend class QgsLayoutUndoCommand;
    friend class QgsLayoutItemGroupUndoCommand;
    friend class QgsLayoutModel;
    friend class QgsLayoutMultiFrame;
    friend class QgsCompositionConverter;
};

#endif //QGSLAYOUT_H