QGIS API Documentation  2.14.0-Essen
Classes | Public Member Functions | Protected Attributes | List of all members
QgsLabelFeature Class Reference

The QgsLabelFeature class describes a feature that should be used within the labeling engine. More...

#include <qgslabelfeature.h>

Inheritance diagram for QgsLabelFeature:
Inheritance graph
[legend]

Classes

struct  VisualMargin
 Stores visual margins for labels (left, right, top and bottom) More...
 

Public Member Functions

 QgsLabelFeature (QgsFeatureId id, GEOSGeometry *geometry, QSizeF size)
 Create label feature, takes ownership of the geometry instance. More...
 
virtual ~QgsLabelFeature ()
 Clean up geometry and curved label info (if present) More...
 
bool alwaysShow () const
 Whether label should be always shown (sets very high label priority) More...
 
pal::LabelInfocurvedLabelInfo () const
 Get additional infor required for curved label placement. Returns null if not set. More...
 
double distLabel () const
 Applies to "around point" placement strategy or linestring features. More...
 
double fixedAngle () const
 Angle in degrees of the fixed angle (relevant only if hasFixedAngle() returns true) More...
 
QgsPoint fixedPosition () const
 Coordinates of the fixed position (relevant only if hasFixedPosition() returns true) More...
 
GEOSGeometry * geometry () const
 Get access to the associated geometry. More...
 
bool hasFixedAngle () const
 Whether the label should use a fixed angle instead of using angle from automatic placement. More...
 
bool hasFixedPosition () const
 Whether the label should use a fixed position instead of being automatically placed. More...
 
bool hasFixedQuadrant () const
 Returns whether the quadrant for the label is fixed. More...
 
QgsFeatureId id () const
 Identifier of the label (unique within the parent label provider) More...
 
bool isObstacle () const
 Returns whether the feature will act as an obstacle for labels. More...
 
QString labelText () const
 Text of the label. More...
 
pal::Layerlayer () const
 Get PAL layer of the label feature. Should be only used internally in PAL. More...
 
double obstacleFactor () const
 Returns the obstacle factor for the feature. More...
 
GEOSGeometry * obstacleGeometry () const
 Returns the label's obstacle geometry, if different to the feature geometry. More...
 
QgsPalLayerSettings::OffsetType offsetType () const
 Returns the offset type, which determines how offsets and distance to label behaves. More...
 
QgsPoint positionOffset () const
 Applies only to "offset from point" placement strategy. More...
 
QVector< QgsPalLayerSettings::PredefinedPointPositionpredefinedPositionOrder () const
 Returns the priority ordered list of predefined positions for label candidates. More...
 
double priority () const
 Returns the feature's labeling priority. More...
 
QgsAbstractLabelProviderprovider () const
 Return provider of this instance. More...
 
QPointF quadOffset () const
 Applies to "offset from point" placement strategy and "around point" (in case hasFixedQuadrant() returns true). More...
 
double repeatDistance () const
 Applies only to linestring features - after what distance (in map units) the labels should be repeated (0 = no repetitions) More...
 
void setAlwaysShow (bool enabled)
 Set whether label should be always shown (sets very high label priority) More...
 
void setCurvedLabelInfo (pal::LabelInfo *info)
 takes ownership of the instance More...
 
void setDistLabel (double dist)
 Applies to "around point" placement strategy or linestring features. More...
 
void setFixedAngle (double angle)
 Set angle in degrees of the fixed angle (relevant only if hasFixedAngle() returns true) More...
 
void setFixedPosition (const QgsPoint &point)
 Set coordinates of the fixed position (relevant only if hasFixedPosition() returns true) More...
 
void setHasFixedAngle (bool enabled)
 Set whether the label should use a fixed angle instead of using angle from automatic placement. More...
 
void setHasFixedPosition (bool enabled)
 Set whether the label should use a fixed position instead of being automatically placed. More...
 
void setHasFixedQuadrant (bool enabled)
 Sets whether the quadrant for the label must be respected. More...
 
void setIsObstacle (bool enabled)
 Sets whether the feature will act as an obstacle for labels. More...
 
void setLabelText (const QString &text)
 Set text of the label. More...
 
void setLayer (pal::Layer *layer)
 Assign PAL layer to the label feature. Should be only used internally in PAL. More...
 
void setObstacleFactor (double factor)
 Sets the obstacle factor for the feature. More...
 
void setObstacleGeometry (GEOSGeometry *obstacleGeom)
 Sets the label's obstacle geometry, if different to the feature geometry. More...
 
void setOffsetType (QgsPalLayerSettings::OffsetType type)
 Sets the offset type, which determines how offsets and distance to label behaves. More...
 
void setPositionOffset (const QgsPoint &offset)
 Applies only to "offset from point" placement strategy. More...
 
void setPredefinedPositionOrder (const QVector< QgsPalLayerSettings::PredefinedPointPosition > &order)
 Sets the priority ordered list of predefined positions for label candidates. More...
 
void setPriority (double priority)
 Sets the priority for labeling the feature. More...
 
void setQuadOffset (QPointF quadOffset)
 Set which side of the point to use. More...
 
void setRepeatDistance (double dist)
 Applies only to linestring features - set after what distance (in map units) the labels should be repeated (0 = no repetitions) More...
 
void setSymbolSize (QSizeF size)
 Sets the size of the rendered symbol associated with this feature. More...
 
void setVisualMargin (const VisualMargin &margin)
 Sets the visual margin for the label feature. More...
 
void setZIndex (double zIndex)
 Sets the label's z-index. More...
 
QSizeF size () const
 Size of the label (in map units) More...
 
const QSizeFsymbolSize () const
 Returns the size of the rendered symbol associated with this feature, if applicable. More...
 
const VisualMarginvisualMargin () const
 Returns the visual margin for the label feature. More...
 
double zIndex () const
 Returns the label's z-index. More...
 

Protected Attributes

bool mAlwaysShow
 whether to always show label - even in case of collisions More...
 
double mDistLabel
 distance of label from the feature (only for "around point" placement or linestrings) More...
 
double mFixedAngle
 fixed rotation for the label (instead of automatic choice) More...
 
QgsPoint mFixedPosition
 fixed position for the label (instead of automatic placement) More...
 
GEOSGeometry * mGeometry
 Geometry of the feature to be labelled. More...
 
bool mHasFixedAngle
 whether mFixedAngle should be respected More...
 
bool mHasFixedPosition
 whether mFixedPosition should be respected More...
 
bool mHasFixedQuadrant
 whether mQuadOffset should be respected (only for "around point" placement) More...
 
QgsFeatureId mId
 Associated ID unique within the parent label provider. More...
 
pal::LabelInfomInfo
 extra information for curved labels (may be null) More...
 
bool mIsObstacle
 whether the feature geometry acts as an obstacle for labels More...
 
QString mLabelText
 text of the label More...
 
pal::LayermLayer
 Pointer to PAL layer (assigned when registered to PAL) More...
 
double mObstacleFactor
 how strong is the geometry acting as obstacle More...
 
GEOSGeometry * mObstacleGeometry
 Optional geometry to use for label obstacles, if different to mGeometry. More...
 
QgsPalLayerSettings::OffsetType mOffsetType
 Offset type for certain placement modes. More...
 
QgsPoint mPositionOffset
 offset of label from the feature (only for "offset from point" placement) More...
 
QVector< QgsPalLayerSettings::PredefinedPointPositionmPredefinedPositionOrder
 Ordered list of predefined positions for label (only for OrderedPositionsAroundPoint placement) More...
 
double mPriority
 Priority of the label. More...
 
QPointF mQuadOffset
 whether the side of the label is fixed (only for "around point" placement) More...
 
double mRepeatDistance
 distance after which label should be repeated (only for linestrings) More...
 
QSizeF mSize
 Width and height of the label. More...
 
QSizeF mSymbolSize
 Size of associated rendered symbol, if applicable. More...
 
VisualMargin mVisualMargin
 Visual margin of label contents. More...
 
double mZIndex
 Z-index of label (higher z-index labels are rendered on top of lower z-index labels) More...
 

Detailed Description

The QgsLabelFeature class describes a feature that should be used within the labeling engine.

Those may be the usual textual labels, diagrams, or any other custom type of map annotations (generated by custom label providers).

Instances only contain data relevant to the labeling engine (geometry, label size etc.) necessary for the layout. Rendering of labels is done by label providers.

Individual label providers may create subclasses of QgsLabelFeature in order to add more data to the instances that will be later used for drawing of labels.

Note
this class is not a part of public API yet. See notes in QgsLabelingEngineV2
added in QGIS 2.12
not available in Python bindings

Definition at line 34 of file qgslabelfeature.h.

Constructor & Destructor Documentation

QgsLabelFeature::QgsLabelFeature ( QgsFeatureId  id,
GEOSGeometry *  geometry,
QSizeF  size 
)

Create label feature, takes ownership of the geometry instance.

Definition at line 20 of file qgslabelfeature.cpp.

QgsLabelFeature::~QgsLabelFeature ( )
virtual

Clean up geometry and curved label info (if present)

Definition at line 42 of file qgslabelfeature.cpp.

Member Function Documentation

bool QgsLabelFeature::alwaysShow ( ) const
inline

Whether label should be always shown (sets very high label priority)

Definition at line 259 of file qgslabelfeature.h.

pal::LabelInfo* QgsLabelFeature::curvedLabelInfo ( ) const
inline

Get additional infor required for curved label placement. Returns null if not set.

Definition at line 297 of file qgslabelfeature.h.

double QgsLabelFeature::distLabel ( ) const
inline

Applies to "around point" placement strategy or linestring features.

Distance of the label from the feature (in map units)

Definition at line 234 of file qgslabelfeature.h.

double QgsLabelFeature::fixedAngle ( ) const
inline

Angle in degrees of the fixed angle (relevant only if hasFixedAngle() returns true)

Definition at line 187 of file qgslabelfeature.h.

QgsPoint QgsLabelFeature::fixedPosition ( ) const
inline

Coordinates of the fixed position (relevant only if hasFixedPosition() returns true)

Definition at line 178 of file qgslabelfeature.h.

GEOSGeometry* QgsLabelFeature::geometry ( ) const
inline

Get access to the associated geometry.

Definition at line 92 of file qgslabelfeature.h.

bool QgsLabelFeature::hasFixedAngle ( ) const
inline

Whether the label should use a fixed angle instead of using angle from automatic placement.

Definition at line 183 of file qgslabelfeature.h.

bool QgsLabelFeature::hasFixedPosition ( ) const
inline

Whether the label should use a fixed position instead of being automatically placed.

Definition at line 174 of file qgslabelfeature.h.

bool QgsLabelFeature::hasFixedQuadrant ( ) const
inline

Returns whether the quadrant for the label is fixed.

Applies to "around point" placement strategy.

See also
setFixedQuadrant
quadOffset

Definition at line 196 of file qgslabelfeature.h.

QgsFeatureId QgsLabelFeature::id ( ) const
inline

Identifier of the label (unique within the parent label provider)

Definition at line 89 of file qgslabelfeature.h.

bool QgsLabelFeature::isObstacle ( ) const
inline

Returns whether the feature will act as an obstacle for labels.

Returns
true if feature is an obstacle
See also
setIsObstacle

Definition at line 267 of file qgslabelfeature.h.

QString QgsLabelFeature::labelText ( ) const
inline

Text of the label.

Used also if "merge connected lines to avoid duplicate labels" is enabled to identify which features may be merged.

Definition at line 292 of file qgslabelfeature.h.

pal::Layer* QgsLabelFeature::layer ( ) const
inline

Get PAL layer of the label feature. Should be only used internally in PAL.

Definition at line 302 of file qgslabelfeature.h.

double QgsLabelFeature::obstacleFactor ( ) const
inline

Returns the obstacle factor for the feature.

The factor controls the penalty for labels overlapping this feature.

See also
setObstacleFactor

Definition at line 277 of file qgslabelfeature.h.

GEOSGeometry* QgsLabelFeature::obstacleGeometry ( ) const
inline

Returns the label's obstacle geometry, if different to the feature geometry.

Note
added in QGIS 2.14
See also
setObstacleGeometry()

Definition at line 108 of file qgslabelfeature.h.

QgsPalLayerSettings::OffsetType QgsLabelFeature::offsetType ( void  ) const
inline

Returns the offset type, which determines how offsets and distance to label behaves.

Support depends on which placement mode is used for generating label candidates.

See also
setOffsetType()

Definition at line 223 of file qgslabelfeature.h.

QgsPoint QgsLabelFeature::positionOffset ( ) const
inline

Applies only to "offset from point" placement strategy.

What offset (in map units) to use from the point

Definition at line 213 of file qgslabelfeature.h.

QVector< QgsPalLayerSettings::PredefinedPointPosition > QgsLabelFeature::predefinedPositionOrder ( ) const
inline

Returns the priority ordered list of predefined positions for label candidates.

This property is only used for OrderedPositionsAroundPoint placements.

See also
setPredefinedPositionOrder()

Definition at line 243 of file qgslabelfeature.h.

double QgsLabelFeature::priority ( ) const
inline

Returns the feature's labeling priority.

Returns
feature's priority, as a value between 0 (highest priority) and 1 (lowest priority). Returns -1.0 if feature will use the layer's default priority.
See also
setPriority

Definition at line 149 of file qgslabelfeature.h.

QgsAbstractLabelProvider * QgsLabelFeature::provider ( ) const

Return provider of this instance.

Definition at line 378 of file qgslabelingenginev2.cpp.

QPointF QgsLabelFeature::quadOffset ( ) const
inline

Applies to "offset from point" placement strategy and "around point" (in case hasFixedQuadrant() returns true).

Determines which side of the point to use. For X coordinate, values -1, 0, 1 mean left, center, right. For Y coordinate, values -1, 0, 1 mean above, center, below.

Definition at line 207 of file qgslabelfeature.h.

double QgsLabelFeature::repeatDistance ( ) const
inline

Applies only to linestring features - after what distance (in map units) the labels should be repeated (0 = no repetitions)

Definition at line 253 of file qgslabelfeature.h.

void QgsLabelFeature::setAlwaysShow ( bool  enabled)
inline

Set whether label should be always shown (sets very high label priority)

Definition at line 261 of file qgslabelfeature.h.

void QgsLabelFeature::setCurvedLabelInfo ( pal::LabelInfo info)
inline

takes ownership of the instance

Definition at line 299 of file qgslabelfeature.h.

void QgsLabelFeature::setDistLabel ( double  dist)
inline

Applies to "around point" placement strategy or linestring features.

Set distance of the label from the feature (in map units)

Definition at line 237 of file qgslabelfeature.h.

void QgsLabelFeature::setFixedAngle ( double  angle)
inline

Set angle in degrees of the fixed angle (relevant only if hasFixedAngle() returns true)

Definition at line 189 of file qgslabelfeature.h.

void QgsLabelFeature::setFixedPosition ( const QgsPoint point)
inline

Set coordinates of the fixed position (relevant only if hasFixedPosition() returns true)

Definition at line 180 of file qgslabelfeature.h.

void QgsLabelFeature::setHasFixedAngle ( bool  enabled)
inline

Set whether the label should use a fixed angle instead of using angle from automatic placement.

Definition at line 185 of file qgslabelfeature.h.

void QgsLabelFeature::setHasFixedPosition ( bool  enabled)
inline

Set whether the label should use a fixed position instead of being automatically placed.

Definition at line 176 of file qgslabelfeature.h.

void QgsLabelFeature::setHasFixedQuadrant ( bool  enabled)
inline

Sets whether the quadrant for the label must be respected.

This can be used to fix the quadrant for specific features when using an "around point" placement.

See also
fixedQuadrant
quadOffset

Definition at line 202 of file qgslabelfeature.h.

void QgsLabelFeature::setIsObstacle ( bool  enabled)
inline

Sets whether the feature will act as an obstacle for labels.

Parameters
enabledwhether feature will act as an obstacle
See also
isObstacle

Definition at line 272 of file qgslabelfeature.h.

void QgsLabelFeature::setLabelText ( const QString text)
inline

Set text of the label.

Definition at line 294 of file qgslabelfeature.h.

void QgsLabelFeature::setLayer ( pal::Layer layer)
inline

Assign PAL layer to the label feature. Should be only used internally in PAL.

Definition at line 304 of file qgslabelfeature.h.

void QgsLabelFeature::setObstacleFactor ( double  factor)
inline

Sets the obstacle factor for the feature.

The factor controls the penalty for labels overlapping this feature.

Parameters
factorlarger factors ( > 1.0 ) will result in labels which are less likely to cover this feature, smaller factors ( < 1.0 ) mean labels are more likely to cover this feature (where required)
See also
obstacleFactor

Definition at line 285 of file qgslabelfeature.h.

void QgsLabelFeature::setObstacleGeometry ( GEOSGeometry *  obstacleGeom)

Sets the label's obstacle geometry, if different to the feature geometry.

This can be used to override the shape of the feature for obstacle detection, eg to buffer around a point geometry to prevent labels being placed too close to the point itself. It not set, the feature's geometry is used for obstacle detection. Ownership of obstacle geometry is transferred.

Note
added in QGIS 2.14
See also
obstacleGeometry()

Definition at line 53 of file qgslabelfeature.cpp.

void QgsLabelFeature::setOffsetType ( QgsPalLayerSettings::OffsetType  type)
inline

Sets the offset type, which determines how offsets and distance to label behaves.

Support depends on which placement mode is used for generating label candidates.

See also
offsetType()

Definition at line 230 of file qgslabelfeature.h.

void QgsLabelFeature::setPositionOffset ( const QgsPoint offset)
inline

Applies only to "offset from point" placement strategy.

Set what offset (in map units) to use from the point

Definition at line 216 of file qgslabelfeature.h.

void QgsLabelFeature::setPredefinedPositionOrder ( const QVector< QgsPalLayerSettings::PredefinedPointPosition > &  order)
inline

Sets the priority ordered list of predefined positions for label candidates.

This property is only used for OrderedPositionsAroundPoint placements.

See also
predefinedPositionOrder()

Definition at line 249 of file qgslabelfeature.h.

void QgsLabelFeature::setPriority ( double  priority)
inline

Sets the priority for labeling the feature.

Parameters
priorityfeature's priority, as a value between 0 (highest priority) and 1 (lowest priority). Set to -1.0 to use the layer's default priority for this feature.
See also
priority

Definition at line 156 of file qgslabelfeature.h.

void QgsLabelFeature::setQuadOffset ( QPointF  quadOffset)
inline

Set which side of the point to use.

See also
quadOffset

Definition at line 210 of file qgslabelfeature.h.

void QgsLabelFeature::setRepeatDistance ( double  dist)
inline

Applies only to linestring features - set after what distance (in map units) the labels should be repeated (0 = no repetitions)

Definition at line 256 of file qgslabelfeature.h.

void QgsLabelFeature::setSymbolSize ( QSizeF  size)
inline

Sets the size of the rendered symbol associated with this feature.

This size is taken into account in certain label placement modes to avoid placing labels over the rendered symbol for this feature.

See also
symbolSize()

Definition at line 134 of file qgslabelfeature.h.

void QgsLabelFeature::setVisualMargin ( const VisualMargin margin)
inline

Sets the visual margin for the label feature.

The visual margin represents a margin within the label which should not be considered when calculating the positions of candidates for the label feature. It is used in certain label placement modes to adjust the position of candidates so that they all appear to be at visually equal distances from a point feature. For instance, this can be used to place labels which sit above a point so that their baseline rather then the descender of the label is at a preset distance from the point.

Parameters
marginvisual margins for label
See also
visualMargin()

Definition at line 122 of file qgslabelfeature.h.

void QgsLabelFeature::setZIndex ( double  zIndex)
inline

Sets the label's z-index.

Higher z-index labels are rendered on top of lower z-index labels.

Parameters
zIndexz-index for label
See also
zIndex()
Note
added in QGIS 2.14

Definition at line 171 of file qgslabelfeature.h.

QSizeF QgsLabelFeature::size ( void  ) const
inline

Size of the label (in map units)

Definition at line 111 of file qgslabelfeature.h.

const QSizeF& QgsLabelFeature::symbolSize ( ) const
inline

Returns the size of the rendered symbol associated with this feature, if applicable.

This size is taken into account in certain label placement modes to avoid placing labels over the rendered symbol for this feature. The size will only be set for labels associated with a point feature.

See also
symbolSize()

Definition at line 142 of file qgslabelfeature.h.

const VisualMargin& QgsLabelFeature::visualMargin ( ) const
inline

Returns the visual margin for the label feature.

See also
setVisualMargin() for details

Definition at line 127 of file qgslabelfeature.h.

double QgsLabelFeature::zIndex ( ) const
inline

Returns the label's z-index.

Higher z-index labels are rendered on top of lower z-index labels.

See also
setZIndex()
Note
added in QGIS 2.14

Definition at line 163 of file qgslabelfeature.h.

Member Data Documentation

bool QgsLabelFeature::mAlwaysShow
protected

whether to always show label - even in case of collisions

Definition at line 352 of file qgslabelfeature.h.

double QgsLabelFeature::mDistLabel
protected

distance of label from the feature (only for "around point" placement or linestrings)

Definition at line 344 of file qgslabelfeature.h.

double QgsLabelFeature::mFixedAngle
protected

fixed rotation for the label (instead of automatic choice)

Definition at line 336 of file qgslabelfeature.h.

QgsPoint QgsLabelFeature::mFixedPosition
protected

fixed position for the label (instead of automatic placement)

Definition at line 332 of file qgslabelfeature.h.

GEOSGeometry* QgsLabelFeature::mGeometry
protected

Geometry of the feature to be labelled.

Definition at line 316 of file qgslabelfeature.h.

bool QgsLabelFeature::mHasFixedAngle
protected

whether mFixedAngle should be respected

Definition at line 334 of file qgslabelfeature.h.

bool QgsLabelFeature::mHasFixedPosition
protected

whether mFixedPosition should be respected

Definition at line 330 of file qgslabelfeature.h.

bool QgsLabelFeature::mHasFixedQuadrant
protected

whether mQuadOffset should be respected (only for "around point" placement)

Definition at line 338 of file qgslabelfeature.h.

QgsFeatureId QgsLabelFeature::mId
protected

Associated ID unique within the parent label provider.

Definition at line 314 of file qgslabelfeature.h.

pal::LabelInfo* QgsLabelFeature::mInfo
protected

extra information for curved labels (may be null)

Definition at line 360 of file qgslabelfeature.h.

bool QgsLabelFeature::mIsObstacle
protected

whether the feature geometry acts as an obstacle for labels

Definition at line 354 of file qgslabelfeature.h.

QString QgsLabelFeature::mLabelText
protected

text of the label

Definition at line 358 of file qgslabelfeature.h.

pal::Layer* QgsLabelFeature::mLayer
protected

Pointer to PAL layer (assigned when registered to PAL)

Definition at line 311 of file qgslabelfeature.h.

double QgsLabelFeature::mObstacleFactor
protected

how strong is the geometry acting as obstacle

Definition at line 356 of file qgslabelfeature.h.

GEOSGeometry* QgsLabelFeature::mObstacleGeometry
protected

Optional geometry to use for label obstacles, if different to mGeometry.

Definition at line 318 of file qgslabelfeature.h.

QgsPalLayerSettings::OffsetType QgsLabelFeature::mOffsetType
protected

Offset type for certain placement modes.

Definition at line 346 of file qgslabelfeature.h.

QgsPoint QgsLabelFeature::mPositionOffset
protected

offset of label from the feature (only for "offset from point" placement)

Definition at line 342 of file qgslabelfeature.h.

QVector< QgsPalLayerSettings::PredefinedPointPosition > QgsLabelFeature::mPredefinedPositionOrder
protected

Ordered list of predefined positions for label (only for OrderedPositionsAroundPoint placement)

Definition at line 348 of file qgslabelfeature.h.

double QgsLabelFeature::mPriority
protected

Priority of the label.

Definition at line 326 of file qgslabelfeature.h.

QPointF QgsLabelFeature::mQuadOffset
protected

whether the side of the label is fixed (only for "around point" placement)

Definition at line 340 of file qgslabelfeature.h.

double QgsLabelFeature::mRepeatDistance
protected

distance after which label should be repeated (only for linestrings)

Definition at line 350 of file qgslabelfeature.h.

QSizeF QgsLabelFeature::mSize
protected

Width and height of the label.

Definition at line 320 of file qgslabelfeature.h.

QSizeF QgsLabelFeature::mSymbolSize
protected

Size of associated rendered symbol, if applicable.

Definition at line 324 of file qgslabelfeature.h.

VisualMargin QgsLabelFeature::mVisualMargin
protected

Visual margin of label contents.

Definition at line 322 of file qgslabelfeature.h.

double QgsLabelFeature::mZIndex
protected

Z-index of label (higher z-index labels are rendered on top of lower z-index labels)

Definition at line 328 of file qgslabelfeature.h.


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