Branch data     Line data    Source code

       1                 :            : /***************************************************************************
       2                 :            :                          qgslayoutsize.h
       3                 :            :                          ---------------
       4                 :            :     begin                : June 2017
       5                 :            :     copyright            : (C) 2017 by Nyall Dawson
       6                 :            :     email                : nyall dot dawson at gmail dot com
       7                 :            :  ***************************************************************************/
       8                 :            : 
       9                 :            : /***************************************************************************
      10                 :            :  *                                                                         *
      11                 :            :  *   This program is free software; you can redistribute it and/or modify  *
      12                 :            :  *   it under the terms of the GNU General Public License as published by  *
      13                 :            :  *   the Free Software Foundation; either version 2 of the License, or     *
      14                 :            :  *   (at your option) any later version.                                   *
      15                 :            :  *                                                                         *
      16                 :            :  ***************************************************************************/
      17                 :            : 
      18                 :            : #ifndef QGSLAYOUTSIZE_H
      19                 :            : #define QGSLAYOUTSIZE_H
      20                 :            : 
      21                 :            : #include "qgis_core.h"
      22                 :            : #include "qgsunittypes.h"
      23                 :            : #include <QSizeF>
      24                 :            : 
      25                 :            : 
      26                 :            : /**
      27                 :            :  * \ingroup core
      28                 :            :  * \class QgsLayoutSize
      29                 :            :  * \brief This class provides a method of storing sizes, consisting of a width and height,
      30                 :            :  * for use in QGIS layouts. Measurement units are stored alongside the size.
      31                 :            :  *
      32                 :            :  * \see QgsLayoutMeasurementConverter
      33                 :            :  * \note This class does not inherit from QSizeF since QSizeF includes methods which should not apply to sizes
      34                 :            :  * with units. For instance, the + and - operators would mislead users of this class to believe that
      35                 :            :  * addition of two QgsLayoutSize with different unit types would automatically convert units. Instead,
      36                 :            :  * all unit conversion must be handled by a QgsLayoutMeasurementConverter so that conversion between
      37                 :            :  * paper and screen units can be correctly performed.
      38                 :            :  * \since QGIS 3.0
      39                 :            :  */
      40                 :            : class CORE_EXPORT QgsLayoutSize
      41                 :            : {
      42                 :            :   public:
      43                 :            : 
      44                 :            :     /**
      45                 :            :      * Constructor for QgsLayoutSize.
      46                 :            :      * \param width width
      47                 :            :      * \param height height
      48                 :            :      * \param units units for width and height
      49                 :            :     */
      50                 :            :     QgsLayoutSize( double width, double height, QgsUnitTypes::LayoutUnit units = QgsUnitTypes::LayoutMillimeters );
      51                 :            : 
      52                 :            :     /**
      53                 :            :      * Constructor for QgsLayoutSize.
      54                 :            :     */
      55                 :            :     explicit QgsLayoutSize( QSizeF size, QgsUnitTypes::LayoutUnit units = QgsUnitTypes::LayoutMillimeters );
      56                 :            : 
      57                 :            :     /**
      58                 :            :      * Constructor for an empty layout size
      59                 :            :      * \param units units for measurement
      60                 :            :     */
      61                 :            :     explicit QgsLayoutSize( QgsUnitTypes::LayoutUnit units = QgsUnitTypes::LayoutMillimeters );
      62                 :            : 
      63                 :            :     /**
      64                 :            :      * Sets new \a width and \a height for the size.
      65                 :            :      * \see setWidth()
      66                 :            :      * \see setHeight()
      67                 :            :      * \see setUnits()
      68                 :            :     */
      69                 :          0 :     void setSize( const double width, const double height ) { mWidth = width; mHeight = height; }
      70                 :            : 
      71                 :            :     /**
      72                 :            :      * Returns the width of the size.
      73                 :            :      * \see setWidth()
      74                 :            :      * \see height()
      75                 :            :     */
      76                 :          0 :     double width() const { return mWidth; }
      77                 :            : 
      78                 :            :     /**
      79                 :            :      * Sets the \a width for the size.
      80                 :            :      * \see width()
      81                 :            :      * \see setHeight()
      82                 :            :     */
      83                 :          0 :     void setWidth( const double width ) { mWidth = width; }
      84                 :            : 
      85                 :            :     /**
      86                 :            :      * Returns the height of the size.
      87                 :            :      * \see setHeight()
      88                 :            :      * \see width()
      89                 :            :     */
      90                 :          0 :     double height() const { return mHeight; }
      91                 :            : 
      92                 :            :     /**
      93                 :            :      * Sets the \a height for the size.
      94                 :            :      * \see height()
      95                 :            :      * \see setWidth()
      96                 :            :     */
      97                 :          0 :     void setHeight( const double height ) { mHeight = height; }
      98                 :            : 
      99                 :            :     /**
     100                 :            :      * Returns the units for the size.
     101                 :            :      * \see setUnits()
     102                 :            :     */
     103                 :          0 :     QgsUnitTypes::LayoutUnit units() const { return mUnits; }
     104                 :            : 
     105                 :            :     /**
     106                 :            :      * Sets the \a units for the size. Does not alter the stored width or height,
     107                 :            :      * ie. no conversion is done.
     108                 :            :      * \see units()
     109                 :            :     */
     110                 :          0 :     void setUnits( const QgsUnitTypes::LayoutUnit units ) { mUnits = units; }
     111                 :            : 
     112                 :            :     /**
     113                 :            :      * Tests whether the size is empty, ie both its width and height
     114                 :            :      * are zero.
     115                 :            :      * \returns TRUE if size is empty
     116                 :            :     */
     117                 :            :     bool isEmpty() const;
     118                 :            : 
     119                 :            :     /**
     120                 :            :      * Converts the layout size to a QSizeF. The unit information is discarded
     121                 :            :      * during this operation.
     122                 :            :      * \returns QSizeF with same dimensions as layout size
     123                 :            :     */
     124                 :            :     QSizeF toQSizeF() const;
     125                 :            : 
     126                 :            :     /**
     127                 :            :      * Encodes the layout size to a string
     128                 :            :      * \see decodeSize()
     129                 :            :     */
     130                 :            :     QString encodeSize() const;
     131                 :            : 
     132                 :            :     /**
     133                 :            :      * Decodes a size from a \a string.
     134                 :            :      * \see encodeSize()
     135                 :            :     */
     136                 :            :     static QgsLayoutSize decodeSize( const QString &string );
     137                 :            : 
     138                 :            :     bool operator==( const QgsLayoutSize &other ) const;
     139                 :            :     bool operator!=( const QgsLayoutSize &other ) const;
     140                 :            : 
     141                 :            :     /**
     142                 :            :      * Multiplies the width and height by a scalar value.
     143                 :            :      */
     144                 :            :     QgsLayoutSize operator*( double v ) const;
     145                 :            : 
     146                 :            :     /**
     147                 :            :      * Multiplies the width and height by a scalar value.
     148                 :            :      */
     149                 :            :     QgsLayoutSize operator*=( double v );
     150                 :            : 
     151                 :            :     /**
     152                 :            :      * Divides the width and height by a scalar value.
     153                 :            :      */
     154                 :            :     QgsLayoutSize operator/( double v ) const;
     155                 :            : 
     156                 :            :     /**
     157                 :            :      * Divides the width and height by a scalar value.
     158                 :            :      */
     159                 :            :     QgsLayoutSize operator/=( double v );
     160                 :            : 
     161                 :            : #ifdef SIP_RUN
     162                 :            :     SIP_PYOBJECT __repr__();
     163                 :            :     % MethodCode
     164                 :            :     QString str = QStringLiteral( "<QgsLayoutSize: %1 x %2 %3 >" ).arg( sipCpp->width() ).arg( sipCpp->height() ).arg( QgsUnitTypes::toAbbreviatedString( sipCpp->units() ) );
     165                 :            :     sipRes = PyUnicode_FromString( str.toUtf8().constData() );
     166                 :            :     % End
     167                 :            : #endif
     168                 :            : 
     169                 :            :   private:
     170                 :            : 
     171                 :            :     double mWidth = 0.0;
     172                 :            :     double mHeight = 0.0;
     173                 :            :     QgsUnitTypes::LayoutUnit mUnits = QgsUnitTypes::LayoutMillimeters;
     174                 :            : 
     175                 :            : };
     176                 :            : 
     177                 :            : #endif // QGSLAYOUTSIZE_H