qgslayoutguidecollection.h

/***************************************************************************
                             qgslayoutguidecollection.h
                             --------------------------
    begin                : July 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 QGSLAYOUTGUIDECOLLECTION_H
#define QGSLAYOUTGUIDECOLLECTION_H

#include "qgis_core.h"
#include "qgslayoutmeasurement.h"
#include "qgslayoutpoint.h"
#include <QPen>
#include <QAbstractListModel>
#include <QSortFilterProxyModel>
#include <QGraphicsLineItem>
#include <memory>

class QgsLayout;

/**
 * \ingroup core
 * \class QgsLayoutGuide
 * \brief Contains the configuration for a single snap guide used by a layout.
 * \since QGIS 3.0
 */
class CORE_EXPORT QgsLayoutGuide : public QObject
{

    Q_OBJECT

  public:

    //! Guide orientation
    enum Orientation
    {
      Horizontal, //!< Horizontal guide
      Vertical, //!< Vertical guide
    };

    /**
     * Constructor for a new guide with the specified \a orientation and
     * initial \a position.
     *
     * A layout must be set by calling setLayout() before the guide can be used.
     * Adding the guide to a QgsLayoutGuideCollection will automatically set
     * the corresponding layout for you.
     */
    QgsLayoutGuide( Orientation orientation, const QgsLayoutMeasurement &position );

    /**
     * Returns the layout the guide belongs to.
     * \see setLayout()
     */
    QgsLayout *layout() const;

    /**
     * Sets the \a layout the guide belongs to.
     *
     * \note Adding the guide to a QgsLayoutGuideCollection will automatically set
     * the corresponding layout for you.
     *
     * \see layout()
     */
    void setLayout( QgsLayout *layout );

    /**
     * Returns the guide's orientation.
     */
    Orientation orientation() const;

    /**
     * Returns the guide's position within the page.
     *
     * The position indicates either the horizontal or vertical position
     * of the guide, depending on the guide's orientation().
     *
     * \see setPosition()
     */
    QgsLayoutMeasurement position() const;

    /**
     * Sets the guide's \a position within the page.
     *
     * The \a position argument indicates either the horizontal or vertical position
     * of the guide, depending on the guide's orientation().
     *
     * \see position()
     */
    void setPosition( const QgsLayoutMeasurement &position );

    /**
     * Returns the page number of the guide.
     *
     * Page numbering begins at 0.
     *
     * \see setPage()
     */
    int page() const;

    /**
     * Sets the \a page number of the guide.
     *
     * Page numbering begins at 0.
     *
     * \see page()
     */
    void setPage( int page );

    /**
     * Updates the position of the guide's line item.
     */
    void update();

    /**
     * Returns the guide's line item.
     */
    QGraphicsLineItem *item();

    /**
     * Returns the guide's position in absolute layout units.
     */
    double layoutPosition() const;

  signals:

    /**
     * Emitted when the guide's position is changed.
     */
    void positionChanged();

  private:

    Orientation mOrientation = Vertical;

    //! Horizontal/vertical position of guide on page
    QgsLayoutMeasurement mPosition;

    //! Page number, 0 index based
    int mPage = 0;

    QgsLayout *mLayout = nullptr;

    //! Line item used in scene for guide
    std::unique_ptr< QGraphicsLineItem > mLineItem;

};

/**
 * \ingroup core
 * \class QgsLayoutGuideCollection
 * \brief Stores and manages the snap guides used by a layout.
 * \since QGIS 3.0
 */
class CORE_EXPORT QgsLayoutGuideCollection : public QAbstractTableModel
{

    Q_OBJECT

  public:

    //! Model roles
    enum Roles
    {
      OrientationRole = Qt::UserRole, //!< Guide orientation role
      PositionRole, //!< Guide position role
      UnitsRole, //!< Guide position units role
      PageRole, //!< Guide page role
      LayoutPositionRole, //!< Guide position in layout coordinates
    };

    /**
     * Constructor for QgsLayoutGuideCollection belonging to the specified layout.
     */
    QgsLayoutGuideCollection( QgsLayout *layout );
    ~QgsLayoutGuideCollection();

    int rowCount( const QModelIndex & ) const override;
    int columnCount( const QModelIndex & ) const override;
    QVariant data( const QModelIndex &index, int role ) const override;
    bool setData( const QModelIndex &index, const QVariant &value, int role ) override;
    Qt::ItemFlags flags( const QModelIndex &index ) const override;
    QVariant headerData( int section, Qt::Orientation orientation,
                         int role = Qt::DisplayRole ) const override;
    bool removeRows( int row, int count, const QModelIndex &parent = QModelIndex() ) override;

    /**
     * Adds a \a guide to the collection. Ownership of the guide is transferred to the
     * collection, and the guide will automatically have the correct layout
     * set.
     */
    void addGuide( QgsLayoutGuide *guide SIP_TRANSFER );

    /**
     * Updates the position (and visibility) of all guide line items.
     */
    void update();

    /**
     * Returns the list of guides contained in the collection with the specified
     * \a orientation.
     */
    QList< QgsLayoutGuide * > guides( QgsLayoutGuide::Orientation orientation );

  private:

    QgsLayout *mLayout = nullptr;

    QList< QgsLayoutGuide * > mGuides;
    int mHeaderSize = 0;

};


/**
 * \ingroup core
 * \class QgsLayoutGuideProxyModel
 * \brief Filters QgsLayoutGuideCollection models to guides of a single orientation (horizontal or vertical).
 * \since QGIS 3.0
 */
class CORE_EXPORT QgsLayoutGuideProxyModel : public QSortFilterProxyModel
{
    Q_OBJECT

  public:

    /**
     * Constructor for QgsLayoutGuideProxyModel, filtered to guides of the specified \a orientation and \a page only.
     *
     * Page numbers begin at 0.
     */
    explicit QgsLayoutGuideProxyModel( QObject *parent SIP_TRANSFERTHIS, QgsLayoutGuide::Orientation orientation, int page );

    /**
     * Sets the current \a page for filtering matching guides. Page numbers begin at 0.
     */
    void setPage( int page );

    bool filterAcceptsRow( int sourceRow, const QModelIndex &sourceParent ) const override;
    bool lessThan( const QModelIndex &left, const QModelIndex &right ) const override;

  private:
    QgsLayoutGuide::Orientation mOrientation = QgsLayoutGuide::Horizontal;
    int mPage = 0;

};

#endif //QGSLAYOUTGUIDECOLLECTION_H