qgspallabeling.h

Go to the documentation of this file.

/***************************************************************************
  qgspallabeling.h
  Smart labeling for vector layers
  -------------------
   begin                : June 2009
   copyright            : (C) Martin Dobias
   email                : wonder dot sk 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 QGSPALLABELING_H
#define QGSPALLABELING_H
 
#include "qgis_core.h"
#include "qgis_sip.h"
#include "qgscoordinatetransform.h"
#include "qgsexpression.h"
#include "qgsfeature.h"
#include "qgsfields.h"
#include "qgsgeometry.h"
#include "qgslabellinesettings.h"
#include "qgslabelobstaclesettings.h"
#include "qgslabelplacementsettings.h"
#include "qgslabelpointsettings.h"
#include "qgslabelthinningsettings.h"
#include "qgsmapunitscale.h"
#include "qgspointxy.h"
#include "qgspropertycollection.h"
#include "qgsstringutils.h"
#include "qgstextformat.h"
 
#include <QColor>
#include <QFont>
#include <QFontDatabase>
#include <QHash>
#include <QList>
#include <QMap>
#include <QPainter>
#include <QRectF>
#include <QString>
 
class QgsTextDocument;
class QgsTextDocumentMetrics;
class QgsLabelFeatureDetails;
 
namespace pal SIP_SKIP
{
  class Pal;
  class Layer;
  class LabelPosition;
} //namespace pal
 
class QgsDiagramLayerSettings;
class QgsRectangle;
class QgsMapToPixel;
class QgsFeature;
class QgsTextLabelFeature;
class QgsVectorLayer;
class QgsExpression;
class QFontMetricsF;
class QPainter;
class QPicture;
class QgsGeometry;
class QgsCoordinateTransform;
class QgsLabelSearchTree;
class QgsMapLayer;
class QgsMapSettings;
class QgsLabelFeature;
class QgsLabelingEngine;
class QgsPalLayerSettings;
class QgsVectorLayerLabelProvider;
class QgsDxfExport;
class QgsVectorLayerDiagramProvider;
class QgsExpressionContext;
class QgsCallout;
class QMimeData;

class CORE_EXPORT QgsPalLayerSettings
{
  public:
    QgsPalLayerSettings();
    QgsPalLayerSettings( const QgsPalLayerSettings &s );
    ~QgsPalLayerSettings();

    QgsPalLayerSettings &operator=( const QgsPalLayerSettings &s );
 
    // *INDENT-OFF*
    enum class Property SIP_MONKEYPATCH_SCOPEENUM_UNNEST( QgsPalLayerSettings, Property ) : int
    {
      // text style
      Size = 0,                
      Bold = 1,                
      Italic = 2,              
      Underline = 3,           
      Color = 4,               
      Strikeout = 5,           
      Family = 6,              
      FontStyle = 21,          
      FontSizeUnit = 22,       
      FontTransp = 18,         
      FontOpacity = 92,        
      FontCase = 27,           
      FontLetterSpacing = 28,  
      FontWordSpacing = 29,    
      FontBlendMode = 30,      
      FontStretchFactor = 113, 
 
      // text formatting
      MultiLineWrapChar = 31,
      AutoWrapLength = 101,
      MultiLineHeight = 32,
      MultiLineAlignment = 33,
      TextOrientation = 110,
      TabStopDistance = 120, 
      DirSymbDraw = 34,
      DirSymbLeft = 35,
      DirSymbRight = 36,
      DirSymbPlacement = 37,
      DirSymbReverse = 38,
      NumFormat = 39,
      NumDecimals = 40,
      NumPlusSign = 41,
 
      // text buffer
      BufferDraw = 42,
      BufferSize = 7,
      BufferUnit = 43,
      BufferColor = 8,
      BufferTransp = 19,  
      BufferOpacity = 94, 
      BufferJoinStyle = 44,
      BufferBlendMode = 45,
 
      // mask buffer
      MaskEnabled = 104,    
      MaskBufferSize = 105, 
      MaskBufferUnit = 106, 
      MaskOpacity = 107,    
      MaskJoinStyle = 108,  
 
      // background
      ShapeDraw = 46,
      ShapeKind = 47,
      ShapeSVGFile = 48,
      ShapeSizeType = 49,
      ShapeSizeX = 50,
      ShapeSizeY = 85,
      ShapeSizeUnits = 51,
      ShapeRotationType = 52,
      ShapeRotation = 53,
      ShapeOffset = 54,
      ShapeOffsetUnits = 55,
      ShapeRadii = 56,
      ShapeRadiiUnits = 57,
      ShapeTransparency = 63, 
      ShapeOpacity = 93,      
      ShapeBlendMode = 64,
      ShapeFillColor = 58,
      ShapeStrokeColor = 59,
      ShapeStrokeWidth = 60,
      ShapeStrokeWidthUnits = 61,
      ShapeJoinStyle = 62,
 
      // drop shadow
      ShadowDraw = 65,
      ShadowUnder = 66,
      ShadowOffsetAngle = 67,
      ShadowOffsetDist = 68,
      ShadowOffsetUnits = 69,
      ShadowRadius = 70,
      ShadowRadiusUnits = 71,
      ShadowTransparency = 72, 
      ShadowOpacity = 95,      
      ShadowScale = 73,
      ShadowColor = 74,
      ShadowBlendMode = 75,
 
      // placement
      CentroidWhole = 76,
      OffsetQuad = 77,
      OffsetXY = 78,
      OffsetUnits = 80,
      LabelDistance = 13,
      MaximumDistance = 119, 
      DistanceUnits = 81,
      OffsetRotation = 82,
      CurvedCharAngleInOut = 83,
      // (data defined only)
      PositionX = 9,       
      PositionY = 10,      
      PositionPoint = 114, 
      Hali = 11,           
      Vali = 12,           
      Rotation = 14,       
      LabelRotation = 96,  
      RepeatDistance = 84,
      RepeatDistanceUnit = 86,
      Priority = 87,
      PredefinedPositionOrder = 91,
      LinePlacementOptions = 99, 
      OverrunDistance = 102,     
 
      // TODO QGIS 5.0 - rename this
      LabelAllParts = 103, 
 
      PolygonLabelOutside = 109, 
      LineAnchorPercent = 111,   
      LineAnchorClipping = 112,  
      LineAnchorType = 115,      
      LineAnchorTextPoint = 116, 
      CurvedLabelMode = 124,     
 
      // rendering
      ScaleVisibility = 23,
      MinScale = 16,     
      MinimumScale = 97, 
      MaxScale = 17,     
      MaximumScale = 98, 
      FontLimitPixel = 24,
      FontMinPixel = 25,
      FontMaxPixel = 26,
      IsObstacle = 88,
      ObstacleFactor = 89,
      ZIndex = 90,
      CalloutDraw = 100, 
 
      AllowDegradedPlacement = 117,      
      OverlapHandling = 118,             
      WhitespaceCollisionHandling = 125, 
 
      LabelMarginDistance = 121,          
      RemoveDuplicateLabels = 122,        
      RemoveDuplicateLabelDistance = 123, 
 
      // (data defined only)
      Show = 15,
      AlwaysShow = 20
    };
    // *INDENT-ON*

    bool prepare( QgsRenderContext &context, QSet<QString> &attributeNames SIP_INOUT, const QgsFields &fields, const QgsMapSettings &mapSettings, const QgsCoordinateReferenceSystem &crs );

    QSet<QString> referencedFields( const QgsRenderContext &context ) const;

    void startRender( QgsRenderContext &context );

    void stopRender( QgsRenderContext &context );

    bool containsAdvancedEffects() const;

    static const QgsPropertiesDefinition &propertyDefinitions();

    bool drawLabels = true;
 
    //-- text style

    QString fieldName;

    bool isExpression = false;

    QgsExpression *getLabelExpression() const;

    Q_DECL_DEPRECATED QColor previewBkgrdColor = Qt::white;

    QgsStringReplacementCollection substitutions;
    bool useSubstitutions = false;
 
    //-- text formatting

    QString wrapChar;

    int autoWrapLength = 0;

    bool useMaxLineLengthForAutoWrap = true;

    Qgis::LabelMultiLineAlignment multilineAlign = Qgis::LabelMultiLineAlignment::FollowPlacement;

    bool formatNumbers = false;

    int decimals = 3;

    bool plusSign = false;
 
    //-- placement

    Qgis::LabelPlacement placement = Qgis::LabelPlacement::AroundPoint;

    Qgis::LabelPolygonPlacementFlags polygonPlacementFlags() const { return mPolygonPlacementFlags; }

    void setPolygonPlacementFlags( Qgis::LabelPolygonPlacementFlags flags ) { mPolygonPlacementFlags = flags; }

    bool centroidWhole = false;

    bool centroidInside = false;

    bool fitInPolygonOnly = false;

    double dist = 0;

    Qgis::RenderUnit distUnits = Qgis::RenderUnit::Millimeters;

    QgsMapUnitScale distMapUnitScale;

    Qgis::LabelOffsetType offsetType = Qgis::LabelOffsetType::FromPoint;

    double repeatDistance = 0;

    Qgis::RenderUnit repeatDistanceUnit = Qgis::RenderUnit::Millimeters;

    QgsMapUnitScale repeatDistanceMapUnitScale;

    double xOffset = 0;

    double yOffset = 0;

    Qgis::RenderUnit offsetUnits = Qgis::RenderUnit::Millimeters;

    QgsMapUnitScale labelOffsetMapUnitScale;

    double angleOffset = 0;

    bool preserveRotation = true;

    Qgis::AngleUnit rotationUnit() const;

    void setRotationUnit( Qgis::AngleUnit angleUnit );

    double maxCurvedCharAngleIn = 25.0;

    double maxCurvedCharAngleOut = -25.0;

    int priority = 5;
 
    //-- rendering

    bool scaleVisibility = false;

    double maximumScale = 0;

    double minimumScale = 0;

    bool fontLimitPixelSize = false;

    int fontMinPixelSize = 0;

    int fontMaxPixelSize = 10000;

    Qgis::UpsideDownLabelHandling upsidedownLabels = Qgis::UpsideDownLabelHandling::FlipUpsideDownLabels;

    double zIndex = 0;

    QString geometryGenerator;

    Qgis::GeometryType geometryGeneratorType = Qgis::GeometryType::Point;

    bool geometryGeneratorEnabled = false;

    Qgis::GeometryType layerType = Qgis::GeometryType::Unknown;

    void setLegendString( const QString &legendString ) { mLegendString = legendString; }

    QString legendString() const { return mLegendString; }

    Q_DECL_DEPRECATED void calculateLabelSize(
      const QFontMetricsF *fm,
      const QString &text,
      double &labelX,
      double &labelY,
      const QgsFeature *f = nullptr,
      QgsRenderContext *context = nullptr,
      double *rotatedLabelX SIP_OUT = nullptr,
      double *rotatedLabelY SIP_OUT = nullptr
    ) SIP_DEPRECATED;

    void registerFeature( const QgsFeature &f, QgsRenderContext &context );
 
#ifndef SIP_RUN

    std::vector< std::unique_ptr< QgsLabelFeature > > registerFeatureWithDetails( const QgsFeature &feature, QgsRenderContext &context, const QgsLabelFeatureDetails &details );
 
#endif

    void readXml( const QDomElement &elem, const QgsReadWriteContext &context );

    QDomElement writeXml( QDomDocument &doc, const QgsReadWriteContext &context ) const;

    QgsPropertyCollection &dataDefinedProperties() { return mDataDefinedProperties; }

    const QgsPropertyCollection &dataDefinedProperties() const SIP_SKIP { return mDataDefinedProperties; }

    void setDataDefinedProperties( const QgsPropertyCollection &collection ) { mDataDefinedProperties = collection; }

    const QgsTextFormat &format() const { return mFormat; }

    void setFormat( const QgsTextFormat &format ) { mFormat = format; }

    QgsCallout *callout() const { return mCallout.get(); }

    void setCallout( QgsCallout *callout SIP_TRANSFER );

    const QgsLabelLineSettings &lineSettings() const SIP_SKIP { return mLineSettings; }

    QgsLabelLineSettings &lineSettings() { return mLineSettings; }

    void setLineSettings( const QgsLabelLineSettings &settings ) { mLineSettings = settings; }

    const QgsLabelPointSettings &pointSettings() const SIP_SKIP { return mPointSettings; }

    QgsLabelPointSettings &pointSettings() { return mPointSettings; }

    void setPointSettings( const QgsLabelPointSettings &settings ) { mPointSettings = settings; }

    const QgsLabelObstacleSettings &obstacleSettings() const SIP_SKIP { return mObstacleSettings; }

    QgsLabelObstacleSettings &obstacleSettings() { return mObstacleSettings; }

    void setObstacleSettings( const QgsLabelObstacleSettings &settings ) { mObstacleSettings = settings; }

    const QgsLabelThinningSettings &thinningSettings() const SIP_SKIP { return mThinningSettings; }

    QgsLabelThinningSettings &thinningSettings() { return mThinningSettings; }

    void setThinningSettings( const QgsLabelThinningSettings &settings ) { mThinningSettings = settings; }

    const QgsLabelPlacementSettings &placementSettings() const SIP_SKIP { return mPlacementSettings; }

    QgsLabelPlacementSettings &placementSettings() { return mPlacementSettings; }

    void setPlacementSettings( const QgsLabelPlacementSettings &settings ) { mPlacementSettings = settings; }

    static QPixmap labelSettingsPreviewPixmap(
      const QgsPalLayerSettings &settings, QSize size, const QString &previewText = QString(), int padding = 0, const QgsScreenProperties &screen = QgsScreenProperties()
    );

    Qgis::UnplacedLabelVisibility unplacedVisibility() const;

    void setUnplacedVisibility( Qgis::UnplacedLabelVisibility visibility );

    QMimeData *toMimeData() const SIP_FACTORY;

    static QgsPalLayerSettings fromMimeData( const QMimeData *data, bool *ok SIP_OUT = nullptr );
 
    // temporary stuff: set when layer gets prepared or labeled
    const QgsFeature *mCurFeat = nullptr;
    QgsFields mCurFields;
    int fieldIndex = 0;
    const QgsMapToPixel *xform = nullptr;
    QgsCoordinateTransform ct;
 
    QgsPointXY ptZero;
    QgsPointXY ptOne;
    QgsGeometry extentGeom;
    int mFeaturesToLabel = 0; // total features that will probably be labeled, may be less (figured before PAL)
#ifndef SIP_RUN
    mutable int mFeatsSendingToPal = 0; // total features tested for sending into PAL (relative to maxNumLabels)
    mutable int mFeatsRegPal = 0;       // number of features registered in PAL, when using limitNumLabels
#else
    int mFeatsSendingToPal; // total features tested for sending into PAL (relative to maxNumLabels)
    int mFeatsRegPal;       // number of features registered in PAL, when using limitNumLabels
#endif
 
  private:
    friend class QgsVectorLayer; // to allow calling readFromLayerCustomProperties()

    void readFromLayerCustomProperties( QgsVectorLayer *layer );

    void readOldDataDefinedPropertyMap( QgsVectorLayer *layer, QDomElement *parentElem );

    void readOldDataDefinedProperty( QgsVectorLayer *layer, QgsPalLayerSettings::Property p );

    void calculateLabelMetrics(
      const QFontMetricsF &fm, QgsRenderContext &context, const QgsTextFormat &format, QgsTextDocument &document, QgsTextDocumentMetrics &documentMetrics, QSizeF &size, QSizeF &rotatedSize, QRectF &outerBounds
    ) const;
 
 
    enum DataDefinedValueType
    {
      DDBool,
      DDInt,
      DDIntPos,
      DDDouble,
      DDDoublePos,
      DDRotation180,
      DDOpacity, 
      DDString,
      DDUnits,
      DDColor,
      DDJoinStyle,
      DDBlendMode,
      DDPointF,
      DDSizeF, 
    };
 
    // convenience data defined evaluation function
    bool dataDefinedValEval( DataDefinedValueType valType, QgsPalLayerSettings::Property p, QVariant &exprVal, QgsExpressionContext &context, const QVariant &originalValue = QVariant() );
 
    void parseTextStyle( QFont &labelFont, Qgis::RenderUnit fontunits, QgsRenderContext &context );
 
    void parseTextBuffer( QgsRenderContext &context );
 
    void parseTextMask( QgsRenderContext &context );
 
    void parseTextFormatting( QgsRenderContext &context );
 
    void parseShapeBackground( QgsRenderContext &context );
 
    void parseDropShadow( QgsRenderContext &context );

    bool checkMinimumSizeMM( const QgsRenderContext &ct, const QgsGeometry &geom, double minSize ) const;

    bool isLabelVisible( QgsRenderContext &context ) const;

    QgsTextFormat evaluateTextFormat( QgsRenderContext &context, bool &labelIsHidden );

    bool evaluateLabelContent( const QgsFeature &feature, QgsRenderContext &context, bool allowMultipleLines, QString &labelText, QgsTextDocument &document, const QgsTextFormat &format ) const;

    QgsGeometry evaluateLabelGeometry( const QgsFeature &feature, QgsRenderContext &context, const QgsLabelLineSettings &lineSettings ) const;
 
    std::unique_ptr< QgsTextLabelFeature> generateLabelFeature(
      QgsRenderContext &context,
      const QgsFeature &feature,
      int subPartId,
      QgsGeometry geom,
      const QgsGeometry &obstacleGeometry,
      QgsTextDocument doc,
      const QString &labelText,
      const QgsTextFormat &evaluatedFormat,
      const QgsSymbol *symbol,
      const QgsLabelLineSettings &lineSettings,
      const QgsLabelPointSettings &pointSettings,
      const QgsLabelPlacementSettings &placementSettings,
      bool isObstacle,
      bool doClip
    ) const;

    std::unique_ptr< QgsLabelFeature > registerObstacleFeature( const QgsFeature &f, QgsRenderContext &context, const QgsGeometry &obstacleGeometry = QgsGeometry() );
 
    QMap<Property, QVariant> dataDefinedValues;

    QgsPropertyCollection mDataDefinedProperties;
 
    mutable std::unique_ptr<QgsExpression> expression;
 
    std::unique_ptr< QFontDatabase > mFontDB;
 
    QgsTextFormat mFormat;
 
    std::unique_ptr< QgsCallout > mCallout;
 
    QgsLabelPlacementSettings mPlacementSettings;
    QgsLabelLineSettings mLineSettings;
    QgsLabelPointSettings mPointSettings;
    QgsLabelObstacleSettings mObstacleSettings;
    QgsLabelThinningSettings mThinningSettings;
 
    Qgis::LabelPolygonPlacementFlags mPolygonPlacementFlags = Qgis::LabelPolygonPlacementFlag::AllowPlacementInsideOfPolygon;
 
    QgsExpression mGeometryGeneratorExpression;
 
    bool mRenderStarted = false;
 
    QString mLegendString = QObject::tr( "Aa" );
 
    Qgis::UnplacedLabelVisibility mUnplacedVisibility = Qgis::UnplacedLabelVisibility::FollowEngineSetting;

    Qgis::AngleUnit mRotationUnit = Qgis::AngleUnit::Degrees;
 
    static void initPropertyDefinitions();
};
 

class CORE_EXPORT QgsPalLabeling
{
  public:
    static bool staticWillUseLayer( const QgsMapLayer *layer );
 
    // clang-format off
    static QgsGeometry prepareGeometry( const QgsGeometry &geometry, QgsRenderContext &context, const QgsCoordinateTransform &ct, const QgsGeometry &clipGeometry = QgsGeometry(), bool mergeLines = false ) SIP_FACTORY;
    // clang-format on

    static bool geometryRequiresPreparation(
      const QgsGeometry &geometry, QgsRenderContext &context, const QgsCoordinateTransform &ct, const QgsGeometry &clipGeometry = QgsGeometry(), bool mergeLines = false
    );

    static QStringList splitToLines( const QString &text, const QString &wrapCharacter, int autoWrapLength = 0, bool useMaxLineLengthWhenAutoWrapping = true );

    static QStringList splitToGraphemes( const QString &text );
 
  private:
    static void dataDefinedTextStyle( QgsPalLayerSettings &tmpLyr, const QMap< QgsPalLayerSettings::Property, QVariant > &ddValues );

    static void dataDefinedTextFormatting( QgsPalLayerSettings &tmpLyr, const QMap< QgsPalLayerSettings::Property, QVariant > &ddValues );

    static void dataDefinedTextBuffer( QgsPalLayerSettings &tmpLyr, const QMap< QgsPalLayerSettings::Property, QVariant > &ddValues );

    static void dataDefinedTextMask( QgsPalLayerSettings &tmpLyr, const QMap< QgsPalLayerSettings::Property, QVariant > &ddValues );

    static void dataDefinedShapeBackground( QgsPalLayerSettings &tmpLyr, const QMap< QgsPalLayerSettings::Property, QVariant > &ddValues );

    static void dataDefinedDropShadow( QgsPalLayerSettings &tmpLyr, const QMap< QgsPalLayerSettings::Property, QVariant > &ddValues );
 
    friend class QgsVectorLayerLabelProvider; // to allow calling the static methods above
    friend class QgsDxfExport;                // to allow calling the static methods above

    static bool checkMinimumSizeMM( const QgsRenderContext &context, const QgsGeometry &geom, double minSize );
 
    friend class QgsPalLayerSettings;
};
 
 
#endif // QGSPALLABELING_H