QGIS API Documentation  3.21.0-Master (5b68dc587e)
Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
QgsBalloonCallout Class Reference

A cartoon talking bubble callout style. More...

#include <qgscallout.h>

Inheritance diagram for QgsBalloonCallout:
Inheritance graph
[legend]

Public Member Functions

 QgsBalloonCallout ()
 
 QgsBalloonCallout (const QgsBalloonCallout &other)
 Copy constructor. More...
 
 ~QgsBalloonCallout () override
 
QgsBalloonCalloutclone () const override
 Duplicates a callout by creating a deep copy of the callout. More...
 
double cornerRadius () const
 Returns the corner radius of the balloon shapes. More...
 
const QgsMapUnitScalecornerRadiusMapUnitScale () const
 Returns the map unit scale for the corner radius. More...
 
QgsUnitTypes::RenderUnit cornerRadiusUnit () const
 Returns the units for the corner radius. More...
 
QgsFillSymbolfillSymbol ()
 Returns the fill symbol used to render the callout. More...
 
const QgsMarginsmargins () const
 Returns the margins between the outside of the callout frame and the label's bounding rectangle. More...
 
QgsUnitTypes::RenderUnit marginsUnit () const
 Returns the units for the margins between the outside of the callout frame and the label's bounding rectangle. 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...
 
QgsUnitTypes::RenderUnit offsetFromAnchorUnit () const
 Returns the units for the offset from anchor point. More...
 
QgsBalloonCalloutoperator= (const QgsBalloonCallout &)=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 setCornerRadius (double radius)
 Sets the radius of the corners for the balloon shapes. More...
 
void setCornerRadiusMapUnitScale (const QgsMapUnitScale &scale)
 Sets the map unit scale for the corner radius. More...
 
void setCornerRadiusUnit (QgsUnitTypes::RenderUnit unit)
 Sets the unit for the corner radius. More...
 
void setFillSymbol (QgsFillSymbol *symbol)
 Sets the fill symbol used to render the callout. More...
 
void setMargins (const QgsMargins &margins)
 Sets the margins between the outside of the callout frame and the label's bounding rectangle. More...
 
void setMarginsUnit (QgsUnitTypes::RenderUnit unit)
 Sets the unit for the margins between the outside of the callout frame and the label's bounding rectangle. 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 (QgsUnitTypes::RenderUnit unit)
 Sets the unit for the offset from anchor distance. More...
 
void setWedgeWidth (double width)
 Sets the width of the wedge shape at the side it connects with the label. More...
 
void setWedgeWidthMapUnitScale (const QgsMapUnitScale &scale)
 Sets the map unit scale for the wedge width. More...
 
void setWedgeWidthUnit (QgsUnitTypes::RenderUnit unit)
 Sets the unit for the wedge width. 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...
 
double wedgeWidth () const
 Returns the width of the wedge shape at the side it connects with the label. More...
 
const QgsMapUnitScalewedgeWidthMapUnitScale () const
 Returns the map unit scale for the wedge width. More...
 
QgsUnitTypes::RenderUnit wedgeWidthUnit () const
 Returns the units for the wedge width. 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...
 
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...
 
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...
 

Static Public Member Functions

static QgsCalloutcreate (const QVariantMap &properties=QVariantMap(), const QgsReadWriteContext &context=QgsReadWriteContext())
 Creates a new QgsBalloonCallout, using the settings serialized in the properties map (corresponding to the output from QgsBalloonCallout::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

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...
 
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  Property {
  MinimumCalloutLength , OffsetFromAnchor , OffsetFromLabel , DrawCalloutToAllParts ,
  AnchorPointPosition , LabelAnchorPointPosition , OriginX , OriginY ,
  DestinationX , DestinationY , Curvature , Orientation ,
  Margins , WedgeWidth , CornerRadius , BlendMode
}
 Data definable properties. More...
 

Detailed Description

A cartoon talking bubble callout style.

Since
QGIS 3.20

Definition at line 890 of file qgscallout.h.

Constructor & Destructor Documentation

◆ QgsBalloonCallout() [1/2]

QgsBalloonCallout::QgsBalloonCallout ( )

Definition at line 1034 of file qgscallout.cpp.

◆ ~QgsBalloonCallout()

QgsBalloonCallout::~QgsBalloonCallout ( )
overridedefault

◆ QgsBalloonCallout() [2/2]

QgsBalloonCallout::QgsBalloonCallout ( const QgsBalloonCallout other)

Copy constructor.

Definition at line 1041 of file qgscallout.cpp.

Member Function Documentation

◆ clone()

QgsBalloonCallout * QgsBalloonCallout::clone ( ) const
overridevirtual

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

Caller takes ownership of the returned object.

Implements QgsCallout.

Definition at line 1071 of file qgscallout.cpp.

◆ cornerRadius()

double QgsBalloonCallout::cornerRadius ( ) const
inline

Returns the corner radius of the balloon shapes.

Units are specified through wedgeWidthUnit().

See also
setCornerRadius()
cornerRadiusUnit()

Definition at line 1084 of file qgscallout.h.

◆ cornerRadiusMapUnitScale()

const QgsMapUnitScale& QgsBalloonCallout::cornerRadiusMapUnitScale ( ) const
inline

Returns the map unit scale for the corner radius.

See also
setCornerRadiusMapUnitScale()
cornerRadiusUnit()
cornerRadius()

Definition at line 1128 of file qgscallout.h.

◆ cornerRadiusUnit()

QgsUnitTypes::RenderUnit QgsBalloonCallout::cornerRadiusUnit ( ) const
inline

Returns the units for the corner radius.

See also
setCornerRadiusUnit()
cornerRadius()

Definition at line 1110 of file qgscallout.h.

◆ create()

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

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

Definition at line 1059 of file qgscallout.cpp.

◆ draw()

void QgsBalloonCallout::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 1163 of file qgscallout.cpp.

◆ fillSymbol()

QgsFillSymbol * QgsBalloonCallout::fillSymbol ( )

Returns the fill symbol used to render the callout.

Ownership is not transferred.

See also
setFillSymbol()

Definition at line 1153 of file qgscallout.cpp.

◆ margins()

const QgsMargins& QgsBalloonCallout::margins ( ) const
inline

Returns the margins between the outside of the callout frame and the label's bounding rectangle.

Units are retrieved via marginsUnit()

Note
Negative margins are acceptable.
See also
setMargins()
marginsUnit()

Definition at line 992 of file qgscallout.h.

◆ marginsUnit()

QgsUnitTypes::RenderUnit QgsBalloonCallout::marginsUnit ( ) const
inline

Returns the units for the margins between the outside of the callout frame and the label's bounding rectangle.

See also
setMarginsUnit()
margins()

Definition at line 1020 of file qgscallout.h.

◆ offsetFromAnchor()

double QgsBalloonCallout::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 943 of file qgscallout.h.

◆ offsetFromAnchorMapUnitScale()

const QgsMapUnitScale& QgsBalloonCallout::offsetFromAnchorMapUnitScale ( ) const
inline

Returns the map unit scale for the offset from anchor.

See also
setOffsetFromAnchorMapUnitScale()
offsetFromAnchorUnit()
offsetFromAnchor()

Definition at line 980 of file qgscallout.h.

◆ offsetFromAnchorUnit()

QgsUnitTypes::RenderUnit QgsBalloonCallout::offsetFromAnchorUnit ( ) const
inline

Returns the units for the offset from anchor point.

See also
setOffsetFromAnchorUnit()
offsetFromAnchor()

Definition at line 964 of file qgscallout.h.

◆ operator=()

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

◆ properties()

QVariantMap QgsBalloonCallout::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.

Definition at line 1076 of file qgscallout.cpp.

◆ readProperties()

void QgsBalloonCallout::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 1103 of file qgscallout.cpp.

◆ referencedFields()

QSet< QString > QgsBalloonCallout::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 1145 of file qgscallout.cpp.

◆ setCornerRadius()

void QgsBalloonCallout::setCornerRadius ( double  radius)
inline

Sets the radius of the corners for the balloon shapes.

Units are specified through setCornerRadiusUnit().

See also
cornerRadius()
setCornerRadiusUnit()

Definition at line 1094 of file qgscallout.h.

◆ setCornerRadiusMapUnitScale()

void QgsBalloonCallout::setCornerRadiusMapUnitScale ( const QgsMapUnitScale scale)
inline

Sets the map unit scale for the corner radius.

See also
cornerRadiusMapUnitScale()
setCornerRadiusUnit()
setCornerRadius()

Definition at line 1119 of file qgscallout.h.

◆ setCornerRadiusUnit()

void QgsBalloonCallout::setCornerRadiusUnit ( QgsUnitTypes::RenderUnit  unit)
inline

Sets the unit for the corner radius.

See also
cornerRadiusUnit()
setCornerRadius()

Definition at line 1102 of file qgscallout.h.

◆ setFillSymbol()

void QgsBalloonCallout::setFillSymbol ( QgsFillSymbol symbol)

Sets the fill symbol used to render the callout.

Ownership of symbol is transferred to the callout.

See also
fillSymbol()

Definition at line 1158 of file qgscallout.cpp.

◆ setMargins()

void QgsBalloonCallout::setMargins ( const QgsMargins margins)
inline

Sets the margins between the outside of the callout frame and the label's bounding rectangle.

Units are set via setMarginsUnit()

Note
Negative margins are acceptable.
See also
margins()
setMarginsUnit()

Definition at line 1004 of file qgscallout.h.

◆ setMarginsUnit()

void QgsBalloonCallout::setMarginsUnit ( QgsUnitTypes::RenderUnit  unit)
inline

Sets the unit for the margins between the outside of the callout frame and the label's bounding rectangle.

See also
margins()
marginsUnit()

Definition at line 1012 of file qgscallout.h.

◆ setOffsetFromAnchor()

void QgsBalloonCallout::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 950 of file qgscallout.h.

◆ setOffsetFromAnchorMapUnitScale()

void QgsBalloonCallout::setOffsetFromAnchorMapUnitScale ( const QgsMapUnitScale scale)
inline

Sets the map unit scale for the offset from anchor.

See also
offsetFromAnchorMapUnitScale()
setOffsetFromAnchorUnit()
setOffsetFromAnchor()

Definition at line 972 of file qgscallout.h.

◆ setOffsetFromAnchorUnit()

void QgsBalloonCallout::setOffsetFromAnchorUnit ( QgsUnitTypes::RenderUnit  unit)
inline

Sets the unit for the offset from anchor distance.

See also
offsetFromAnchor()
setOffsetFromAnchor()

Definition at line 957 of file qgscallout.h.

◆ setWedgeWidth()

void QgsBalloonCallout::setWedgeWidth ( double  width)
inline

Sets the width of the wedge shape at the side it connects with the label.

Units are specified through setWedgeWidthUnit().

See also
wedgeWidth()
setWedgeWidthUnit()

Definition at line 1040 of file qgscallout.h.

◆ setWedgeWidthMapUnitScale()

void QgsBalloonCallout::setWedgeWidthMapUnitScale ( const QgsMapUnitScale scale)
inline

Sets the map unit scale for the wedge width.

See also
wedgeWidthMapUnitScale()
setWedgeWidthUnit()
setWedgeWidth()

Definition at line 1065 of file qgscallout.h.

◆ setWedgeWidthUnit()

void QgsBalloonCallout::setWedgeWidthUnit ( QgsUnitTypes::RenderUnit  unit)
inline

Sets the unit for the wedge width.

See also
wedgeWidthUnit()
setWedgeWidth()

Definition at line 1048 of file qgscallout.h.

◆ startRender()

void QgsBalloonCallout::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 1131 of file qgscallout.cpp.

◆ stopRender()

void QgsBalloonCallout::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 1138 of file qgscallout.cpp.

◆ type()

QString QgsBalloonCallout::type ( ) const
overridevirtual

Returns a unique string representing the callout type.

Implements QgsCallout.

Definition at line 1066 of file qgscallout.cpp.

◆ wedgeWidth()

double QgsBalloonCallout::wedgeWidth ( ) const
inline

Returns the width of the wedge shape at the side it connects with the label.

Units are specified through wedgeWidthUnit().

See also
setWedgeWidth()
wedgeWidthUnit()

Definition at line 1030 of file qgscallout.h.

◆ wedgeWidthMapUnitScale()

const QgsMapUnitScale& QgsBalloonCallout::wedgeWidthMapUnitScale ( ) const
inline

Returns the map unit scale for the wedge width.

See also
setWedgeWidthMapUnitScale()
wedgeWidthUnit()
wedgeWidth()

Definition at line 1074 of file qgscallout.h.

◆ wedgeWidthUnit()

QgsUnitTypes::RenderUnit QgsBalloonCallout::wedgeWidthUnit ( ) const
inline

Returns the units for the wedge width.

See also
setWedgeWidthUnit()
wedgeWidth()

Definition at line 1056 of file qgscallout.h.


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