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 <QString>
#include <QFont>
#include <QFontDatabase>
#include <QColor>
#include <QHash>
#include <QList>
#include <QPainter>
#include <QRectF>
#include <QMap>
#include "qgsfeature.h"
#include "qgsgeometry.h"
#include "qgsfields.h"
#include "qgspointxy.h"
#include "qgsmapunitscale.h"
#include "qgsstringutils.h"
#include "qgstextformat.h"
#include "qgspropertycollection.h"
#include "qgslabelplacementsettings.h"
#include "qgslabelobstaclesettings.h"
#include "qgslabelthinningsettings.h"
#include "qgslabellinesettings.h"
#include "qgslabelpointsettings.h"
#include "qgscoordinatetransform.h"
#include "qgsexpression.h"
 
class QgsTextDocument;
class QgsTextDocumentMetrics;
 
namespace pal SIP_SKIP
{
  class Pal;
  class Layer;
  class LabelPosition;
}
 
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 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, 
      LabelAllParts = 103, 
      PolygonLabelOutside = 109, 
      LineAnchorPercent = 111, 
      LineAnchorClipping = 112, 
      LineAnchorType = 115, 
      LineAnchorTextPoint = 116, 
 
      // 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, 
 
      // (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();
 
    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;
 
    bool labelPerPart = false;
 
    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; }
 
#ifndef SIP_RUN
    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,
                             QgsTextFormat *format = nullptr, QgsTextDocument *document = nullptr, QgsTextDocumentMetrics *documentMetrics = nullptr, QRectF *outerBounds = nullptr );
#else
    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 );
#endif
 
    void registerFeature( const QgsFeature &f, QgsRenderContext &context );
 
#ifndef SIP_RUN
 
    std::unique_ptr< QgsLabelFeature > registerFeatureWithDetails( const QgsFeature &feature, QgsRenderContext &context,
        QgsGeometry obstacleGeometry = QgsGeometry(), const QgsSymbol *symbol = nullptr );
#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 { return mLineSettings; } SIP_SKIP
 
    QgsLabelLineSettings &lineSettings() { return mLineSettings; }
 
    void setLineSettings( const QgsLabelLineSettings &settings ) { mLineSettings = settings; }
 
    const QgsLabelPointSettings &pointSettings() const { return mPointSettings; } SIP_SKIP
 
    QgsLabelPointSettings &pointSettings() { return mPointSettings; }
 
    void setPointSettings( const QgsLabelPointSettings &settings ) { mPointSettings = settings; }
 
    const QgsLabelObstacleSettings &obstacleSettings() const { return mObstacleSettings; } SIP_SKIP
 
    QgsLabelObstacleSettings &obstacleSettings() { return mObstacleSettings; }
 
    void setObstacleSettings( const QgsLabelObstacleSettings &settings ) { mObstacleSettings = settings; }
 
    const QgsLabelThinningSettings &thinningSettings() const { return mThinningSettings; } SIP_SKIP
 
    QgsLabelThinningSettings &thinningSettings() { return mThinningSettings; }
 
    void setThinningSettings( const QgsLabelThinningSettings &settings ) { mThinningSettings = settings; }
 
    const QgsLabelPlacementSettings &placementSettings() const { return mPlacementSettings; } SIP_SKIP
 
    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 );
 
    // 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)
    int mFeatsSendingToPal = 0; // total features tested for sending into PAL (relative to maxNumLabels)
    int mFeatsRegPal = 0; // number of features registered in PAL, when using limitNumLabels
 
  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 );
 
    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;
 
    std::unique_ptr< QgsLabelFeature > registerObstacleFeature( const QgsFeature &f, QgsRenderContext &context, const QgsGeometry &obstacleGeometry = QgsGeometry() );
 
    QMap<Property, QVariant> dataDefinedValues;
 
    QgsPropertyCollection mDataDefinedProperties;
 
    QgsExpression *expression = nullptr;
 
    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 QgsLabelCandidate
{
  public:
    QgsLabelCandidate( const QRectF &r, double c ): rect( r ), cost( c ) {}
 
    QRectF rect;
    double cost;
};
 
class CORE_EXPORT QgsPalLabeling
{
  public:
 
    static bool staticWillUseLayer( const QgsMapLayer *layer );
 
    static void drawLabelCandidateRect( pal::LabelPosition *lp, QPainter *painter, const QgsMapToPixel *xform, QList<QgsLabelCandidate> *candidates = nullptr ) SIP_SKIP;
 
    static QgsGeometry prepareGeometry( const QgsGeometry &geometry, QgsRenderContext &context, const QgsCoordinateTransform &ct, const QgsGeometry &clipGeometry = QgsGeometry(), bool mergeLines = false ) SIP_FACTORY;
 
    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