qgslayoutpoint.h 5.15 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173
/***************************************************************************
                         qgslayoutpoint.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 QGSLAYOUTPOINT_H
#define QGSLAYOUTPOINT_H

#include "qgis_core.h"
#include "qgsunittypes.h"
#include <QPointF>

/**
 * \ingroup core
 * \class QgsLayoutPoint
 * \brief This class provides a method of storing points, consisting of an x and y coordinate,
 * for use in QGIS layouts. Measurement units are stored alongside the position.
 *
 * \see QgsLayoutMeasurementConverter
 * \note This class does not inherit from QPointF since QPointF includes methods which should not apply
 * to positions with with units. For instance, the + and - operators would mislead users of this class
 * to believe that addition of two QgsLayoutPoints with different unit types would automatically convert
 * units. Instead, all unit conversion must be handled by a QgsLayoutMeasurementConverter so that
 * conversion between paper and screen units can be correctly performed.
 * \since QGIS 3.0
 */
class CORE_EXPORT QgsLayoutPoint
{
  public:

    /**
     * Constructor for QgsLayoutPoint.
    */
    QgsLayoutPoint( double x, double y, QgsUnitTypes::LayoutUnit units = QgsUnitTypes::LayoutMillimeters );

    /**
     * Constructor for QgsLayoutPoint.
    */
    explicit QgsLayoutPoint( QPointF point, QgsUnitTypes::LayoutUnit units = QgsUnitTypes::LayoutMillimeters );

    /**
     * Constructor for an empty point, where both x and y are set to 0.
     * \param units units for measurement
    */
    explicit QgsLayoutPoint( QgsUnitTypes::LayoutUnit units = QgsUnitTypes::LayoutMillimeters );

    /**
     * Sets new x and y coordinates for the point.
     * \see setX()
     * \see setY()
     * \see setUnits()
    */
    void setPoint( const double x, const double y ) { mX = x; mY = y; }

    /**
     * Returns x coordinate of point.
     * \see setX()
     * \see y()
    */
    double x() const { return mX; }

    /**
     * Sets the x coordinate of point.
     * \see x()
     * \see setY()
    */
    void setX( const double x ) { mX = x; }

    /**
     * Returns y coordinate of point.
     * \see setY()
     * \see x()
    */
    double y() const { return mY; }

    /**
     * Sets y coordinate of point.
     * \see y()
     * \see setX()
    */
    void setY( const double y ) { mY = y; }

    /**
     * Returns the units for the point.
     * \see setUnits()
    */
    QgsUnitTypes::LayoutUnit units() const { return mUnits; }

    /**
     * Sets the \a units for the point. Does not alter the stored coordinates,
     * ie. no conversion is done.
     * \see units()
    */
    void setUnits( const QgsUnitTypes::LayoutUnit units ) { mUnits = units; }

    /**
     * Tests whether the position is null, ie both its x and y coordinates
     * are zero.
     * \returns TRUE if point is null
    */
    bool isNull() const;

    /**
     * Converts the layout point to a QPointF. The unit information is discarded
     * during this operation.
     * \returns QPointF with same x and y coordinates as layout point
    */
    QPointF toQPointF() const;

    /**
     * Encodes the layout point to a string
     * \see decodePoint()
    */
    QString encodePoint() const;

    /**
     * Decodes a point from a \a string.
     * \see encodePoint()
    */
    static QgsLayoutPoint decodePoint( const QString &string );

    bool operator==( const QgsLayoutPoint &other ) const;
    bool operator!=( const QgsLayoutPoint &other ) const;

    /**
     * Multiplies the x and y by a scalar value.
     */
    QgsLayoutPoint operator*( double v ) const;

    /**
     * Multiplies the x and y by a scalar value.
     */
    QgsLayoutPoint operator*=( double v );

    /**
     * Divides the x and y by a scalar value.
     */
    QgsLayoutPoint operator/( double v ) const;

    /**
     * Divides the x and y by a scalar value.
     */
    QgsLayoutPoint operator/=( double v );

#ifdef SIP_RUN
    SIP_PYOBJECT __repr__();
    % MethodCode
    QString str = QStringLiteral( "<QgsLayoutPoint: %1, %2 %3 >" ).arg( sipCpp->x() ).arg( sipCpp->y() ).arg( QgsUnitTypes::toAbbreviatedString( sipCpp->units() ) );
    sipRes = PyUnicode_FromString( str.toUtf8().constData() );
    % End
#endif

  private:

    double mX = 0.0;
    double mY = 0.0;
    QgsUnitTypes::LayoutUnit mUnits = QgsUnitTypes::LayoutMillimeters;

};

#endif // QGSLAYOUTPOINT_H