qgsunittypes.h

Go to the documentation of this file.

/***************************************************************************
                         qgsunittypes.h
                         --------------
    begin                : February 2016
    copyright            : (C) 2016 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 QGSUNITTYPES_H
#define QGSUNITTYPES_H

#include "qgis_core.h"
#include "qgis.h"

/***************************************************************************
 * This class is considered CRITICAL and any change MUST be accompanied with
 * full unit tests in test_qgsunittypes.py.
 * See details in QEP #17
 ****************************************************************************/

class CORE_EXPORT QgsUnitTypes
{
    Q_GADGET

  public:
    enum DistanceUnit
    {
      DistanceMeters = 0, 
      DistanceKilometers, 
      DistanceFeet, 
      DistanceNauticalMiles, 
      DistanceYards, 
      DistanceMiles, 
      DistanceDegrees, 
      DistanceCentimeters, 
      DistanceMillimeters, 
      DistanceUnknownUnit, 
    };
    Q_ENUM( DistanceUnit )

    
    enum DistanceUnitType
    {
      Standard = 0, 
      Geographic,   
      UnknownType,  
    };

    enum AreaUnit
    {
      AreaSquareMeters = 0, 
      AreaSquareKilometers, 
      AreaSquareFeet, 
      AreaSquareYards, 
      AreaSquareMiles, 
      AreaHectares, 
      AreaAcres, 
      AreaSquareNauticalMiles, 
      AreaSquareDegrees, 
      AreaSquareCentimeters, 
      AreaSquareMillimeters, 
      AreaUnknownUnit, 
    };
    Q_ENUM( AreaUnit )

    
    enum AngleUnit
    {
      AngleDegrees = 0, 
      AngleRadians, 
      AngleGon, 
      AngleMinutesOfArc, 
      AngleSecondsOfArc, 
      AngleTurn, 
      AngleUnknownUnit, 
    };
    Q_ENUM( AngleUnit )

    
    enum RenderUnit
    {
      RenderMillimeters = 0, 
      RenderMapUnits, 
      RenderPixels, 
      RenderPercentage, 
      RenderPoints, 
      RenderInches, 
      RenderUnknownUnit, 
      RenderMetersInMapUnits, 
    };
    Q_ENUM( RenderUnit )

    
    enum LayoutUnit
    {
      LayoutMillimeters = 0, 
      LayoutCentimeters, 
      LayoutMeters, 
      LayoutInches, 
      LayoutFeet, 
      LayoutPoints, 
      LayoutPicas, 
      LayoutPixels 
    };
    Q_ENUM( LayoutUnit )

    
    enum LayoutUnitType
    {
      LayoutPaperUnits = 0, 
      LayoutScreenUnits 
    };

    struct DistanceValue
    {

      double value;

      QgsUnitTypes::DistanceUnit unit;
    };

    struct AreaValue
    {

      double value;

      QgsUnitTypes::AreaUnit unit;
    };

    typedef QList<QgsUnitTypes::RenderUnit> RenderUnitList;

    // DISTANCE UNITS

    Q_INVOKABLE static DistanceUnitType unitType( QgsUnitTypes::DistanceUnit unit );

    Q_INVOKABLE static QString encodeUnit( QgsUnitTypes::DistanceUnit unit );

    Q_INVOKABLE static QgsUnitTypes::DistanceUnit decodeDistanceUnit( const QString &string, bool *ok SIP_OUT = nullptr );

    Q_INVOKABLE static QString toString( QgsUnitTypes::DistanceUnit unit );

    Q_INVOKABLE static QString toAbbreviatedString( QgsUnitTypes::DistanceUnit unit );

    Q_INVOKABLE static QgsUnitTypes::DistanceUnit stringToDistanceUnit( const QString &string, bool *ok SIP_OUT = nullptr );

    Q_INVOKABLE static double fromUnitToUnitFactor( QgsUnitTypes::DistanceUnit fromUnit, QgsUnitTypes::DistanceUnit toUnit );

    // AREAL UNITS

    Q_INVOKABLE static DistanceUnitType unitType( QgsUnitTypes::AreaUnit unit );

    Q_INVOKABLE static QString encodeUnit( QgsUnitTypes::AreaUnit unit );

    Q_INVOKABLE static AreaUnit decodeAreaUnit( const QString &string, bool *ok SIP_OUT = nullptr );

    Q_INVOKABLE static QString toString( QgsUnitTypes::AreaUnit unit );

    Q_INVOKABLE static QString toAbbreviatedString( QgsUnitTypes::AreaUnit unit );

    Q_INVOKABLE static AreaUnit stringToAreaUnit( const QString &string, bool *ok SIP_OUT = nullptr );

    Q_INVOKABLE static double fromUnitToUnitFactor( QgsUnitTypes::AreaUnit fromUnit, QgsUnitTypes::AreaUnit toUnit );

    Q_INVOKABLE static QgsUnitTypes::AreaUnit distanceToAreaUnit( QgsUnitTypes::DistanceUnit distanceUnit );

    // ANGULAR UNITS

    Q_INVOKABLE static QString encodeUnit( QgsUnitTypes::AngleUnit unit );

    Q_INVOKABLE static QgsUnitTypes::AngleUnit decodeAngleUnit( const QString &string, bool *ok SIP_OUT = nullptr );

    Q_INVOKABLE static QString toString( QgsUnitTypes::AngleUnit unit );

    Q_INVOKABLE static double fromUnitToUnitFactor( QgsUnitTypes::AngleUnit fromUnit, QgsUnitTypes::AngleUnit toUnit );

    Q_INVOKABLE static QString formatAngle( double angle, int decimals, QgsUnitTypes::AngleUnit unit );


    Q_INVOKABLE static QgsUnitTypes::DistanceValue scaledDistance( double distance, QgsUnitTypes::DistanceUnit unit, int decimals, bool keepBaseUnit = false );

    Q_INVOKABLE static QgsUnitTypes::AreaValue scaledArea( double area, QgsUnitTypes::AreaUnit unit, int decimals, bool keepBaseUnit = false );

    Q_INVOKABLE static QString formatDistance( double distance, int decimals, QgsUnitTypes::DistanceUnit unit, bool keepBaseUnit = false );

    Q_INVOKABLE static QString formatArea( double area, int decimals, QgsUnitTypes::AreaUnit unit, bool keepBaseUnit = false );

    // RENDER UNITS

    Q_INVOKABLE static QString encodeUnit( QgsUnitTypes::RenderUnit unit );

    Q_INVOKABLE static QgsUnitTypes::RenderUnit decodeRenderUnit( const QString &string, bool *ok SIP_OUT = nullptr );

    Q_INVOKABLE static QString toString( QgsUnitTypes::RenderUnit unit );


    // LAYOUT UNITS

    Q_INVOKABLE static QString encodeUnit( QgsUnitTypes::LayoutUnit unit );

    Q_INVOKABLE static QgsUnitTypes::LayoutUnit decodeLayoutUnit( const QString &string, bool *ok SIP_OUT = nullptr );

    Q_INVOKABLE static QgsUnitTypes::LayoutUnitType unitType( QgsUnitTypes::LayoutUnit units );

    Q_INVOKABLE static QString toAbbreviatedString( QgsUnitTypes::LayoutUnit unit );

    Q_INVOKABLE static QString toString( QgsUnitTypes::LayoutUnit unit );

};

#endif // QGSUNITTYPES_H