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.                                   *
 *                                                                         *
 ***************************************************************************/

//Note: although this file is in the core library, it is not part of the stable API
//and might change at any time!

#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 "qgslabelingenginesettings.h"
#include "qgspointxy.h"
#include "qgsmapunitscale.h"
#include "qgsstringutils.h"
#include "qgssymbol.h"
#include "qgstextrenderer.h"
#include "qgspropertycollection.h"

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 QgsMapSettings;
class QgsLabelFeature;
class QgsLabelingEngine;
class QgsPalLayerSettings;
class QgsVectorLayerLabelProvider;
class QgsDxfExport;
class QgsVectorLayerDiagramProvider;
class QgsExpressionContext;
class QgsCallout;

class CORE_EXPORT QgsLabelPosition
{
  public:

    QgsLabelPosition( QgsFeatureId id, double r, const QVector< QgsPointXY > &corners, const QgsRectangle &rect, double w, double h, const QString &layer, const QString &labeltext, const QFont &labelfont, bool upside_down, bool diagram = false, bool pinned = false, const QString &providerId = QString(),
                      const QgsGeometry &labelGeometry = QgsGeometry(), bool isUnplaced = false )
      : featureId( id )
      , rotation( r )
      , cornerPoints( corners )
      , labelRect( rect )
      , labelGeometry( labelGeometry )
      , width( w )
      , height( h )
      , layerID( layer )
      , labelText( labeltext )
      , labelFont( labelfont )
      , upsideDown( upside_down )
      , isDiagram( diagram )
      , isPinned( pinned )
      , providerID( providerId )
      , isUnplaced( isUnplaced )
    {}

    QgsLabelPosition() = default;

    QgsFeatureId featureId = FID_NULL;

    double rotation = 0;

    QVector< QgsPointXY > cornerPoints;
    QgsRectangle labelRect;

    QgsGeometry labelGeometry;

    double width = 0;

    double height = 0;

    QString layerID;

    QString labelText;

    QFont labelFont;

    bool upsideDown = false;

    bool isDiagram = false;

    bool isPinned = false;

    QString providerID;

    bool isUnplaced = false;
};


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

    QgsPalLayerSettings &operator=( const QgsPalLayerSettings &s );

    //TODO QGIS 4.0 - move to QgsLabelingEngine

    enum Placement
    {
      AroundPoint, 
      OverPoint, 
      Line, 
      Curved, 
      Horizontal, 
      Free, 
      OrderedPositionsAroundPoint, 
      PerimeterCurved, 
    };

    //TODO QGIS 4.0 - move to QgsLabelingEngine
    enum PredefinedPointPosition
    {
      TopLeft, 
      TopSlightlyLeft, 
      TopMiddle, 
      TopSlightlyRight, 
      TopRight, 
      MiddleLeft, 
      MiddleRight, 
      BottomLeft, 
      BottomSlightlyLeft, 
      BottomMiddle, 
      BottomSlightlyRight, 
      BottomRight, 
    };

    //TODO QGIS 4.0 - move to QgsLabelingEngine

    enum OffsetType
    {
      FromPoint, 
      FromSymbolBounds, 
    };

    //TODO QGIS 4.0 - move to QgsLabelingEngine, rename to LinePlacementFlag, use Q_DECLARE_FLAGS to make
    //LinePlacementFlags type, and replace use of pal::LineArrangementFlag

    enum LinePlacementFlags
    {
      OnLine    = 1,      
      AboveLine = 2,      
      BelowLine = 4,      
      MapOrientation = 8, 
    };

    enum QuadrantPosition
    {
      QuadrantAboveLeft,
      QuadrantAbove,
      QuadrantAboveRight,
      QuadrantLeft,
      QuadrantOver,
      QuadrantRight,
      QuadrantBelowLeft,
      QuadrantBelow,
      QuadrantBelowRight,
    };

    enum UpsideDownLabels
    {
      Upright, 
      ShowDefined, 
      ShowAll 
    };

    enum DirectionSymbols
    {
      SymbolLeftRight, 
      SymbolAbove, 
      SymbolBelow 
    };

    enum MultiLineAlign
    {
      MultiLeft = 0,
      MultiCenter,
      MultiRight,
      MultiFollowPlacement 
    };

    //TODO QGIS 4.0 - Move to QgsLabelingEngine

    enum ObstacleType
    {
      PolygonInterior, 
      PolygonBoundary, 
      PolygonWhole 
    };

    enum Property
    {
      // 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, 

      // text formatting
      MultiLineWrapChar = 31,
      AutoWrapLength = 101,
      MultiLineHeight = 32,
      MultiLineAlignment = 33,
      TextOrientation = 104,
      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,

      // 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,
      DistanceUnits = 81,
      OffsetRotation = 82,
      CurvedCharAngleInOut = 83,
      // (data defined only)
      PositionX = 9, 
      PositionY = 10, 
      Hali = 11, 
      Vali = 12, 
      Rotation = 14, 
      LabelRotation = 96, 
      RepeatDistance = 84,
      RepeatDistanceUnit = 86,
      Priority = 87,
      PredefinedPositionOrder = 91,
      LinePlacementOptions = 99, 
      OverrunDistance = 102, 
      LabelAllParts = 103, 

      // 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, 

      // (data defined only)
      Show = 15,
      AlwaysShow = 20
    };


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

    void startRender( QgsRenderContext &context );

    void stopRender( QgsRenderContext &context );

    static const QgsPropertiesDefinition &propertyDefinitions();

    bool drawLabels;

    //-- text style

    QString fieldName;

    bool isExpression;

    QgsExpression *getLabelExpression();

    Q_DECL_DEPRECATED QColor previewBkgrdColor = Qt::white;

    QgsStringReplacementCollection substitutions;
    bool useSubstitutions;

    //-- text formatting

    QString wrapChar;

    int autoWrapLength = 0;

    bool useMaxLineLengthForAutoWrap = true;

    MultiLineAlign multilineAlign;

    bool addDirectionSymbol;

    QString leftDirectionSymbol;

    QString rightDirectionSymbol;

    DirectionSymbols placeDirectionSymbol;

    bool reverseDirectionSymbol;

    bool formatNumbers;

    int decimals;

    bool plusSign;

    //-- placement

    Placement placement;
    unsigned int placementFlags;

    bool centroidWhole;

    bool centroidInside;

    QVector< PredefinedPointPosition > predefinedPositionOrder SIP_SKIP;

    bool fitInPolygonOnly;

    double dist;

    QgsUnitTypes::RenderUnit distUnits;

    QgsMapUnitScale distMapUnitScale;

    OffsetType offsetType;

    double repeatDistance;

    QgsUnitTypes::RenderUnit repeatDistanceUnit;

    QgsMapUnitScale repeatDistanceMapUnitScale;

    double overrunDistance = 0;

    QgsUnitTypes::RenderUnit overrunDistanceUnit = QgsUnitTypes::RenderMillimeters;

    QgsMapUnitScale overrunDistanceMapUnitScale;

    QuadrantPosition quadOffset;

    double xOffset;

    double yOffset;

    QgsUnitTypes::RenderUnit offsetUnits;

    QgsMapUnitScale labelOffsetMapUnitScale;

    double angleOffset;

    bool preserveRotation;

    double maxCurvedCharAngleIn;

    double maxCurvedCharAngleOut;

    int priority;

    //-- rendering

    bool scaleVisibility;

    double maximumScale;

    double minimumScale;

    bool fontLimitPixelSize;

    int fontMinPixelSize;

    int fontMaxPixelSize;

    bool displayAll;

    UpsideDownLabels upsidedownLabels = Upright;

    bool labelPerPart;

    bool mergeLines;

    bool limitNumLabels;

    int maxNumLabels;

    double minFeatureSize;

    bool obstacle;

    double obstacleFactor;

    ObstacleType obstacleType;

    double zIndex;

    QString geometryGenerator;

    QgsWkbTypes::GeometryType geometryGeneratorType = QgsWkbTypes::GeometryType::PointGeometry;

    bool geometryGeneratorEnabled = false;

    QgsWkbTypes::GeometryType layerType = QgsWkbTypes::UnknownGeometry;

    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 );

    void registerFeature( const QgsFeature &f, QgsRenderContext &context,
                          QgsLabelFeature **labelFeature SIP_PYARGREMOVE = nullptr,
                          QgsGeometry obstacleGeometry SIP_PYARGREMOVE = QgsGeometry(), const QgsSymbol *symbol SIP_PYARGREMOVE = nullptr );

    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 );

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

    // temporary stuff: set when layer gets prepared or labeled
    const QgsFeature *mCurFeat = nullptr;
    QgsFields mCurFields;
    int fieldIndex;
    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,
                         QgsUnitTypes::RenderUnit fontunits,
                         QgsRenderContext &context );

    void parseTextBuffer( 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;

    void registerObstacleFeature( const QgsFeature &f, QgsRenderContext &context, QgsLabelFeature **obstacleFeature, const QgsGeometry &obstacleGeometry = QgsGeometry() );

    QMap<Property, QVariant> dataDefinedValues;

    QgsPropertyCollection mDataDefinedProperties;

    QgsExpression *expression = nullptr;

    QFontDatabase mFontDB;

    QgsTextFormat mFormat;

    std::unique_ptr< QgsCallout > mCallout;

    QgsExpression mGeometryGeneratorExpression;

    bool mRenderStarted = false;

    static const QVector< PredefinedPointPosition > DEFAULT_PLACEMENT_ORDER;

    static void initPropertyDefinitions();

    static QgsPropertiesDefinition sPropertyDefinitions;

};

class CORE_EXPORT QgsLabelCandidate
{
  public:
    QgsLabelCandidate( const QRectF &r, double c ): rect( r ), cost( c ) {}

    QRectF rect;
    double cost;
};




class CORE_EXPORT QgsLabelingResults
{
  public:
    QgsLabelingResults();
    ~QgsLabelingResults();

    QgsLabelingResults( const QgsLabelingResults & ) = delete;
    QgsLabelingResults &operator=( const QgsLabelingResults &rh ) = delete;

    QList<QgsLabelPosition> labelsAtPosition( const QgsPointXY &p ) const;
    QList<QgsLabelPosition> labelsWithinRect( const QgsRectangle &r ) const;

    void setMapSettings( const QgsMapSettings &settings );

  private:
#ifdef SIP_RUN
    QgsLabelingResults( const QgsLabelingResults & );
#endif

    std::unique_ptr< QgsLabelSearchTree > mLabelSearchTree;

    friend class QgsPalLabeling;
    friend class QgsVectorLayerLabelProvider;
    friend class QgsVectorLayerDiagramProvider;
};

class CORE_EXPORT QgsPalLabeling
{
  public:

    static bool staticWillUseLayer( QgsVectorLayer *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 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