|
| 1 | +#ifndef QGSLABELFEATURE_H |
| 2 | +#define QGSLABELFEATURE_H |
| 3 | + |
| 4 | +#include "qgsgeometry.h" |
| 5 | + |
| 6 | +#include "qgspallabeling.h" |
| 7 | + |
| 8 | +namespace pal |
| 9 | +{ |
| 10 | + class LabelInfo; |
| 11 | +} |
| 12 | + |
| 13 | +class QgsAbstractLabelProvider; |
| 14 | +class QgsRenderContext; |
| 15 | +class QgsGeometry; |
| 16 | + |
| 17 | + |
| 18 | +/** |
| 19 | + * @brief The QgsLabelFeature class describes a feature that |
| 20 | + * should be used within the labeling engine. Those may be the usual textual labels, |
| 21 | + * diagrams, or any other custom type of map annotations (generated by custom |
| 22 | + * label providers). |
| 23 | + * |
| 24 | + * Instances only contain data relevant to the labeling engine (geometry, label size etc.) |
| 25 | + * necessary for the layout. Rendering of labels is done by label providers. |
| 26 | + * |
| 27 | + * Individual label providers may create subclasses of QgsLabelFeature in order to add |
| 28 | + * more data to the instances that will be later used for drawing of labels. |
| 29 | + * |
| 30 | + * @note this class is not a part of public API yet. See notes in QgsLabelingEngineV2 |
| 31 | + * @note added in QGIS 2.12 |
| 32 | + */ |
| 33 | +class CORE_EXPORT QgsLabelFeature |
| 34 | +{ |
| 35 | + public: |
| 36 | + //! Create label feature, takes ownership of the geometry instance |
| 37 | + QgsLabelFeature( QgsFeatureId id, GEOSGeometry* geometry, const QSizeF& size ); |
| 38 | + //! Clean up geometry and curved label info (if present) |
| 39 | + virtual ~QgsLabelFeature(); |
| 40 | + |
| 41 | + //! Identifier of the label (unique within the parent label provider) |
| 42 | + QgsFeatureId id() const { return mId; } |
| 43 | + |
| 44 | + //! Get access to the associated geometry |
| 45 | + GEOSGeometry* geometry() const { return mGeometry; } |
| 46 | + |
| 47 | + /** Sets the label's obstacle geometry, if different to the feature geometry. |
| 48 | + * This can be used to override the shape of the feature for obstacle detection, eg to |
| 49 | + * buffer around a point geometry to prevent labels being placed too close to the |
| 50 | + * point itself. It not set, the feature's geometry is used for obstacle detection. |
| 51 | + * Ownership of obstacle geometry is transferred. |
| 52 | + * @note added in QGIS 2.14 |
| 53 | + * @see obstacleGeometry() |
| 54 | + */ |
| 55 | + void setObstacleGeometry( GEOSGeometry* obstacleGeom ); |
| 56 | + |
| 57 | + /** Returns the label's obstacle geometry, if different to the feature geometry. |
| 58 | + * @note added in QGIS 2.14 |
| 59 | + * @see setObstacleGeometry() |
| 60 | + */ |
| 61 | + GEOSGeometry* obstacleGeometry() const { return mObstacleGeometry; } |
| 62 | + |
| 63 | + //! Size of the label (in map units) |
| 64 | + QSizeF size() const { return mSize; } |
| 65 | + |
| 66 | + /** Returns the feature's labeling priority. |
| 67 | + * @returns feature's priority, as a value between 0 (highest priority) |
| 68 | + * and 1 (lowest priority). Returns -1.0 if feature will use the layer's default priority. |
| 69 | + * @see setPriority |
| 70 | + */ |
| 71 | + double priority() const { return mPriority; } |
| 72 | + /** Sets the priority for labeling the feature. |
| 73 | + * @param priority feature's priority, as a value between 0 (highest priority) |
| 74 | + * and 1 (lowest priority). Set to -1.0 to use the layer's default priority |
| 75 | + * for this feature. |
| 76 | + * @see priority |
| 77 | + */ |
| 78 | + void setPriority( double priority ) { mPriority = priority; } |
| 79 | + |
| 80 | + //! Whether the label should use a fixed position instead of being automatically placed |
| 81 | + bool hasFixedPosition() const { return mHasFixedPosition; } |
| 82 | + //! Set whether the label should use a fixed position instead of being automatically placed |
| 83 | + void setHasFixedPosition( bool enabled ) { mHasFixedPosition = enabled; } |
| 84 | + //! Coordinates of the fixed position (relevant only if hasFixedPosition() returns true) |
| 85 | + QgsPoint fixedPosition() const { return mFixedPosition; } |
| 86 | + //! Set coordinates of the fixed position (relevant only if hasFixedPosition() returns true) |
| 87 | + void setFixedPosition( const QgsPoint& point ) { mFixedPosition = point; } |
| 88 | + |
| 89 | + //! Whether the label should use a fixed angle instead of using angle from automatic placement |
| 90 | + bool hasFixedAngle() const { return mHasFixedAngle; } |
| 91 | + //! Set whether the label should use a fixed angle instead of using angle from automatic placement |
| 92 | + void setHasFixedAngle( bool enabled ) { mHasFixedAngle = enabled; } |
| 93 | + //! Angle in degrees of the fixed angle (relevant only if hasFixedAngle() returns true) |
| 94 | + double fixedAngle() const { return mFixedAngle; } |
| 95 | + //! Set angle in degrees of the fixed angle (relevant only if hasFixedAngle() returns true) |
| 96 | + void setFixedAngle( double angle ) { mFixedAngle = angle; } |
| 97 | + |
| 98 | + /** Returns whether the quadrant for the label is fixed. |
| 99 | + * Applies to "around point" placement strategy. |
| 100 | + * @see setFixedQuadrant |
| 101 | + * @see quadOffset |
| 102 | + */ |
| 103 | + bool hasFixedQuadrant() const { return mHasFixedQuadrant; } |
| 104 | + /** Sets whether the quadrant for the label must be respected. This can be used |
| 105 | + * to fix the quadrant for specific features when using an "around point" placement. |
| 106 | + * @see fixedQuadrant |
| 107 | + * @see quadOffset |
| 108 | + */ |
| 109 | + void setHasFixedQuadrant( bool enabled ) { mHasFixedQuadrant = enabled; } |
| 110 | + //! Applies to "offset from point" placement strategy and "around point" (in case hasFixedQuadrant() returns true). |
| 111 | + //! Determines which side of the point to use. |
| 112 | + //! For X coordinate, values -1, 0, 1 mean left, center, right. |
| 113 | + //! For Y coordinate, values -1, 0, 1 mean above, center, below. |
| 114 | + QPointF quadOffset() const { return mQuadOffset; } |
| 115 | + //! Set which side of the point to use |
| 116 | + //! @see quadOffset |
| 117 | + void setQuadOffset( const QPointF& quadOffset ) { mQuadOffset = quadOffset; } |
| 118 | + //! Applies only to "offset from point" placement strategy. |
| 119 | + //! What offset (in map units) to use from the point |
| 120 | + QgsPoint positionOffset() const { return mPositionOffset; } |
| 121 | + //! Applies only to "offset from point" placement strategy. |
| 122 | + //! Set what offset (in map units) to use from the point |
| 123 | + void setPositionOffset( const QgsPoint& offset ) { mPositionOffset = offset; } |
| 124 | + //! Applies to "around point" placement strategy or linestring features. |
| 125 | + //! Distance of the label from the feature (in map units) |
| 126 | + double distLabel() const { return mDistLabel; } |
| 127 | + //! Applies to "around point" placement strategy or linestring features. |
| 128 | + //! Set distance of the label from the feature (in map units) |
| 129 | + void setDistLabel( double dist ) { mDistLabel = dist; } |
| 130 | + |
| 131 | + //! Applies only to linestring features - after what distance (in map units) |
| 132 | + //! the labels should be repeated (0 = no repetitions) |
| 133 | + double repeatDistance() const { return mRepeatDistance; } |
| 134 | + //! Applies only to linestring features - set after what distance (in map units) |
| 135 | + //! the labels should be repeated (0 = no repetitions) |
| 136 | + void setRepeatDistance( double dist ) { mRepeatDistance = dist; } |
| 137 | + |
| 138 | + //! Whether label should be always shown (sets very high label priority) |
| 139 | + bool alwaysShow() const { return mAlwaysShow; } |
| 140 | + //! Set whether label should be always shown (sets very high label priority) |
| 141 | + void setAlwaysShow( bool enabled ) { mAlwaysShow = enabled; } |
| 142 | + |
| 143 | + /** Returns whether the feature will act as an obstacle for labels. |
| 144 | + * @returns true if feature is an obstacle |
| 145 | + * @see setIsObstacle |
| 146 | + */ |
| 147 | + bool isObstacle() const { return mIsObstacle; } |
| 148 | + /** Sets whether the feature will act as an obstacle for labels. |
| 149 | + * @param enabled whether feature will act as an obstacle |
| 150 | + * @see isObstacle |
| 151 | + */ |
| 152 | + void setIsObstacle( bool enabled ) { mIsObstacle = enabled; } |
| 153 | + /** Returns the obstacle factor for the feature. The factor controls the penalty |
| 154 | + * for labels overlapping this feature. |
| 155 | + * @see setObstacleFactor |
| 156 | + */ |
| 157 | + double obstacleFactor() const { return mObstacleFactor; } |
| 158 | + /** Sets the obstacle factor for the feature. The factor controls the penalty |
| 159 | + * for labels overlapping this feature. |
| 160 | + * @param factor larger factors ( > 1.0 ) will result in labels |
| 161 | + * which are less likely to cover this feature, smaller factors ( < 1.0 ) mean labels |
| 162 | + * are more likely to cover this feature (where required) |
| 163 | + * @see obstacleFactor |
| 164 | + */ |
| 165 | + void setObstacleFactor( double factor ) { mObstacleFactor = factor; } |
| 166 | + |
| 167 | + /** Text of the label |
| 168 | + * |
| 169 | + * Used also if "merge connected lines to avoid duplicate labels" is enabled |
| 170 | + * to identify which features may be merged. |
| 171 | + */ |
| 172 | + QString labelText() const { return mLabelText; } |
| 173 | + //! Set text of the label |
| 174 | + void setLabelText( const QString& text ) { mLabelText = text; } |
| 175 | + |
| 176 | + //! Get additional infor required for curved label placement. Returns null if not set |
| 177 | + pal::LabelInfo* curvedLabelInfo() const { return mInfo; } |
| 178 | + //! takes ownership of the instance |
| 179 | + void setCurvedLabelInfo( pal::LabelInfo* info ) { mInfo = info; } |
| 180 | + |
| 181 | + //! Get PAL layer of the label feature. Should be only used internally in PAL |
| 182 | + pal::Layer* layer() const { return mLayer; } |
| 183 | + //! Assign PAL layer to the label feature. Should be only used internally in PAL |
| 184 | + void setLayer( pal::Layer* layer ) { mLayer = layer; } |
| 185 | + |
| 186 | + //! Return provider of this instance |
| 187 | + QgsAbstractLabelProvider* provider() const; |
| 188 | + |
| 189 | + protected: |
| 190 | + //! Pointer to PAL layer (assigned when registered to PAL) |
| 191 | + pal::Layer* mLayer; |
| 192 | + |
| 193 | + //! Associated ID unique within the parent label provider |
| 194 | + QgsFeatureId mId; |
| 195 | + //! Geometry of the feature to be labelled |
| 196 | + GEOSGeometry* mGeometry; |
| 197 | + //! Optional geometry to use for label obstacles, if different to mGeometry |
| 198 | + GEOSGeometry* mObstacleGeometry; |
| 199 | + //! Width and height of the label |
| 200 | + QSizeF mSize; |
| 201 | + //! Priority of the label |
| 202 | + double mPriority; |
| 203 | + //! whether mFixedPosition should be respected |
| 204 | + bool mHasFixedPosition; |
| 205 | + //! fixed position for the label (instead of automatic placement) |
| 206 | + QgsPoint mFixedPosition; |
| 207 | + //! whether mFixedAngle should be respected |
| 208 | + bool mHasFixedAngle; |
| 209 | + //! fixed rotation for the label (instead of automatic choice) |
| 210 | + double mFixedAngle; |
| 211 | + //! whether mQuadOffset should be respected (only for "around point" placement) |
| 212 | + bool mHasFixedQuadrant; |
| 213 | + //! whether the side of the label is fixed (only for "around point" placement) |
| 214 | + QPointF mQuadOffset; |
| 215 | + //! offset of label from the feature (only for "offset from point" placement) |
| 216 | + QgsPoint mPositionOffset; |
| 217 | + //! distance of label from the feature (only for "around point" placement or linestrings) |
| 218 | + double mDistLabel; |
| 219 | + //! distance after which label should be repeated (only for linestrings) |
| 220 | + double mRepeatDistance; |
| 221 | + //! whether to always show label - even in case of collisions |
| 222 | + bool mAlwaysShow; |
| 223 | + //! whether the feature geometry acts as an obstacle for labels |
| 224 | + bool mIsObstacle; |
| 225 | + //! how strong is the geometry acting as obstacle |
| 226 | + double mObstacleFactor; |
| 227 | + //! text of the label |
| 228 | + QString mLabelText; |
| 229 | + //! extra information for curved labels (may be null) |
| 230 | + pal::LabelInfo* mInfo; |
| 231 | +}; |
| 232 | + |
| 233 | +#endif // QGSLABELFEATURE_H |
0 commit comments