Start on classes for snapping guide items

python/core/core_auto.sip

@@ -384,6 +384,7 @@
 %Include gps/qgsnmeaconnection.sip
 %Include gps/qgsgpsdconnection.sip
 %Include layout/qgslayout.sip
+%Include layout/qgslayoutguidecollection.sip
 %Include layout/qgslayoutitem.sip
 %Include layout/qgslayoutitemmap.sip
 %Include layout/qgslayoutitempage.sip

python/core/layout/qgslayout.sip

@@ -25,6 +25,7 @@ class QgsLayout : QGraphicsScene, QgsExpressionContextGenerator
       ZPage,
       ZItem,
       ZGrid,
+      ZGuide,
       ZMapTool,
       ZSnapIndicator,
     };

python/core/layout/qgslayoutguidecollection.sip

@@ -0,0 +1,98 @@
+/************************************************************************
+ * This file has been generated automatically from                      *
+ *                                                                      *
+ * src/core/layout/qgslayoutguidecollection.h                           *
+ *                                                                      *
+ * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
+ ************************************************************************/
+
+
+
+class QgsLayoutGuide
+{
+%Docstring
+ Contains the configuration for a single snap guide used by a layout.
+.. versionadded:: 3.0
+%End
+
+%TypeHeaderCode
+#include "qgslayoutguidecollection.h"
+%End
+  public:
+
+    enum Orientation
+    {
+      Horizontal,
+      Vertical,
+    };
+
+    QgsLayoutGuide( QgsLayout *layout, Orientation orientation, const QgsLayoutMeasurement &position );
+
+    Orientation orientation() const;
+%Docstring
+ Returns the guide's orientation.
+ :rtype: Orientation
+%End
+
+    QgsLayoutMeasurement position() const;
+%Docstring
+ 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().
+
+.. seealso:: setPosition()
+ :rtype: QgsLayoutMeasurement
+%End
+
+    void setPosition( const QgsLayoutMeasurement &position );
+%Docstring
+ Sets the guide's ``position`` within the page.
+
+ The ``position`` argument indicates either the horizontal or vertical position
+ of the guide, depending on the guide's orientation().
+
+.. seealso:: position()
+%End
+
+    int page() const;
+%Docstring
+ Returns the page number of the guide.
+
+ Page numbering begins at 0.
+
+.. seealso:: setPage()
+ :rtype: int
+%End
+
+    void setPage( int page );
+%Docstring
+ Sets the ``page`` number of the guide.
+
+ Page numbering begins at 0.
+
+.. seealso:: page()
+%End
+
+    void update();
+%Docstring
+ Updates the position of the guide's line item.
+%End
+
+    QGraphicsLineItem *item();
+%Docstring
+ Returns the guide's line item.
+ :rtype: QGraphicsLineItem
+%End
+
+};
+
+
+
+/************************************************************************
+ * This file has been generated automatically from                      *
+ *                                                                      *
+ * src/core/layout/qgslayoutguidecollection.h                           *
+ *                                                                      *
+ * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
+ ************************************************************************/

src/core/CMakeLists.txt

@@ -354,6 +354,7 @@ SET(QGIS_CORE_SRCS
   layout/qgslayout.cpp
   layout/qgslayoutcontext.cpp
   layout/qgslayoutgridsettings.cpp
+  layout/qgslayoutguidecollection.cpp
   layout/qgslayoutitem.cpp
   layout/qgslayoutitemmap.cpp
   layout/qgslayoutitempage.cpp
@@ -684,6 +685,7 @@ SET(QGIS_CORE_MOC_HDRS
   gps/qgsgpsdconnection.h
 
   layout/qgslayout.h
+  layout/qgslayoutguidecollection.h
   layout/qgslayoutitem.h
   layout/qgslayoutitemmap.h
   layout/qgslayoutitempage.h

src/core/layout/qgslayout.h

@@ -43,7 +43,8 @@ class CORE_EXPORT QgsLayout : public QGraphicsScene, public QgsExpressionContext
     {
       ZPage = 0, //!< Z-value for page (paper) items
       ZItem = 1, //!< Minimum z value for items
-      ZGrid = 9999, //!< Z-value for page grids
+      ZGrid = 9998, //!< Z-value for page grids
+      ZGuide = 9999, //!< Z-value for page guides
       ZMapTool = 10000, //!< Z-value for temporary map tool items
       ZSnapIndicator = 10001, //!< Z-value for snapping indicator
     };

src/core/layout/qgslayoutguidecollection.cpp

@@ -0,0 +1,116 @@
+/***************************************************************************
+                             qgslayoutguidecollection.cpp
+                             ----------------------------
+    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.                                   *
+ *                                                                         *
+ ***************************************************************************/
+
+#include "qgslayoutguidecollection.h"
+#include "qgslayout.h"
+#include <QGraphicsLineItem>
+
+
+//
+// QgsLayoutGuide
+//
+
+QgsLayoutGuide::QgsLayoutGuide( QgsLayout *layout, Orientation orientation, const QgsLayoutMeasurement &position )
+  : mOrientation( orientation )
+  , mPosition( position )
+  , mLayout( layout )
+  , mLineItem( new QGraphicsLineItem() )
+{
+  mLineItem->hide();
+  mLineItem->setZValue( QgsLayout::ZGuide );
+  mLayout->addItem( mLineItem.get() );
+
+  QPen linePen( Qt::SolidLine );
+  linePen.setColor( Qt::red );
+  // use a pen width of 0, since this activates a cosmetic pen
+  // which doesn't scale with the composer and keeps a constant size
+  linePen.setWidthF( 0 );
+  mLineItem->setPen( linePen );
+}
+
+QgsLayoutMeasurement QgsLayoutGuide::position() const
+{
+  return mPosition;
+}
+
+void QgsLayoutGuide::setPosition( const QgsLayoutMeasurement &position )
+{
+  mPosition = position;
+  update();
+}
+
+int QgsLayoutGuide::page() const
+{
+  return mPage;
+}
+
+void QgsLayoutGuide::setPage( int page )
+{
+  mPage = page;
+  update();
+}
+
+void QgsLayoutGuide::update()
+{
+  // first find matching page
+  if ( mPage >= mLayout->pageCollection()->pageCount() )
+  {
+    mLineItem->hide();
+    return;
+  }
+
+  QgsLayoutItemPage *page = mLayout->pageCollection()->page( mPage );
+  mLineItem->setParentItem( page );
+  double layoutPos = mLayout->convertToLayoutUnits( mPosition );
+  switch ( mOrientation )
+  {
+    case Horizontal:
+      if ( layoutPos > page->rect().width() )
+      {
+        mLineItem->hide();
+      }
+      else
+      {
+        mLineItem->setLine( 0, layoutPos, page->rect().width(), layoutPos );
+        mLineItem->show();
+      }
+
+      break;
+
+    case Vertical:
+      if ( layoutPos > page->rect().height() )
+      {
+        mLineItem->hide();
+      }
+      else
+      {
+        mLineItem->setLine( layoutPos, 0, layoutPos, page->rect().height() );
+        mLineItem->show();
+      }
+
+      break;
+  }
+}
+
+QGraphicsLineItem *QgsLayoutGuide::item()
+{
+  return mLineItem.get();
+}
+
+QgsLayoutGuide::Orientation QgsLayoutGuide::orientation() const
+{
+  return mOrientation;
+}

src/core/layout/qgslayoutguidecollection.h

@@ -0,0 +1,119 @@
+/***************************************************************************
+                             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 <memory>
+
+class QgsLayout;
+class QGraphicsLineItem;
+
+/**
+ * \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:
+
+    //! Guide orientation
+    enum Orientation
+    {
+      Horizontal, //!< Horizontal guide
+      Vertical, //!< Vertical guide
+    };
+
+    QgsLayoutGuide( QgsLayout *layout, Orientation orientation, const QgsLayoutMeasurement &position );
+
+    /**
+     * 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();
+
+  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::shared_ptr< QGraphicsLineItem > mLineItem;
+};
+
+
+
+#endif //QGSLAYOUTGUIDECOLLECTION_H

tests/src/python/CMakeLists.txt

@@ -79,6 +79,7 @@ ADD_PYTHON_TEST(PyQgsLayoutManager test_qgslayoutmanager.py)
 ADD_PYTHON_TEST(PyQgsLayoutPageCollection test_qgslayoutpagecollection.py)
 ADD_PYTHON_TEST(PyQgsLayoutView test_qgslayoutview.py)
 ADD_PYTHON_TEST(PyQgsLayoutGridSettings test_qgslayoutgridsettings.py)
+ADD_PYTHON_TEST(PyQgsLayoutGuide test_qgslayoutguides.py)
 ADD_PYTHON_TEST(PyQgsLayoutItemPropertiesDialog test_qgslayoutitempropertiesdialog.py)
 ADD_PYTHON_TEST(PyQgsLayoutSnapper test_qgslayoutsnapper.py)
 ADD_PYTHON_TEST(PyQgsLayoutUnitsComboBox test_qgslayoutunitscombobox.py)