QGIS API Documentation  3.10.0-A Coruña (6c816b4204)
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  {
76  };
77 
79  enum DrawOrder
80  {
83  };
84 
87  {
88  PoleOfInaccessibility = 0,
92  };
93 
97  QgsCallout();
98  virtual ~QgsCallout() = default;
99 
103  virtual QString type() const = 0;
104 
110  virtual QgsCallout *clone() const = 0 SIP_FACTORY;
111 
122  virtual QVariantMap properties( const QgsReadWriteContext &context ) const;
123 
133  virtual void readProperties( const QVariantMap &props, const QgsReadWriteContext &context );
134 
142  virtual bool saveProperties( QDomDocument &doc, QDomElement &element, const QgsReadWriteContext &context ) const;
143 
151  virtual void restoreProperties( const QDomElement &element, const QgsReadWriteContext &context );
152 
161  virtual void startRender( QgsRenderContext &context );
162 
171  virtual void stopRender( QgsRenderContext &context );
172 
180  virtual QSet< QString > referencedFields( const QgsRenderContext &context ) const;
181 
187  virtual DrawOrder drawOrder() const;
188 
195  struct CORE_EXPORT QgsCalloutContext
196  {
198  bool allFeaturePartsLabeled = false;
199  };
200 
222  void render( QgsRenderContext &context, QRectF rect, const double angle, const QgsGeometry &anchor, QgsCalloutContext &calloutContext );
223 
228  bool enabled() const { return mEnabled; }
229 
234  void setEnabled( bool enabled );
235 
240  QgsPropertyCollection &dataDefinedProperties() { return mDataDefinedProperties; }
241 
248  const QgsPropertyCollection &dataDefinedProperties() const SIP_SKIP { return mDataDefinedProperties; }
249 
258  void setDataDefinedProperties( const QgsPropertyCollection &collection ) { mDataDefinedProperties = collection; }
259 
263  static QgsPropertiesDefinition propertyDefinitions();
264 
270  AnchorPoint anchorPoint() const { return mAnchorPoint; }
271 
277  void setAnchorPoint( AnchorPoint anchor ) { mAnchorPoint = anchor; }
278 
284  static QString encodeAnchorPoint( AnchorPoint anchor );
285 
294  static QgsCallout::AnchorPoint decodeAnchorPoint( const QString &name, bool *ok = nullptr );
295 
296  protected:
297 
316  virtual void draw( QgsRenderContext &context, QRectF bodyBoundingBox, const double angle, const QgsGeometry &anchor, QgsCalloutContext &calloutContext ) = 0;
317 
318  private:
319 
320  bool mEnabled = false;
321 
322  AnchorPoint mAnchorPoint = PoleOfInaccessibility;
323 
325  QgsPropertyCollection mDataDefinedProperties;
326 
328  static QgsPropertiesDefinition sPropertyDefinitions;
329 
330  static void initPropertyDefinitions();
331 };
332 
339 class CORE_EXPORT QgsSimpleLineCallout : public QgsCallout
340 {
341  public:
342 
344  ~QgsSimpleLineCallout() override;
345 
346 #ifndef SIP_RUN
347 
352  QgsSimpleLineCallout &operator=( const QgsSimpleLineCallout & ) = delete;
353 #endif
354 
360  static QgsCallout *create( const QVariantMap &properties = QVariantMap(), const QgsReadWriteContext &context = QgsReadWriteContext() ) SIP_FACTORY;
361 
362  QString type() const override;
363  QgsSimpleLineCallout *clone() const override;
364  QVariantMap properties( const QgsReadWriteContext &context ) const override;
365  void readProperties( const QVariantMap &props, const QgsReadWriteContext &context ) override;
366  void startRender( QgsRenderContext &context ) override;
367  void stopRender( QgsRenderContext &context ) override;
368  QSet< QString > referencedFields( const QgsRenderContext &context ) const override;
369 
377  QgsLineSymbol *lineSymbol();
378 
385  void setLineSymbol( QgsLineSymbol *symbol SIP_TRANSFER );
386 
392  double minimumLength() const { return mMinCalloutLength; }
393 
399  void setMinimumLength( double length ) { mMinCalloutLength = length; }
400 
406  void setMinimumLengthUnit( QgsUnitTypes::RenderUnit unit ) { mMinCalloutLengthUnit = unit; }
407 
413  QgsUnitTypes::RenderUnit minimumLengthUnit() const { return mMinCalloutLengthUnit; }
414 
421  void setMinimumLengthMapUnitScale( const QgsMapUnitScale &scale ) { mMinCalloutLengthScale = scale; }
422 
429  const QgsMapUnitScale &minimumLengthMapUnitScale() const { return mMinCalloutLengthScale; }
430 
431 
437  double offsetFromAnchor() const { return mOffsetFromAnchorDistance; }
438 
444  void setOffsetFromAnchor( double distance ) { mOffsetFromAnchorDistance = distance; }
445 
451  void setOffsetFromAnchorUnit( QgsUnitTypes::RenderUnit unit ) { mOffsetFromAnchorUnit = unit; }
452 
458  QgsUnitTypes::RenderUnit offsetFromAnchorUnit() const { return mOffsetFromAnchorUnit; }
459 
466  void setOffsetFromAnchorMapUnitScale( const QgsMapUnitScale &scale ) { mOffsetFromAnchorScale = scale; }
467 
474  const QgsMapUnitScale &offsetFromAnchorMapUnitScale() const { return mOffsetFromAnchorScale; }
475 
481  double offsetFromLabel() const { return mOffsetFromLabelDistance; }
482 
488  void setOffsetFromLabel( double distance ) { mOffsetFromLabelDistance = distance; }
489 
495  void setOffsetFromLabelUnit( QgsUnitTypes::RenderUnit unit ) { mOffsetFromLabelUnit = unit; }
496 
502  QgsUnitTypes::RenderUnit offsetFromLabelUnit() const { return mOffsetFromLabelUnit; }
503 
510  void setOffsetFromLabelMapUnitScale( const QgsMapUnitScale &scale ) { mOffsetFromLabelScale = scale; }
511 
518  const QgsMapUnitScale &offsetFromLabelMapUnitScale() const { return mOffsetFromLabelScale; }
519 
525  bool drawCalloutToAllParts() const { return mDrawCalloutToAllParts; }
526 
532  void setDrawCalloutToAllParts( bool drawToAllParts ) { mDrawCalloutToAllParts = drawToAllParts; }
533 
534  protected:
535  void draw( QgsRenderContext &context, QRectF bodyBoundingBox, const double angle, const QgsGeometry &anchor, QgsCallout::QgsCalloutContext &calloutContext ) override;
536 
537  private:
538 
539 #ifdef SIP_RUN
541  QgsSimpleLineCallout &operator=( const QgsSimpleLineCallout & );
542 #endif
543 
544  std::unique_ptr< QgsLineSymbol > mLineSymbol;
545  double mMinCalloutLength = 0;
547  QgsMapUnitScale mMinCalloutLengthScale;
548 
549  double mOffsetFromAnchorDistance = 0;
551  QgsMapUnitScale mOffsetFromAnchorScale;
552 
553  double mOffsetFromLabelDistance = 0;
555  QgsMapUnitScale mOffsetFromLabelScale;
556 
557  bool mDrawCalloutToAllParts = false;
558 };
559 
560 
568 {
569  public:
570 
572 
573 #ifndef SIP_RUN
574 
579 
581 #endif
582 
588  static QgsCallout *create( const QVariantMap &properties = QVariantMap(), const QgsReadWriteContext &context = QgsReadWriteContext() ) SIP_FACTORY;
589 
590  QString type() const override;
591  QgsManhattanLineCallout *clone() const override;
592 
593  protected:
594  void draw( QgsRenderContext &context, QRectF bodyBoundingBox, const double angle, const QgsGeometry &anchor, QgsCallout::QgsCalloutContext &calloutContext ) override;
595 
596  private:
597 #ifdef SIP_RUN
600 #endif
601 };
602 
603 
604 #endif // QGSCALLOUT_H
605 
void setOffsetFromLabelUnit(QgsUnitTypes::RenderUnit unit)
Sets the unit for the offset from label area distance.
Definition: qgscallout.h:495
QgsUnitTypes::RenderUnit minimumLengthUnit() const
Returns the units for the minimum length of callout lines.
Definition: qgscallout.h:413
The class is used as a container of context for various read/write operations on other objects...
double offsetFromLabel() const
Returns the offset distance from label area at which to end the line.
Definition: qgscallout.h:481
Abstract base class for callout renderers.
Definition: qgscallout.h:46
void setMinimumLengthUnit(QgsUnitTypes::RenderUnit unit)
Sets the unit for the minimum length of callout lines.
Definition: qgscallout.h:406
const QgsMapUnitScale & offsetFromAnchorMapUnitScale() const
Returns the map unit scale for the offset from anchor.
Definition: qgscallout.h:474
Minimum length of callouts.
Definition: qgscallout.h:71
virtual void stopRender(QgsRenderContext &context)
Finalises the callout after a set of rendering operations on the specified render context...
Definition: qgscallout.cpp:93
Distance to offset lines from anchor points.
Definition: qgscallout.h:72
Property
Data definable properties.
Definition: qgscallout.h:69
QgsUnitTypes::RenderUnit offsetFromAnchorUnit() const
Returns the units for the offset from anchor point.
Definition: qgscallout.h:458
Contains additional contextual information about the context in which a callout is being rendered...
Definition: qgscallout.h:195
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...
void setOffsetFromAnchorMapUnitScale(const QgsMapUnitScale &scale)
Sets the map unit scale for the offset from anchor.
Definition: qgscallout.h:466
virtual QgsCallout * clone() const =0
Duplicates a callout by creating a deep copy of the callout.
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:315
QString type() const override
Returns a unique string representing the callout type.
Definition: qgscallout.cpp:223
The surface&#39;s centroid is used as anchor for polygon geometries.
Definition: qgscallout.h:91
A geometry is the spatial representation of a feature.
Definition: qgsgeometry.h:122
Feature&#39;s anchor point position.
Definition: qgscallout.h:75
Base class for widgets which allow control over the properties of callouts.
const QgsMapUnitScale & minimumLengthMapUnitScale() const
Returns the map unit scale for the minimum callout length.
Definition: qgscallout.h:429
void setMinimumLength(double length)
Sets the minimum length of callout lines.
Definition: qgscallout.h:399
const QgsMapUnitScale & offsetFromLabelMapUnitScale() const
Returns the map unit scale for the minimum callout length.
Definition: qgscallout.h:518
void setAnchorPoint(AnchorPoint anchor)
Sets the feature&#39;s anchor point position.
Definition: qgscallout.h:277
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
A line symbol type, for rendering LineString and MultiLineString geometries.
Definition: qgssymbol.h:1060
void setDrawCalloutToAllParts(bool drawToAllParts)
Sets whether callout lines should be drawn to all feature parts.
Definition: qgscallout.h:532
virtual QSet< QString > referencedFields(const QgsRenderContext &context) const
Returns the set of attributes referenced by the callout.
Definition: qgscallout.cpp:98
void setOffsetFromAnchor(double distance)
Sets the offset distance from the anchor point at which to start the line.
Definition: qgscallout.h:444
Render callouts below their individual associated labels, some callouts may be drawn over other label...
Definition: qgscallout.h:82
#define SIP_SKIP
Definition: qgis_sip.h:126
QgsSimpleLineCallout & operator=(const QgsSimpleLineCallout &)=delete
#define SIP_TRANSFER
Definition: qgis_sip.h:36
#define SIP_END
Definition: qgis_sip.h:189
bool drawCalloutToAllParts() const
Returns true if callout lines should be drawn to all feature parts.
Definition: qgscallout.h:525
#define SIP_FACTORY
Definition: qgis_sip.h:76
Render callouts below all labels.
Definition: qgscallout.h:81
virtual void startRender(QgsRenderContext &context)
Prepares the callout for rendering on the specified render context.
Definition: qgscallout.cpp:89
Draws straight (right angled) lines as callouts.
Definition: qgscallout.h:567
Distance to offset lines from label area.
Definition: qgscallout.h:73
A simple direct line callout style.
Definition: qgscallout.h:339
QMap< int, QgsPropertyDefinition > QgsPropertiesDefinition
Definition of available properties.
void setOffsetFromLabel(double distance)
Sets the offset distance from label area at which to end the line.
Definition: qgscallout.h:488
void setOffsetFromAnchorUnit(QgsUnitTypes::RenderUnit unit)
Sets the unit for the offset from anchor distance.
Definition: qgscallout.h:451
A point on the surface&#39;s outline closest to the label is used as anchor for polygon geometries...
Definition: qgscallout.h:89
QgsUnitTypes::RenderUnit offsetFromLabelUnit() const
Returns the units for the offset from label area.
Definition: qgscallout.h:502
void setMinimumLengthMapUnitScale(const QgsMapUnitScale &scale)
Sets the map unit scale for the minimum callout length.
Definition: qgscallout.h:421
virtual QString type() const =0
Returns a unique string representing the callout type.
Whether callout lines should be drawn to all feature parts.
Definition: qgscallout.h:74
void setDataDefinedProperties(const QgsPropertyCollection &collection)
Sets the callout&#39;s property collection, used for data defined overrides.
Definition: qgscallout.h:258
double offsetFromAnchor() const
Returns the offset distance from the anchor point at which to start the line.
Definition: qgscallout.h:437
QgsPropertyCollection & dataDefinedProperties()
Returns a reference to the callout&#39;s property collection, used for data defined overrides.
Definition: qgscallout.h:240
Contains information about the context of a rendering operation.
bool enabled() const
Returns true if the the callout is enabled.
Definition: qgscallout.h:228
Struct for storing maximum and minimum scales for measurements in map units.
void setOffsetFromLabelMapUnitScale(const QgsMapUnitScale &scale)
Sets the map unit scale for the offset from label area.
Definition: qgscallout.h:510
#define SIP_CONVERT_TO_SUBCLASS_CODE(code)
Definition: qgis_sip.h:172
double minimumLength() const
Returns the minimum length of callout lines.
Definition: qgscallout.h:392
A grouped map of multiple QgsProperty objects, each referenced by a integer key value.
AnchorPoint
Feature&#39;s anchor point position.
Definition: qgscallout.h:86
const QgsPropertyCollection & dataDefinedProperties() const
Returns a reference to the callout&#39;s property collection, used for data defined overrides.
Definition: qgscallout.h:248
virtual void readProperties(const QVariantMap &props, const QgsReadWriteContext &context)
Reads a string map of an callout&#39;s properties and restores the callout to the state described by the ...
Definition: qgscallout.cpp:59
AnchorPoint anchorPoint() const
Returns the feature&#39;s anchor point position.
Definition: qgscallout.h:270
DrawOrder
Options for draw order (stacking) of callouts.
Definition: qgscallout.h:79
virtual QVariantMap properties(const QgsReadWriteContext &context) const
Returns the properties describing the callout encoded in a string format.
Definition: qgscallout.cpp:50
A point guaranteed to be on the surface is used as anchor for polygon geometries. ...
Definition: qgscallout.h:90
RenderUnit
Rendering size units.
Definition: qgsunittypes.h:145
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:216
QgsSimpleLineCallout * clone() const override
Duplicates a callout by creating a deep copy of the callout.
Definition: qgscallout.cpp:228
record about vertex coordinates and index of anchor to which it is snapped