QGIS API Documentation  3.14.0-Pi (9f7028fd23)
qgscallout.h
Go to the documentation of this file.
1 /***************************************************************************
2  qgscallout.h
3  ----------------
4  begin : July 2019
5  copyright : (C) 2019 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 #ifndef QGSCALLOUT_H
18 #define QGSCALLOUT_H
19 
20 #include "qgis_core.h"
21 #include "qgis_sip.h"
22 #include "qgsexpressioncontext.h"
23 #include "qgsreadwritecontext.h"
24 #include "qgspropertycollection.h"
25 #include "qgsmapunitscale.h"
26 #include <QString>
27 #include <QRectF>
28 #include <memory>
29 
30 class QgsLineSymbol;
31 class QgsGeometry;
32 class QgsRenderContext;
33 
34 class QgsCalloutWidget; //stop sip breaking
35 
46 class CORE_EXPORT QgsCallout
47 {
48 
49 #ifdef SIP_RUN
51  if ( sipCpp->type() == "simple" && dynamic_cast<QgsSimpleLineCallout *>( sipCpp ) != NULL )
52  {
53  sipType = sipType_QgsSimpleLineCallout;
54  }
55  else if ( sipCpp->type() == "manhattan" && dynamic_cast<QgsManhattanLineCallout *>( sipCpp ) != NULL )
56  {
57  sipType = sipType_QgsManhattanLineCallout;
58  }
59  else
60  {
61  sipType = 0;
62  }
63  SIP_END
64 #endif
65 
66  public:
67 
69  enum Property
70  {
77  };
78 
80  enum DrawOrder
81  {
84  };
85 
88  {
89  PoleOfInaccessibility = 0,
93  };
94 
100  {
111  };
112 
116  QgsCallout();
117  virtual ~QgsCallout() = default;
118 
122  virtual QString type() const = 0;
123 
129  virtual QgsCallout *clone() const = 0 SIP_FACTORY;
130 
141  virtual QVariantMap properties( const QgsReadWriteContext &context ) const;
142 
152  virtual void readProperties( const QVariantMap &props, const QgsReadWriteContext &context );
153 
161  virtual bool saveProperties( QDomDocument &doc, QDomElement &element, const QgsReadWriteContext &context ) const;
162 
170  virtual void restoreProperties( const QDomElement &element, const QgsReadWriteContext &context );
171 
180  virtual void startRender( QgsRenderContext &context );
181 
190  virtual void stopRender( QgsRenderContext &context );
191 
199  virtual QSet< QString > referencedFields( const QgsRenderContext &context ) const;
200 
206  virtual DrawOrder drawOrder() const;
207 
214  struct CORE_EXPORT QgsCalloutContext
215  {
217  bool allFeaturePartsLabeled = false;
218  };
219 
241  void render( QgsRenderContext &context, QRectF rect, const double angle, const QgsGeometry &anchor, QgsCalloutContext &calloutContext );
242 
247  bool enabled() const { return mEnabled; }
248 
253  void setEnabled( bool enabled );
254 
259  QgsPropertyCollection &dataDefinedProperties() { return mDataDefinedProperties; }
260 
267  const QgsPropertyCollection &dataDefinedProperties() const SIP_SKIP { return mDataDefinedProperties; }
268 
277  void setDataDefinedProperties( const QgsPropertyCollection &collection ) { mDataDefinedProperties = collection; }
278 
282  static QgsPropertiesDefinition propertyDefinitions();
283 
289  AnchorPoint anchorPoint() const { return mAnchorPoint; }
290 
296  void setAnchorPoint( AnchorPoint anchor ) { mAnchorPoint = anchor; }
297 
303  static QString encodeAnchorPoint( AnchorPoint anchor );
304 
313  static QgsCallout::AnchorPoint decodeAnchorPoint( const QString &name, bool *ok = nullptr );
314 
315 
322  LabelAnchorPoint labelAnchorPoint() const { return mLabelAnchorPoint; }
323 
330  void setLabelAnchorPoint( LabelAnchorPoint anchor ) { mLabelAnchorPoint = anchor; }
331 
338  static QString encodeLabelAnchorPoint( LabelAnchorPoint anchor );
339 
349  static QgsCallout::LabelAnchorPoint decodeLabelAnchorPoint( const QString &name, bool *ok = nullptr );
350 
351  protected:
352 
371  virtual void draw( QgsRenderContext &context, QRectF bodyBoundingBox, const double angle, const QgsGeometry &anchor, QgsCalloutContext &calloutContext ) = 0;
372 
377  QgsGeometry labelAnchorGeometry( QRectF bodyBoundingBox, const double angle, LabelAnchorPoint anchor ) const;
378 
379  private:
380 
381  bool mEnabled = false;
382 
383  AnchorPoint mAnchorPoint = PoleOfInaccessibility;
384  LabelAnchorPoint mLabelAnchorPoint = LabelPointOnExterior;
385 
387  QgsPropertyCollection mDataDefinedProperties;
388 
390  static QgsPropertiesDefinition sPropertyDefinitions;
391 
392  static void initPropertyDefinitions();
393 };
394 
401 class CORE_EXPORT QgsSimpleLineCallout : public QgsCallout
402 {
403  public:
404 
406  ~QgsSimpleLineCallout() override;
407 
408 #ifndef SIP_RUN
409 
414  QgsSimpleLineCallout &operator=( const QgsSimpleLineCallout & ) = delete;
415 #endif
416 
422  static QgsCallout *create( const QVariantMap &properties = QVariantMap(), const QgsReadWriteContext &context = QgsReadWriteContext() ) SIP_FACTORY;
423 
424  QString type() const override;
425  QgsSimpleLineCallout *clone() const override;
426  QVariantMap properties( const QgsReadWriteContext &context ) const override;
427  void readProperties( const QVariantMap &props, const QgsReadWriteContext &context ) override;
428  void startRender( QgsRenderContext &context ) override;
429  void stopRender( QgsRenderContext &context ) override;
430  QSet< QString > referencedFields( const QgsRenderContext &context ) const override;
431 
439  QgsLineSymbol *lineSymbol();
440 
447  void setLineSymbol( QgsLineSymbol *symbol SIP_TRANSFER );
448 
454  double minimumLength() const { return mMinCalloutLength; }
455 
461  void setMinimumLength( double length ) { mMinCalloutLength = length; }
462 
468  void setMinimumLengthUnit( QgsUnitTypes::RenderUnit unit ) { mMinCalloutLengthUnit = unit; }
469 
475  QgsUnitTypes::RenderUnit minimumLengthUnit() const { return mMinCalloutLengthUnit; }
476 
483  void setMinimumLengthMapUnitScale( const QgsMapUnitScale &scale ) { mMinCalloutLengthScale = scale; }
484 
491  const QgsMapUnitScale &minimumLengthMapUnitScale() const { return mMinCalloutLengthScale; }
492 
493 
499  double offsetFromAnchor() const { return mOffsetFromAnchorDistance; }
500 
506  void setOffsetFromAnchor( double distance ) { mOffsetFromAnchorDistance = distance; }
507 
513  void setOffsetFromAnchorUnit( QgsUnitTypes::RenderUnit unit ) { mOffsetFromAnchorUnit = unit; }
514 
520  QgsUnitTypes::RenderUnit offsetFromAnchorUnit() const { return mOffsetFromAnchorUnit; }
521 
528  void setOffsetFromAnchorMapUnitScale( const QgsMapUnitScale &scale ) { mOffsetFromAnchorScale = scale; }
529 
536  const QgsMapUnitScale &offsetFromAnchorMapUnitScale() const { return mOffsetFromAnchorScale; }
537 
543  double offsetFromLabel() const { return mOffsetFromLabelDistance; }
544 
550  void setOffsetFromLabel( double distance ) { mOffsetFromLabelDistance = distance; }
551 
557  void setOffsetFromLabelUnit( QgsUnitTypes::RenderUnit unit ) { mOffsetFromLabelUnit = unit; }
558 
564  QgsUnitTypes::RenderUnit offsetFromLabelUnit() const { return mOffsetFromLabelUnit; }
565 
572  void setOffsetFromLabelMapUnitScale( const QgsMapUnitScale &scale ) { mOffsetFromLabelScale = scale; }
573 
580  const QgsMapUnitScale &offsetFromLabelMapUnitScale() const { return mOffsetFromLabelScale; }
581 
587  bool drawCalloutToAllParts() const { return mDrawCalloutToAllParts; }
588 
594  void setDrawCalloutToAllParts( bool drawToAllParts ) { mDrawCalloutToAllParts = drawToAllParts; }
595 
596  protected:
597  void draw( QgsRenderContext &context, QRectF bodyBoundingBox, const double angle, const QgsGeometry &anchor, QgsCallout::QgsCalloutContext &calloutContext ) override;
598 
599  private:
600 
601 #ifdef SIP_RUN
603  QgsSimpleLineCallout &operator=( const QgsSimpleLineCallout & );
604 #endif
605 
606  std::unique_ptr< QgsLineSymbol > mLineSymbol;
607  double mMinCalloutLength = 0;
609  QgsMapUnitScale mMinCalloutLengthScale;
610 
611  double mOffsetFromAnchorDistance = 0;
613  QgsMapUnitScale mOffsetFromAnchorScale;
614 
615  double mOffsetFromLabelDistance = 0;
617  QgsMapUnitScale mOffsetFromLabelScale;
618 
619  bool mDrawCalloutToAllParts = false;
620 };
621 
622 
630 {
631  public:
632 
634 
635 #ifndef SIP_RUN
636 
641 
643 #endif
644 
650  static QgsCallout *create( const QVariantMap &properties = QVariantMap(), const QgsReadWriteContext &context = QgsReadWriteContext() ) SIP_FACTORY;
651 
652  QString type() const override;
653  QgsManhattanLineCallout *clone() const override;
654 
655  protected:
656  void draw( QgsRenderContext &context, QRectF bodyBoundingBox, const double angle, const QgsGeometry &anchor, QgsCallout::QgsCalloutContext &calloutContext ) override;
657 
658  private:
659 #ifdef SIP_RUN
662 #endif
663 };
664 
665 
666 #endif // QGSCALLOUT_H
667 
QgsSimpleLineCallout::offsetFromLabelUnit
QgsUnitTypes::RenderUnit offsetFromLabelUnit() const
Returns the units for the offset from label area.
Definition: qgscallout.h:564
QgsSimpleLineCallout::setMinimumLengthMapUnitScale
void setMinimumLengthMapUnitScale(const QgsMapUnitScale &scale)
Sets the map unit scale for the minimum callout length.
Definition: qgscallout.h:483
QgsCallout::LabelPointOnExterior
@ LabelPointOnExterior
The point on the label's boundary closest to the feature.
Definition: qgscallout.h:101
QgsCalloutWidget
Definition: qgscalloutwidget.h:34
QgsCallout::OffsetFromAnchor
@ OffsetFromAnchor
Distance to offset lines from anchor points.
Definition: qgscallout.h:72
QgsSimpleLineCallout::offsetFromAnchor
double offsetFromAnchor() const
Returns the offset distance from the anchor point at which to start the line.
Definition: qgscallout.h:499
QgsUnitTypes::RenderUnit
RenderUnit
Rendering size units.
Definition: qgsunittypes.h:166
QgsCallout::AnchorPoint
AnchorPoint
Feature's anchor point position.
Definition: qgscallout.h:87
QgsReadWriteContext
Definition: qgsreadwritecontext.h:34
QgsCallout
Abstract base class for callout renderers.
Definition: qgscallout.h:46
QgsSimpleLineCallout::setOffsetFromAnchorUnit
void setOffsetFromAnchorUnit(QgsUnitTypes::RenderUnit unit)
Sets the unit for the offset from anchor distance.
Definition: qgscallout.h:513
qgsreadwritecontext.h
QgsRenderContext
Definition: qgsrendercontext.h:57
QgsSimpleLineCallout::setOffsetFromLabel
void setOffsetFromLabel(double distance)
Sets the offset distance from label area at which to end the line.
Definition: qgscallout.h:550
QgsCallout::dataDefinedProperties
const QgsPropertyCollection & dataDefinedProperties() const
Returns a reference to the callout's property collection, used for data defined overrides.
Definition: qgscallout.h:267
QgsCallout::anchorPoint
AnchorPoint anchorPoint() const
Returns the feature's anchor point position.
Definition: qgscallout.h:289
QgsUnitTypes::RenderMillimeters
@ RenderMillimeters
Millimeters.
Definition: qgsunittypes.h:168
QgsCallout::LabelCentroid
@ LabelCentroid
The labe's centroid.
Definition: qgscallout.h:102
QgsSimpleLineCallout::create
static QgsCallout * create(const QVariantMap &properties=QVariantMap(), const QgsReadWriteContext &context=QgsReadWriteContext())
Creates a new QgsSimpleLineCallout, using the settings serialized in the properties map (correspondin...
Definition: qgscallout.cpp:336
QgsCallout::LabelBottomMiddle
@ LabelBottomMiddle
Bottom middle of the label's boundary.
Definition: qgscallout.h:109
QgsSimpleLineCallout::clone
QgsSimpleLineCallout * clone() const override
Duplicates a callout by creating a deep copy of the callout.
Definition: qgscallout.cpp:348
QgsCallout::type
virtual QString type() const =0
Returns a unique string representing the callout type.
QgsCallout::AnchorPointPosition
@ AnchorPointPosition
Feature's anchor point position.
Definition: qgscallout.h:75
QgsCallout::PointOnExterior
@ PointOnExterior
A point on the surface's outline closest to the label is used as anchor for polygon geometries.
Definition: qgscallout.h:90
QgsCallout::LabelMiddleRight
@ LabelMiddleRight
Middle right of the label's boundary.
Definition: qgscallout.h:107
QgsSimpleLineCallout::setOffsetFromLabelMapUnitScale
void setOffsetFromLabelMapUnitScale(const QgsMapUnitScale &scale)
Sets the map unit scale for the offset from label area.
Definition: qgscallout.h:572
SIP_FACTORY
#define SIP_FACTORY
Definition: qgis_sip.h:76
QgsCallout::LabelTopLeft
@ LabelTopLeft
Top left corner of the label's boundary.
Definition: qgscallout.h:103
QgsSimpleLineCallout::setMinimumLengthUnit
void setMinimumLengthUnit(QgsUnitTypes::RenderUnit unit)
Sets the unit for the minimum length of callout lines.
Definition: qgscallout.h:468
SIP_CONVERT_TO_SUBCLASS_CODE
#define SIP_CONVERT_TO_SUBCLASS_CODE(code)
Definition: qgis_sip.h:172
QgsSimpleLineCallout::minimumLength
double minimumLength() const
Returns the minimum length of callout lines.
Definition: qgscallout.h:454
QgsPropertiesDefinition
QMap< int, QgsPropertyDefinition > QgsPropertiesDefinition
Definition of available properties.
Definition: qgspropertycollection.h:29
AnchorPoint
record about vertex coordinates and index of anchor to which it is snapped
Definition: qgsgeometrysnappersinglesource.cpp:29
QgsSimpleLineCallout::offsetFromLabel
double offsetFromLabel() const
Returns the offset distance from label area at which to end the line.
Definition: qgscallout.h:543
qgsexpressioncontext.h
SIP_SKIP
#define SIP_SKIP
Definition: qgis_sip.h:126
QgsCallout::LabelAnchorPointPosition
@ LabelAnchorPointPosition
Label's anchor point position.
Definition: qgscallout.h:76
QgsCallout::setDataDefinedProperties
void setDataDefinedProperties(const QgsPropertyCollection &collection)
Sets the callout's property collection, used for data defined overrides.
Definition: qgscallout.h:277
qgis_sip.h
QgsCallout::labelAnchorPoint
LabelAnchorPoint labelAnchorPoint() const
Returns the label's anchor point position.
Definition: qgscallout.h:322
SIP_TRANSFER
#define SIP_TRANSFER
Definition: qgis_sip.h:36
QgsLineSymbol
Definition: qgssymbol.h:1117
QgsCallout::DrawCalloutToAllParts
@ DrawCalloutToAllParts
Whether callout lines should be drawn to all feature parts.
Definition: qgscallout.h:74
QgsCallout::Centroid
@ Centroid
The surface's centroid is used as anchor for polygon geometries.
Definition: qgscallout.h:92
QgsSimpleLineCallout::offsetFromAnchorMapUnitScale
const QgsMapUnitScale & offsetFromAnchorMapUnitScale() const
Returns the map unit scale for the offset from anchor.
Definition: qgscallout.h:536
QgsSimpleLineCallout::setMinimumLength
void setMinimumLength(double length)
Sets the minimum length of callout lines.
Definition: qgscallout.h:461
QgsCallout::setLabelAnchorPoint
void setLabelAnchorPoint(LabelAnchorPoint anchor)
Sets the label's anchor point position.
Definition: qgscallout.h:330
QgsSimpleLineCallout::setOffsetFromAnchorMapUnitScale
void setOffsetFromAnchorMapUnitScale(const QgsMapUnitScale &scale)
Sets the map unit scale for the offset from anchor.
Definition: qgscallout.h:528
QgsMapUnitScale
Struct for storing maximum and minimum scales for measurements in map units.
Definition: qgsmapunitscale.h:37
QgsSimpleLineCallout
A simple direct line callout style.
Definition: qgscallout.h:401
QgsSimpleLineCallout::draw
void draw(QgsRenderContext &context, QRectF bodyBoundingBox, const double angle, const QgsGeometry &anchor, QgsCallout::QgsCalloutContext &calloutContext) override
Performs the actual rendering of the callout implementation onto the specified render context.
Definition: qgscallout.cpp:435
QgsCallout::readProperties
virtual void readProperties(const QVariantMap &props, const QgsReadWriteContext &context)
Reads a string map of an callout's properties and restores the callout to the state described by the ...
Definition: qgscallout.cpp:67
QgsSimpleLineCallout::setDrawCalloutToAllParts
void setDrawCalloutToAllParts(bool drawToAllParts)
Sets whether callout lines should be drawn to all feature parts.
Definition: qgscallout.h:594
QgsSimpleLineCallout::setOffsetFromLabelUnit
void setOffsetFromLabelUnit(QgsUnitTypes::RenderUnit unit)
Sets the unit for the offset from label area distance.
Definition: qgscallout.h:557
QgsCallout::DrawOrder
DrawOrder
Options for draw order (stacking) of callouts.
Definition: qgscallout.h:80
QgsCallout::properties
virtual QVariantMap properties(const QgsReadWriteContext &context) const
Returns the properties describing the callout encoded in a string format.
Definition: qgscallout.cpp:57
QgsPropertyCollection
A grouped map of multiple QgsProperty objects, each referenced by a integer key value.
Definition: qgspropertycollection.h:318
QgsSimpleLineCallout::offsetFromLabelMapUnitScale
const QgsMapUnitScale & offsetFromLabelMapUnitScale() const
Returns the map unit scale for the minimum callout length.
Definition: qgscallout.h:580
QgsCallout::LabelBottomLeft
@ LabelBottomLeft
Bottom left corner of the label's boundary.
Definition: qgscallout.h:108
QgsManhattanLineCallout
Draws straight (right angled) lines as callouts.
Definition: qgscallout.h:629
QgsSimpleLineCallout::minimumLengthMapUnitScale
const QgsMapUnitScale & minimumLengthMapUnitScale() const
Returns the map unit scale for the minimum callout length.
Definition: qgscallout.h:491
QgsSimpleLineCallout::offsetFromAnchorUnit
QgsUnitTypes::RenderUnit offsetFromAnchorUnit() const
Returns the units for the offset from anchor point.
Definition: qgscallout.h:520
QgsGeometry
Definition: qgsgeometry.h:122
QgsSimpleLineCallout::minimumLengthUnit
QgsUnitTypes::RenderUnit minimumLengthUnit() const
Returns the units for the minimum length of callout lines.
Definition: qgscallout.h:475
QgsSimpleLineCallout::operator=
QgsSimpleLineCallout & operator=(const QgsSimpleLineCallout &)=delete
QgsCallout::referencedFields
virtual QSet< QString > referencedFields(const QgsRenderContext &context) const
Returns the set of attributes referenced by the callout.
Definition: qgscallout.cpp:107
QgsCallout::MinimumCalloutLength
@ MinimumCalloutLength
Minimum length of callouts.
Definition: qgscallout.h:71
QgsCallout::QgsCalloutContext
Contains additional contextual information about the context in which a callout is being rendered.
Definition: qgscallout.h:214
qgspropertycollection.h
QgsCallout::LabelMiddleLeft
@ LabelMiddleLeft
Middle left of the label's boundary.
Definition: qgscallout.h:106
QgsCallout::draw
virtual void draw(QgsRenderContext &context, QRectF bodyBoundingBox, const double angle, const QgsGeometry &anchor, QgsCalloutContext &calloutContext)=0
Performs the actual rendering of the callout implementation onto the specified render context.
QgsCallout::LabelBottomRight
@ LabelBottomRight
Bottom right corner of the label's boundary.
Definition: qgscallout.h:110
qgsmapunitscale.h
QgsCallout::LabelTopMiddle
@ LabelTopMiddle
Top middle of the label's boundary.
Definition: qgscallout.h:104
QgsSimpleLineCallout::type
QString type() const override
Returns a unique string representing the callout type.
Definition: qgscallout.cpp:343
QgsCallout::startRender
virtual void startRender(QgsRenderContext &context)
Prepares the callout for rendering on the specified render context.
Definition: qgscallout.cpp:98
QgsCallout::stopRender
virtual void stopRender(QgsRenderContext &context)
Finalises the callout after a set of rendering operations on the specified render context.
Definition: qgscallout.cpp:102
QgsCallout::Property
Property
Data definable properties.
Definition: qgscallout.h:69
QgsSimpleLineCallout::drawCalloutToAllParts
bool drawCalloutToAllParts() const
Returns true if callout lines should be drawn to all feature parts.
Definition: qgscallout.h:587
QgsCallout::OrderBelowAllLabels
@ OrderBelowAllLabels
Render callouts below all labels.
Definition: qgscallout.h:82
QgsCallout::OrderBelowIndividualLabels
@ OrderBelowIndividualLabels
Render callouts below their individual associated labels, some callouts may be drawn over other label...
Definition: qgscallout.h:83
QgsCallout::clone
virtual QgsCallout * clone() const =0
Duplicates a callout by creating a deep copy of the callout.
MathUtils::angle
double ANALYSIS_EXPORT angle(QgsPoint *p1, QgsPoint *p2, QgsPoint *p3, QgsPoint *p4)
Calculates the angle between two segments (in 2 dimension, z-values are ignored)
Definition: MathUtils.cpp:786
SIP_END
#define SIP_END
Definition: qgis_sip.h:189
QgsCallout::LabelAnchorPoint
LabelAnchorPoint
Label's anchor point position.
Definition: qgscallout.h:99
QgsCallout::OffsetFromLabel
@ OffsetFromLabel
Distance to offset lines from label area.
Definition: qgscallout.h:73
QgsSimpleLineCallout::setOffsetFromAnchor
void setOffsetFromAnchor(double distance)
Sets the offset distance from the anchor point at which to start the line.
Definition: qgscallout.h:506
QgsCallout::setAnchorPoint
void setAnchorPoint(AnchorPoint anchor)
Sets the feature's anchor point position.
Definition: qgscallout.h:296
QgsCallout::dataDefinedProperties
QgsPropertyCollection & dataDefinedProperties()
Returns a reference to the callout's property collection, used for data defined overrides.
Definition: qgscallout.h:259
QgsCallout::enabled
bool enabled() const
Returns true if the the callout is enabled.
Definition: qgscallout.h:247
QgsCallout::PointOnSurface
@ PointOnSurface
A point guaranteed to be on the surface is used as anchor for polygon geometries.
Definition: qgscallout.h:91
QgsCallout::LabelTopRight
@ LabelTopRight
Top right corner of the label's boundary.
Definition: qgscallout.h:105