QGIS API Documentation 3.37.0-Master (fdefdf9c27f)
Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
QgsSimpleLineCallout Class Reference

A simple direct line callout style. More...

#include <qgscallout.h>

Inheritance diagram for QgsSimpleLineCallout:
Inheritance graph
[legend]

Public Member Functions

 QgsSimpleLineCallout ()
 
 QgsSimpleLineCallout (const QgsSimpleLineCallout &other)
 Copy constructor. More...
 
 ~QgsSimpleLineCallout () override
 
QgsSimpleLineCalloutclone () const override
 Duplicates a callout by creating a deep copy of the callout. More...
 
bool drawCalloutToAllParts () const
 Returns true if callout lines should be drawn to all feature parts. More...
 
QgsLineSymbollineSymbol ()
 Returns the line symbol used to render the callout line. More...
 
double minimumLength () const
 Returns the minimum length of callout lines. More...
 
const QgsMapUnitScaleminimumLengthMapUnitScale () const
 Returns the map unit scale for the minimum callout length. More...
 
Qgis::RenderUnit minimumLengthUnit () const
 Returns the units for the minimum length of callout lines. More...
 
double offsetFromAnchor () const
 Returns the offset distance from the anchor point at which to start the line. More...
 
const QgsMapUnitScaleoffsetFromAnchorMapUnitScale () const
 Returns the map unit scale for the offset from anchor. More...
 
Qgis::RenderUnit offsetFromAnchorUnit () const
 Returns the units for the offset from anchor point. More...
 
double offsetFromLabel () const
 Returns the offset distance from label area at which to end the line. More...
 
const QgsMapUnitScaleoffsetFromLabelMapUnitScale () const
 Returns the map unit scale for the minimum callout length. More...
 
Qgis::RenderUnit offsetFromLabelUnit () const
 Returns the units for the offset from label area. More...
 
QgsSimpleLineCalloutoperator= (const QgsSimpleLineCallout &)=delete
 
QVariantMap properties (const QgsReadWriteContext &context) const override
 Returns the properties describing the callout encoded in a string format. More...
 
void readProperties (const QVariantMap &props, const QgsReadWriteContext &context) override
 Reads a string map of an callout's properties and restores the callout to the state described by the properties map. More...
 
QSet< QString > referencedFields (const QgsRenderContext &context) const override
 Returns the set of attributes referenced by the callout. More...
 
void setDrawCalloutToAllParts (bool drawToAllParts)
 Sets whether callout lines should be drawn to all feature parts. More...
 
void setLineSymbol (QgsLineSymbol *symbol)
 Sets the line symbol used to render the callout line. More...
 
void setMinimumLength (double length)
 Sets the minimum length of callout lines. More...
 
void setMinimumLengthMapUnitScale (const QgsMapUnitScale &scale)
 Sets the map unit scale for the minimum callout length. More...
 
void setMinimumLengthUnit (Qgis::RenderUnit unit)
 Sets the unit for the minimum length of callout lines. More...
 
void setOffsetFromAnchor (double distance)
 Sets the offset distance from the anchor point at which to start the line. More...
 
void setOffsetFromAnchorMapUnitScale (const QgsMapUnitScale &scale)
 Sets the map unit scale for the offset from anchor. More...
 
void setOffsetFromAnchorUnit (Qgis::RenderUnit unit)
 Sets the unit for the offset from anchor distance. More...
 
void setOffsetFromLabel (double distance)
 Sets the offset distance from label area at which to end the line. More...
 
void setOffsetFromLabelMapUnitScale (const QgsMapUnitScale &scale)
 Sets the map unit scale for the offset from label area. More...
 
void setOffsetFromLabelUnit (Qgis::RenderUnit unit)
 Sets the unit for the offset from label area distance. More...
 
void startRender (QgsRenderContext &context) override
 Prepares the callout for rendering on the specified render context. More...
 
void stopRender (QgsRenderContext &context) override
 Finalises the callout after a set of rendering operations on the specified render context. More...
 
QString type () const override
 Returns a unique string representing the callout type. More...
 
- Public Member Functions inherited from QgsCallout
 QgsCallout ()
 Constructor for QgsCallout. More...
 
virtual ~QgsCallout ()=default
 
AnchorPoint anchorPoint () const
 Returns the feature's anchor point position. More...
 
QPainter::CompositionMode blendMode () const
 Returns the blending mode used for drawing callouts. More...
 
virtual QgsCalloutclone () const =0
 Duplicates a callout by creating a deep copy of the callout. More...
 
bool containsAdvancedEffects () const
 Returns true if the callout requires advanced effects such as blend modes, which require output in raster formats to be fully respected. More...
 
QgsPropertyCollectiondataDefinedProperties ()
 Returns a reference to the callout's property collection, used for data defined overrides. More...
 
const QgsPropertyCollectiondataDefinedProperties () const
 Returns a reference to the callout's property collection, used for data defined overrides. More...
 
virtual DrawOrder drawOrder () const
 Returns the desired drawing order (stacking) to use while rendering this callout. More...
 
bool enabled () const
 Returns true if the the callout is enabled. More...
 
LabelAnchorPoint labelAnchorPoint () const
 Returns the label's anchor point position. More...
 
virtual QVariantMap properties (const QgsReadWriteContext &context) const
 Returns the properties describing the callout encoded in a string format. More...
 
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 properties map. More...
 
virtual QSet< QString > referencedFields (const QgsRenderContext &context) const
 Returns the set of attributes referenced by the callout. More...
 
void render (QgsRenderContext &context, const QRectF &rect, const double angle, const QgsGeometry &anchor, QgsCalloutContext &calloutContext)
 Renders the callout onto the specified render context. More...
 
virtual void restoreProperties (const QDomElement &element, const QgsReadWriteContext &context)
 Restores the callout's properties from a DOM element. More...
 
virtual bool saveProperties (QDomDocument &doc, QDomElement &element, const QgsReadWriteContext &context) const
 Saves the current state of the callout to a DOM element. More...
 
void setAnchorPoint (AnchorPoint anchor)
 Sets the feature's anchor point position. More...
 
void setBlendMode (QPainter::CompositionMode mode)
 Sets the blending mode used for drawing callouts. More...
 
void setDataDefinedProperties (const QgsPropertyCollection &collection)
 Sets the callout's property collection, used for data defined overrides. More...
 
void setEnabled (bool enabled)
 Sets whether the callout is enabled. More...
 
void setLabelAnchorPoint (LabelAnchorPoint anchor)
 Sets the label's anchor point position. More...
 
virtual void startRender (QgsRenderContext &context)
 Prepares the callout for rendering on the specified render context. More...
 
virtual void stopRender (QgsRenderContext &context)
 Finalises the callout after a set of rendering operations on the specified render context. More...
 
virtual QString type () const =0
 Returns a unique string representing the callout type. More...
 

Static Public Member Functions

static QgsCalloutcreate (const QVariantMap &properties=QVariantMap(), const QgsReadWriteContext &context=QgsReadWriteContext())
 Creates a new QgsSimpleLineCallout, using the settings serialized in the properties map (corresponding to the output from QgsSimpleLineCallout::properties() ). More...
 
- Static Public Member Functions inherited from QgsCallout
static QgsCallout::AnchorPoint decodeAnchorPoint (const QString &name, bool *ok=nullptr)
 Attempts to decode a string representation of an anchor point name to the corresponding anchor point. More...
 
static QgsCallout::LabelAnchorPoint decodeLabelAnchorPoint (const QString &name, bool *ok=nullptr)
 Attempts to decode a string representation of a label anchor point name to the corresponding anchor point. More...
 
static QString encodeAnchorPoint (AnchorPoint anchor)
 Encodes an anchor point to its string representation. More...
 
static QString encodeLabelAnchorPoint (LabelAnchorPoint anchor)
 Encodes a label anchor point to its string representation. More...
 
static QgsPropertiesDefinition propertyDefinitions ()
 Returns the definitions for data defined properties available for use in callouts. More...
 

Protected Member Functions

virtual QgsCurvecreateCalloutLine (const QgsPoint &start, const QgsPoint &end, QgsRenderContext &context, const QRectF &bodyBoundingBox, const double angle, const QgsGeometry &anchor, QgsCallout::QgsCalloutContext &calloutContext) const
 Creates a callout line between start and end in the desired style. More...
 
void draw (QgsRenderContext &context, const 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. More...
 
- Protected Member Functions inherited from QgsCallout
QgsGeometry calloutLabelPoint (const QRectF &bodyBoundingBox, double angle, LabelAnchorPoint anchor, QgsRenderContext &context, const QgsCalloutContext &calloutContext, bool &pinned) const
 Returns the anchor point geometry for a label with the given bounding box and anchor point mode. More...
 
QgsGeometry calloutLineToPart (const QgsGeometry &labelGeometry, const QgsAbstractGeometry *partGeometry, QgsRenderContext &context, const QgsCalloutContext &calloutContext, bool &pinned) const
 Calculates the direct line from a label geometry to an anchor geometry part, respecting the various callout settings which influence how the callout end should be placed in the anchor geometry. More...
 
virtual void draw (QgsRenderContext &context, const QRectF &bodyBoundingBox, const double angle, const QgsGeometry &anchor, QgsCalloutContext &calloutContext)=0
 Performs the actual rendering of the callout implementation onto the specified render context. More...
 
Q_DECL_DEPRECATED QgsGeometry labelAnchorGeometry (const QRectF &bodyBoundingBox, const double angle, LabelAnchorPoint anchor) const
 Returns the anchor point geometry for a label with the given bounding box and anchor point mode. More...
 

Additional Inherited Members

- Public Types inherited from QgsCallout
enum  AnchorPoint { PoleOfInaccessibility = 0 , PointOnExterior , PointOnSurface , Centroid }
 Feature's anchor point position. More...
 
enum  DrawOrder { OrderBelowAllLabels , OrderBelowIndividualLabels }
 Options for draw order (stacking) of callouts. More...
 
enum  LabelAnchorPoint {
  LabelPointOnExterior , LabelCentroid , LabelTopLeft , LabelTopMiddle ,
  LabelTopRight , LabelMiddleLeft , LabelMiddleRight , LabelBottomLeft ,
  LabelBottomMiddle , LabelBottomRight
}
 Label's anchor point position. More...
 
enum class  Property : int {
  MinimumCalloutLength , OffsetFromAnchor , OffsetFromLabel , DrawCalloutToAllParts ,
  AnchorPointPosition , LabelAnchorPointPosition , OriginX , OriginY ,
  DestinationX , DestinationY , Curvature , Orientation ,
  Margins , WedgeWidth , CornerRadius , BlendMode
}
 Data definable properties. More...
 

Detailed Description

A simple direct line callout style.

Since
QGIS 3.10

Definition at line 512 of file qgscallout.h.

Constructor & Destructor Documentation

◆ QgsSimpleLineCallout() [1/2]

QgsSimpleLineCallout::QgsSimpleLineCallout ( )

Definition at line 530 of file qgscallout.cpp.

◆ ~QgsSimpleLineCallout()

QgsSimpleLineCallout::~QgsSimpleLineCallout ( )
overridedefault

◆ QgsSimpleLineCallout() [2/2]

QgsSimpleLineCallout::QgsSimpleLineCallout ( const QgsSimpleLineCallout other)

Copy constructor.

Definition at line 538 of file qgscallout.cpp.

Member Function Documentation

◆ clone()

QgsSimpleLineCallout * QgsSimpleLineCallout::clone ( ) const
overridevirtual

Duplicates a callout by creating a deep copy of the callout.

Caller takes ownership of the returned object.

Implements QgsCallout.

Reimplemented in QgsManhattanLineCallout, and QgsCurvedLineCallout.

Definition at line 567 of file qgscallout.cpp.

◆ create()

QgsCallout * QgsSimpleLineCallout::create ( const QVariantMap &  properties = QVariantMap(),
const QgsReadWriteContext context = QgsReadWriteContext() 
)
static

Creates a new QgsSimpleLineCallout, using the settings serialized in the properties map (corresponding to the output from QgsSimpleLineCallout::properties() ).

Definition at line 555 of file qgscallout.cpp.

◆ createCalloutLine()

QgsCurve * QgsSimpleLineCallout::createCalloutLine ( const QgsPoint start,
const QgsPoint end,
QgsRenderContext context,
const QRectF &  bodyBoundingBox,
const double  angle,
const QgsGeometry anchor,
QgsCallout::QgsCalloutContext calloutContext 
) const
protectedvirtual

Creates a callout line between start and end in the desired style.

The base class method returns a straight line.

Since
QGIS 3.20

Reimplemented in QgsManhattanLineCallout, and QgsCurvedLineCallout.

Definition at line 744 of file qgscallout.cpp.

◆ draw()

void QgsSimpleLineCallout::draw ( QgsRenderContext context,
const QRectF &  bodyBoundingBox,
const double  angle,
const QgsGeometry anchor,
QgsCallout::QgsCalloutContext calloutContext 
)
overrideprotectedvirtual

Performs the actual rendering of the callout implementation onto the specified render context.

The bodyBoundingBox argument gives the desired size and position of the body of the callout (e.g. the actual label geometry). The angle argument specifies the rotation of the callout body (in degrees clockwise from horizontal). It is assumed that angle rotation specified via angle is applied around the center of rect.

The anchor argument dictates the geometry which the callout should connect to. Depending on the callout subclass and anchor geometry type, the actual shape of the rendered callout may vary. E.g. a subclass may prefer to attach to the centroid of the anchor, while another subclass may prefer to attach to the closest point on anchor instead.

Both rect and anchor are specified in painter coordinates (i.e. pixels).

The calloutContext argument is used to specify additional contextual information about how a callout is being rendered.

Implements QgsCallout.

Definition at line 654 of file qgscallout.cpp.

◆ drawCalloutToAllParts()

bool QgsSimpleLineCallout::drawCalloutToAllParts ( ) const
inline

Returns true if callout lines should be drawn to all feature parts.

See also
setDrawCalloutToAllParts()

Definition at line 698 of file qgscallout.h.

◆ lineSymbol()

QgsLineSymbol * QgsSimpleLineCallout::lineSymbol ( )

Returns the line symbol used to render the callout line.

Ownership is not transferred.

See also
setLineSymbol()

Definition at line 644 of file qgscallout.cpp.

◆ minimumLength()

double QgsSimpleLineCallout::minimumLength ( ) const
inline

Returns the minimum length of callout lines.

Units are specified through minimumLengthUnits().

See also
setMinimumLength()
minimumLengthUnit()

Definition at line 565 of file qgscallout.h.

◆ minimumLengthMapUnitScale()

const QgsMapUnitScale & QgsSimpleLineCallout::minimumLengthMapUnitScale ( ) const
inline

Returns the map unit scale for the minimum callout length.

See also
setMinimumLengthMapUnitScale()
minimumLengthUnit()
minimumLength()

Definition at line 602 of file qgscallout.h.

◆ minimumLengthUnit()

Qgis::RenderUnit QgsSimpleLineCallout::minimumLengthUnit ( ) const
inline

Returns the units for the minimum length of callout lines.

See also
setMinimumLengthUnit()
minimumLength()

Definition at line 586 of file qgscallout.h.

◆ offsetFromAnchor()

double QgsSimpleLineCallout::offsetFromAnchor ( ) const
inline

Returns the offset distance from the anchor point at which to start the line.

Units are specified through offsetFromAnchorUnit().

See also
setOffsetFromAnchor()
offsetFromAnchorUnit()

Definition at line 610 of file qgscallout.h.

◆ offsetFromAnchorMapUnitScale()

const QgsMapUnitScale & QgsSimpleLineCallout::offsetFromAnchorMapUnitScale ( ) const
inline

Returns the map unit scale for the offset from anchor.

See also
setOffsetFromAnchorMapUnitScale()
offsetFromAnchorUnit()
offsetFromAnchor()

Definition at line 647 of file qgscallout.h.

◆ offsetFromAnchorUnit()

Qgis::RenderUnit QgsSimpleLineCallout::offsetFromAnchorUnit ( ) const
inline

Returns the units for the offset from anchor point.

See also
setOffsetFromAnchorUnit()
offsetFromAnchor()

Definition at line 631 of file qgscallout.h.

◆ offsetFromLabel()

double QgsSimpleLineCallout::offsetFromLabel ( ) const
inline

Returns the offset distance from label area at which to end the line.

Units are specified through offsetFromLabelUnit().

See also
setOffsetFromLabel()
offsetFromLabelUnit()

Definition at line 654 of file qgscallout.h.

◆ offsetFromLabelMapUnitScale()

const QgsMapUnitScale & QgsSimpleLineCallout::offsetFromLabelMapUnitScale ( ) const
inline

Returns the map unit scale for the minimum callout length.

See also
setOffsetFromLabelMapUnitScale()
offsetFromLabelUnit()
offsetFromLabel()

Definition at line 691 of file qgscallout.h.

◆ offsetFromLabelUnit()

Qgis::RenderUnit QgsSimpleLineCallout::offsetFromLabelUnit ( ) const
inline

Returns the units for the offset from label area.

See also
setOffsetFromLabelUnit()
offsetFromLabel()

Definition at line 675 of file qgscallout.h.

◆ operator=()

QgsSimpleLineCallout & QgsSimpleLineCallout::operator= ( const QgsSimpleLineCallout )
delete

◆ properties()

QVariantMap QgsSimpleLineCallout::properties ( const QgsReadWriteContext context) const
overridevirtual

Returns the properties describing the callout encoded in a string format.

Subclasses must ensure that they include the base class' properties() in their returned value.

See also
readProperties()
saveProperties()

Reimplemented from QgsCallout.

Reimplemented in QgsCurvedLineCallout.

Definition at line 572 of file qgscallout.cpp.

◆ readProperties()

void QgsSimpleLineCallout::readProperties ( const QVariantMap &  props,
const QgsReadWriteContext context 
)
overridevirtual

Reads a string map of an callout's properties and restores the callout to the state described by the properties map.

Subclasses must ensure that they call the base class' readProperties() method.

See also
properties()

Reimplemented from QgsCallout.

Definition at line 596 of file qgscallout.cpp.

◆ referencedFields()

QSet< QString > QgsSimpleLineCallout::referencedFields ( const QgsRenderContext context) const
overridevirtual

Returns the set of attributes referenced by the callout.

This includes attributes required by any data defined properties associated with the callout.

Warning
This must only be called after a corresponding call to startRender() with the same render context.

Reimplemented from QgsCallout.

Definition at line 636 of file qgscallout.cpp.

◆ setDrawCalloutToAllParts()

void QgsSimpleLineCallout::setDrawCalloutToAllParts ( bool  drawToAllParts)
inline

Sets whether callout lines should be drawn to all feature parts.

See also
drawCalloutToAllParts()

Definition at line 705 of file qgscallout.h.

◆ setLineSymbol()

void QgsSimpleLineCallout::setLineSymbol ( QgsLineSymbol symbol)

Sets the line symbol used to render the callout line.

Ownership of symbol is transferred to the callout.

See also
lineSymbol()

Definition at line 649 of file qgscallout.cpp.

◆ setMinimumLength()

void QgsSimpleLineCallout::setMinimumLength ( double  length)
inline

Sets the minimum length of callout lines.

Units are specified through setMinimumLengthUnit().

See also
minimumLength()
setMinimumLengthUnit()

Definition at line 572 of file qgscallout.h.

◆ setMinimumLengthMapUnitScale()

void QgsSimpleLineCallout::setMinimumLengthMapUnitScale ( const QgsMapUnitScale scale)
inline

Sets the map unit scale for the minimum callout length.

See also
minimumLengthMapUnitScale()
setMinimumLengthUnit()
setMinimumLength()

Definition at line 594 of file qgscallout.h.

◆ setMinimumLengthUnit()

void QgsSimpleLineCallout::setMinimumLengthUnit ( Qgis::RenderUnit  unit)
inline

Sets the unit for the minimum length of callout lines.

See also
minimumLengthUnit()
setMinimumLength()

Definition at line 579 of file qgscallout.h.

◆ setOffsetFromAnchor()

void QgsSimpleLineCallout::setOffsetFromAnchor ( double  distance)
inline

Sets the offset distance from the anchor point at which to start the line.

Units are specified through setOffsetFromAnchorUnit().

See also
offsetFromAnchor()
setOffsetFromAnchorUnit()

Definition at line 617 of file qgscallout.h.

◆ setOffsetFromAnchorMapUnitScale()

void QgsSimpleLineCallout::setOffsetFromAnchorMapUnitScale ( const QgsMapUnitScale scale)
inline

Sets the map unit scale for the offset from anchor.

See also
offsetFromAnchorMapUnitScale()
setOffsetFromAnchorUnit()
setOffsetFromAnchor()

Definition at line 639 of file qgscallout.h.

◆ setOffsetFromAnchorUnit()

void QgsSimpleLineCallout::setOffsetFromAnchorUnit ( Qgis::RenderUnit  unit)
inline

Sets the unit for the offset from anchor distance.

See also
offsetFromAnchor()
setOffsetFromAnchor()

Definition at line 624 of file qgscallout.h.

◆ setOffsetFromLabel()

void QgsSimpleLineCallout::setOffsetFromLabel ( double  distance)
inline

Sets the offset distance from label area at which to end the line.

Units are specified through setOffsetFromLabelUnit().

See also
offsetFromLabel()
setOffsetFromLabelUnit()

Definition at line 661 of file qgscallout.h.

◆ setOffsetFromLabelMapUnitScale()

void QgsSimpleLineCallout::setOffsetFromLabelMapUnitScale ( const QgsMapUnitScale scale)
inline

Sets the map unit scale for the offset from label area.

See also
offsetFromLabelMapUnitScale()
setOffsetFromLabelUnit()
setOffsetFromLabel()

Definition at line 683 of file qgscallout.h.

◆ setOffsetFromLabelUnit()

void QgsSimpleLineCallout::setOffsetFromLabelUnit ( Qgis::RenderUnit  unit)
inline

Sets the unit for the offset from label area distance.

See also
offsetFromLabel()
setOffsetFromLabel()

Definition at line 668 of file qgscallout.h.

◆ startRender()

void QgsSimpleLineCallout::startRender ( QgsRenderContext context)
overridevirtual

Prepares the callout for rendering on the specified render context.

Warning
This MUST be called prior to calling render() on the callout, and must always be accompanied by a corresponding call to stopRender().
See also
stopRender()

Reimplemented from QgsCallout.

Definition at line 622 of file qgscallout.cpp.

◆ stopRender()

void QgsSimpleLineCallout::stopRender ( QgsRenderContext context)
overridevirtual

Finalises the callout after a set of rendering operations on the specified render context.

Warning
This MUST be called after to after render() operations on the callout, and must always be accompanied by a corresponding prior call to startRender().
See also
startRender()

Reimplemented from QgsCallout.

Definition at line 629 of file qgscallout.cpp.

◆ type()

QString QgsSimpleLineCallout::type ( ) const
overridevirtual

Returns a unique string representing the callout type.

Implements QgsCallout.

Reimplemented in QgsManhattanLineCallout, and QgsCurvedLineCallout.

Definition at line 562 of file qgscallout.cpp.


The documentation for this class was generated from the following files: