Branch data Line data Source code
1 : : /***************************************************************************
2 : : qgspallabeling.h
3 : : Smart labeling for vector layers
4 : : -------------------
5 : : begin : June 2009
6 : : copyright : (C) Martin Dobias
7 : : email : wonder dot sk at gmail dot com
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 : :
18 : : //Note: although this file is in the core library, it is not part of the stable API
19 : : //and might change at any time!
20 : :
21 : : #ifndef QGSPALLABELING_H
22 : : #define QGSPALLABELING_H
23 : :
24 : : #include "qgis_core.h"
25 : : #include "qgis_sip.h"
26 : : #include <QString>
27 : : #include <QFont>
28 : : #include <QFontDatabase>
29 : : #include <QColor>
30 : : #include <QHash>
31 : : #include <QList>
32 : : #include <QPainter>
33 : : #include <QRectF>
34 : : #include <QMap>
35 : : #include "qgsfeature.h"
36 : : #include "qgsgeometry.h"
37 : : #include "qgsfields.h"
38 : : #include "qgslabelingenginesettings.h"
39 : : #include "qgspointxy.h"
40 : : #include "qgsmapunitscale.h"
41 : : #include "qgsstringutils.h"
42 : : #include "qgssymbol.h"
43 : : #include "qgstextformat.h"
44 : : #include "qgspropertycollection.h"
45 : : #include "qgslabelobstaclesettings.h"
46 : : #include "qgslabelthinningsettings.h"
47 : : #include "qgslabellinesettings.h"
48 : : #include "qgslabeling.h"
49 : : #include "qgslabelposition.h"
50 : :
51 : : class QgsTextDocument;
52 : :
53 : : namespace pal SIP_SKIP
54 : : {
55 : : class Pal;
56 : : class Layer;
57 : : class LabelPosition;
58 : : }
59 : :
60 : : class QgsDiagramLayerSettings;
61 : : class QgsRectangle;
62 : : class QgsMapToPixel;
63 : : class QgsFeature;
64 : : class QgsTextLabelFeature;
65 : : class QgsVectorLayer;
66 : : class QgsExpression;
67 : : class QFontMetricsF;
68 : : class QPainter;
69 : : class QPicture;
70 : : class QgsGeometry;
71 : : class QgsCoordinateTransform;
72 : : class QgsLabelSearchTree;
73 : : class QgsMapSettings;
74 : : class QgsLabelFeature;
75 : : class QgsLabelingEngine;
76 : : class QgsPalLayerSettings;
77 : : class QgsVectorLayerLabelProvider;
78 : : class QgsDxfExport;
79 : : class QgsVectorLayerDiagramProvider;
80 : : class QgsExpressionContext;
81 : : class QgsCallout;
82 : :
83 : : /**
84 : : * \ingroup core
85 : : * \class QgsPalLayerSettings
86 : : * \brief Contains settings for how a map layer will be labeled.
87 : : */
88 : : class CORE_EXPORT QgsPalLayerSettings
89 : : {
90 : : public:
91 : : QgsPalLayerSettings();
92 : : QgsPalLayerSettings( const QgsPalLayerSettings &s );
93 : : ~QgsPalLayerSettings();
94 : :
95 : : //! copy operator - only copies the permanent members
96 : : QgsPalLayerSettings &operator=( const QgsPalLayerSettings &s );
97 : :
98 : : //TODO QGIS 4.0 - move to QgsLabelingEngine
99 : :
100 : : /**
101 : : * Placement modes which determine how label candidates are generated for a feature.
102 : : */
103 : : enum Placement
104 : : {
105 : : AroundPoint, //!< Arranges candidates in a circle around a point (or centroid of a polygon). Applies to point or polygon layers only.
106 : : OverPoint, //!< Arranges candidates over a point (or centroid of a polygon), or at a preset offset from the point. Applies to point or polygon layers only.
107 : : Line, //!< Arranges candidates parallel to a generalised line representing the feature or parallel to a polygon's perimeter. Applies to line or polygon layers only.
108 : : Curved, //!< Arranges candidates following the curvature of a line feature. Applies to line layers only.
109 : : Horizontal, //!< Arranges horizontal candidates scattered throughout a polygon feature. Applies to polygon layers only.
110 : : Free, //!< Arranges candidates scattered throughout a polygon feature. Candidates are rotated to respect the polygon's orientation. Applies to polygon layers only.
111 : : OrderedPositionsAroundPoint, //!< Candidates are placed in predefined positions around a point. Preference is given to positions with greatest cartographic appeal, e.g., top right, bottom right, etc. Applies to point layers only.
112 : : PerimeterCurved, //!< Arranges candidates following the curvature of a polygon's boundary. Applies to polygon layers only.
113 : : OutsidePolygons, //!< Candidates are placed outside of polygon boundaries. Applies to polygon layers only. Since QGIS 3.14
114 : : };
115 : :
116 : : //TODO QGIS 4.0 - move to QgsLabelingEngine
117 : : //! Positions for labels when using the QgsPalLabeling::OrderedPositionsAroundPoint placement mode
118 : : enum PredefinedPointPosition
119 : : {
120 : : TopLeft, //!< Label on top-left of point
121 : : TopSlightlyLeft, //!< Label on top of point, slightly left of center
122 : : TopMiddle, //!< Label directly above point
123 : : TopSlightlyRight, //!< Label on top of point, slightly right of center
124 : : TopRight, //!< Label on top-right of point
125 : : MiddleLeft, //!< Label on left of point
126 : : MiddleRight, //!< Label on right of point
127 : : BottomLeft, //!< Label on bottom-left of point
128 : : BottomSlightlyLeft, //!< Label below point, slightly left of center
129 : : BottomMiddle, //!< Label directly below point
130 : : BottomSlightlyRight, //!< Label below point, slightly right of center
131 : : BottomRight, //!< Label on bottom right of point
132 : : };
133 : :
134 : : //TODO QGIS 4.0 - move to QgsLabelingEngine
135 : :
136 : : /**
137 : : * Behavior modifier for label offset and distance, only applies in some
138 : : * label placement modes.
139 : : */
140 : : enum OffsetType
141 : : {
142 : : FromPoint, //!< Offset distance applies from point geometry
143 : : FromSymbolBounds, //!< Offset distance applies from rendered symbol bounds
144 : : };
145 : :
146 : : //TODO QGIS 4.0 - remove, replaced by QgsLabeling::LinePlacementFlags
147 : :
148 : : /**
149 : : * Line placement flags, which control how candidates are generated for a linear feature.
150 : : *
151 : : * \deprecated Use QgsLabeling::LinePlacementFlags instead
152 : : */
153 : : enum LinePlacementFlags
154 : : {
155 : : OnLine = 1, //!< Labels can be placed directly over a line feature.
156 : : AboveLine = 2, /**< Labels can be placed above a line feature. Unless MapOrientation is also specified this mode
157 : : respects the direction of the line feature, so a line from right to left labels will have labels
158 : : placed placed below the line feature. */
159 : : BelowLine = 4, /**< Labels can be placed below a line feature. Unless MapOrientation is also specified this mode
160 : : respects the direction of the line feature, so a line from right to left labels will have labels
161 : : placed placed above the line feature. */
162 : : MapOrientation = 8, /**< Signifies that the AboveLine and BelowLine flags should respect the map's orientation rather
163 : : than the feature's orientation. For example, AboveLine will always result in label's being placed
164 : : above a line, regardless of the line's direction. */
165 : : };
166 : :
167 : : enum QuadrantPosition
168 : : {
169 : : QuadrantAboveLeft,
170 : : QuadrantAbove,
171 : : QuadrantAboveRight,
172 : : QuadrantLeft,
173 : : QuadrantOver,
174 : : QuadrantRight,
175 : : QuadrantBelowLeft,
176 : : QuadrantBelow,
177 : : QuadrantBelowRight,
178 : : };
179 : :
180 : : enum UpsideDownLabels
181 : : {
182 : : Upright, //!< Upside-down labels (90 <= angle < 270) are shown upright
183 : : ShowDefined, //!< Show upside down when rotation is layer- or data-defined
184 : : ShowAll //!< Show upside down for all labels, including dynamic ones
185 : : };
186 : :
187 : : //TODO QGIS 4.0 - Remove -- moved to QgsLabelEngineObstacleSettings
188 : :
189 : : //! \deprecated use QgsLabelLineSettings::DirectionSymbolPlacement instead
190 : : enum DirectionSymbols
191 : : {
192 : : SymbolLeftRight, //!< Place direction symbols on left/right of label
193 : : SymbolAbove, //!< Place direction symbols on above label
194 : : SymbolBelow //!< Place direction symbols on below label
195 : : };
196 : :
197 : : enum MultiLineAlign
198 : : {
199 : : MultiLeft = 0,
200 : : MultiCenter,
201 : : MultiRight,
202 : : MultiFollowPlacement, /*!< Alignment follows placement of label, e.g., labels to the left of a feature
203 : : will be drawn with right alignment*/
204 : : MultiJustify, //!< Justified
205 : : };
206 : :
207 : : //TODO QGIS 4.0 - Remove -- moved to QgsLabelEngineObstacleSettings
208 : :
209 : : /**
210 : : * Valid obstacle types, which affect how features within the layer will act as obstacles
211 : : * for labels.
212 : : */
213 : : enum ObstacleType
214 : : {
215 : : PolygonInterior, /*!< avoid placing labels over interior of polygon (prefer placing labels totally
216 : : outside or just slightly inside polygon) */
217 : : PolygonBoundary, /*!< avoid placing labels over boundary of polygon (prefer placing outside or
218 : : completely inside polygon) */
219 : : PolygonWhole /*!< avoid placing labels over ANY part of polygon. Where PolygonInterior will prefer
220 : : to place labels with the smallest area of intersection between the label and the polygon,
221 : : PolygonWhole will penalise any label which intersects with the polygon by an equal amount, so that
222 : : placing labels over any part of the polygon is avoided.*/
223 : : };
224 : :
225 : : //! Data definable properties.
226 : : enum Property
227 : : {
228 : : // text style
229 : : Size = 0, //!< Label size
230 : : Bold = 1, //!< Use bold style
231 : : Italic = 2, //!< Use italic style
232 : : Underline = 3, //!< Use underline
233 : : Color = 4, //!< Text color
234 : : Strikeout = 5, //!< Use strikeout
235 : : Family = 6, //!< Font family
236 : : FontStyle = 21, //!< Font style name
237 : : FontSizeUnit = 22, //!< Font size units
238 : : FontTransp = 18, //!< Text transparency (deprecated)
239 : : FontOpacity = 92, //!< Text opacity
240 : : FontCase = 27, //!< Label text case
241 : : FontLetterSpacing = 28, //!< Letter spacing
242 : : FontWordSpacing = 29, //!< Word spacing
243 : : FontBlendMode = 30, //!< Text blend mode
244 : :
245 : : // text formatting
246 : : MultiLineWrapChar = 31,
247 : : AutoWrapLength = 101,
248 : : MultiLineHeight = 32,
249 : : MultiLineAlignment = 33,
250 : : TextOrientation = 110,
251 : : DirSymbDraw = 34,
252 : : DirSymbLeft = 35,
253 : : DirSymbRight = 36,
254 : : DirSymbPlacement = 37,
255 : : DirSymbReverse = 38,
256 : : NumFormat = 39,
257 : : NumDecimals = 40,
258 : : NumPlusSign = 41,
259 : :
260 : : // text buffer
261 : : BufferDraw = 42,
262 : : BufferSize = 7,
263 : : BufferUnit = 43,
264 : : BufferColor = 8,
265 : : BufferTransp = 19, //!< Buffer transparency (deprecated)
266 : : BufferOpacity = 94, //!< Buffer opacity
267 : : BufferJoinStyle = 44,
268 : : BufferBlendMode = 45,
269 : :
270 : : // mask buffer
271 : : MaskEnabled = 104, //!< Whether the mask is enabled
272 : : MaskBufferSize = 105, //!< Mask buffer size
273 : : MaskBufferUnit = 106, //!< Mask buffer size unit
274 : : MaskOpacity = 107, //!< Mask opacity
275 : : MaskJoinStyle = 108, //!< Mask join style
276 : :
277 : : // background
278 : : ShapeDraw = 46,
279 : : ShapeKind = 47,
280 : : ShapeSVGFile = 48,
281 : : ShapeSizeType = 49,
282 : : ShapeSizeX = 50,
283 : : ShapeSizeY = 85,
284 : : ShapeSizeUnits = 51,
285 : : ShapeRotationType = 52,
286 : : ShapeRotation = 53,
287 : : ShapeOffset = 54,
288 : : ShapeOffsetUnits = 55,
289 : : ShapeRadii = 56,
290 : : ShapeRadiiUnits = 57,
291 : : ShapeTransparency = 63, //!< Shape transparency (deprecated)
292 : : ShapeOpacity = 93, //!< Shape opacity
293 : : ShapeBlendMode = 64,
294 : : ShapeFillColor = 58,
295 : : ShapeStrokeColor = 59,
296 : : ShapeStrokeWidth = 60,
297 : : ShapeStrokeWidthUnits = 61,
298 : : ShapeJoinStyle = 62,
299 : :
300 : : // drop shadow
301 : : ShadowDraw = 65,
302 : : ShadowUnder = 66,
303 : : ShadowOffsetAngle = 67,
304 : : ShadowOffsetDist = 68,
305 : : ShadowOffsetUnits = 69,
306 : : ShadowRadius = 70,
307 : : ShadowRadiusUnits = 71,
308 : : ShadowTransparency = 72, //!< Shadow transparency (deprecated)
309 : : ShadowOpacity = 95, //!< Shadow opacity
310 : : ShadowScale = 73,
311 : : ShadowColor = 74,
312 : : ShadowBlendMode = 75,
313 : :
314 : : // placement
315 : : CentroidWhole = 76,
316 : : OffsetQuad = 77,
317 : : OffsetXY = 78,
318 : : OffsetUnits = 80,
319 : : LabelDistance = 13,
320 : : DistanceUnits = 81,
321 : : OffsetRotation = 82,
322 : : CurvedCharAngleInOut = 83,
323 : : // (data defined only)
324 : : PositionX = 9, //!< X-coordinate data defined label position
325 : : PositionY = 10, //!< Y-coordinate data defined label position
326 : : Hali = 11, //!< Horizontal alignment for data defined label position (Left, Center, Right)
327 : : Vali = 12, //!< Vertical alignment for data defined label position (Bottom, Base, Half, Cap, Top)
328 : : Rotation = 14, //!< Label rotation (deprecated, for old project compatibility only)
329 : : LabelRotation = 96, //!< Label rotation
330 : : RepeatDistance = 84,
331 : : RepeatDistanceUnit = 86,
332 : : Priority = 87,
333 : : PredefinedPositionOrder = 91,
334 : : LinePlacementOptions = 99, //!< Line placement flags
335 : : OverrunDistance = 102, //!< Distance which labels can extend past either end of linear features
336 : : LabelAllParts = 103, //!< Whether all parts of multi-part features should be labeled
337 : : PolygonLabelOutside = 109, //!< Whether labels outside a polygon feature are permitted, or should be forced (since QGIS 3.14)
338 : : LineAnchorPercent = 111, //!< Portion along line at which labels should be anchored (since QGIS 3.16)
339 : : LineAnchorClipping = 112, //!< Clipping mode for line anchor calculation (since QGIS 3.20)
340 : :
341 : : // rendering
342 : : ScaleVisibility = 23,
343 : : MinScale = 16, //!< Min scale (deprecated, for old project compatibility only)
344 : : MinimumScale = 97, //!< Minimum map scale (ie most "zoomed out")
345 : : MaxScale = 17, //!< Max scale (deprecated, for old project compatibility only)
346 : : MaximumScale = 98, //!< Maximum map scale (ie most "zoomed in")
347 : : FontLimitPixel = 24,
348 : : FontMinPixel = 25,
349 : : FontMaxPixel = 26,
350 : : IsObstacle = 88,
351 : : ObstacleFactor = 89,
352 : : ZIndex = 90,
353 : : CalloutDraw = 100, //!< Show callout
354 : :
355 : : // (data defined only)
356 : : Show = 15,
357 : : AlwaysShow = 20
358 : : };
359 : :
360 : :
361 : : /**
362 : : * Prepare for registration of features.
363 : : * The \a context, \a mapSettings and \a fields parameters give more
364 : : * information about the rendering environment.
365 : : * If target \a crs is not specified, the targetCrs from \a mapSettings
366 : : * will be taken.
367 : : * The parameter \a attributeNames should be updated to contain all the field
368 : : * names which the labeling requires for the rendering.
369 : : *
370 : : * \since QGIS 3.8
371 : : */
372 : : bool prepare( QgsRenderContext &context, QSet<QString> &attributeNames SIP_INOUT, const QgsFields &fields, const QgsMapSettings &mapSettings, const QgsCoordinateReferenceSystem &crs );
373 : :
374 : : /**
375 : : * Returns all field names referenced by the configuration (e.g. field name or expression, data defined properties).
376 : : * \since QGIS 3.14
377 : : */
378 : : QSet<QString> referencedFields( const QgsRenderContext &context ) const;
379 : :
380 : : /**
381 : : * Prepares the label settings for rendering.
382 : : *
383 : : * This should be called before rendering any labels, and must be
384 : : * followed by a call to stopRender() in order to gracefully clean up symbols.
385 : : *
386 : : * \since QGIS 3.10
387 : : */
388 : : void startRender( QgsRenderContext &context );
389 : :
390 : : /**
391 : : * Finalises the label settings after use.
392 : : *
393 : : * This must be called after a call to startRender(), in order to gracefully clean up symbols.
394 : : *
395 : : * \since QGIS 3.10
396 : : */
397 : : void stopRender( QgsRenderContext &context );
398 : :
399 : : /**
400 : : * Returns the labeling property definitions.
401 : : * \since QGIS 3.0
402 : : */
403 : : static const QgsPropertiesDefinition &propertyDefinitions();
404 : :
405 : : /**
406 : : * Whether to draw labels for this layer. For some layers it may be desirable
407 : : * to register their features as obstacles for other labels without requiring
408 : : * labels to be drawn for the layer itself. In this case drawLabels can be set
409 : : * to FALSE and obstacle set to TRUE, which will result in the layer acting
410 : : * as an obstacle but having no labels of its own.
411 : : * \since QGIS 2.12
412 : : */
413 : : bool drawLabels = true;
414 : :
415 : : //-- text style
416 : :
417 : : /**
418 : : * Name of field (or an expression) to use for label text.
419 : : * If fieldName is an expression, then isExpression should be set to TRUE.
420 : : * \see isExpression
421 : : */
422 : : QString fieldName;
423 : :
424 : : /**
425 : : * TRUE if this label is made from a expression string, e.g., FieldName || 'mm'
426 : : * \see fieldName
427 : : */
428 : : bool isExpression = false;
429 : :
430 : : /**
431 : : * Returns the QgsExpression for this label settings. May be NULLPTR if isExpression is FALSE.
432 : : */
433 : : QgsExpression *getLabelExpression();
434 : :
435 : : /**
436 : : * \deprecated since QGIS 3.10. Use QgsTextFormat::previewBackgroundColor() instead.
437 : : */
438 : : Q_DECL_DEPRECATED QColor previewBkgrdColor = Qt::white;
439 : :
440 : : //! Substitution collection for automatic text substitution with labels
441 : : QgsStringReplacementCollection substitutions;
442 : : //! True if substitutions should be applied
443 : : bool useSubstitutions = false;
444 : :
445 : : //-- text formatting
446 : :
447 : : /**
448 : : * Wrapping character string. If set, any occurrences of this string in the calculated
449 : : * label text will be replaced with new line characters.
450 : : */
451 : : QString wrapChar;
452 : :
453 : : /**
454 : : * If non-zero, indicates that label text should be automatically wrapped to (ideally) the specified
455 : : * number of characters. If zero, auto wrapping is disabled.
456 : : *
457 : : * \see useMaxLineLengthForAutoWrap
458 : : * \since QGIS 3.4
459 : : */
460 : : int autoWrapLength = 0;
461 : :
462 : : /**
463 : : * If TRUE, indicates that when auto wrapping label text the autoWrapLength length indicates the maximum
464 : : * ideal length of text lines. If FALSE, then autoWrapLength indicates the ideal minimum length of text
465 : : * lines.
466 : : *
467 : : * If autoWrapLength is 0 then this value has no effect.
468 : : *
469 : : * \see autoWrapLength
470 : : * \since QGIS 3.4
471 : : */
472 : : bool useMaxLineLengthForAutoWrap = true;
473 : :
474 : : //! Horizontal alignment of multi-line labels.
475 : : MultiLineAlign multilineAlign = MultiFollowPlacement;
476 : :
477 : : /**
478 : : * Set to TRUE to format numeric label text as numbers (e.g. inserting thousand separators
479 : : * and fixed number of decimal places).
480 : : * \see decimals
481 : : * \see plusSign
482 : : */
483 : : bool formatNumbers = false;
484 : :
485 : : /**
486 : : * Number of decimal places to show for numeric labels. formatNumbers must be TRUE for this
487 : : * setting to have an effect.
488 : : * \see formatNumbers
489 : : */
490 : : int decimals = 3;
491 : :
492 : : /**
493 : : * Whether '+' signs should be prepended to positive numeric labels. formatNumbers must be TRUE for this
494 : : * setting to have an effect.
495 : : * \see formatNumbers
496 : : */
497 : : bool plusSign = false;
498 : :
499 : : //-- placement
500 : :
501 : : Placement placement = AroundPoint;
502 : :
503 : : /**
504 : : * Returns the polygon placement flags, which dictate how polygon labels can be placed.
505 : : *
506 : : * \see setPolygonPlacementFlags()
507 : : * \since QGIS 3.14
508 : : */
509 : : QgsLabeling::PolygonPlacementFlags polygonPlacementFlags() const { return mPolygonPlacementFlags; }
510 : :
511 : : /**
512 : : * Sets the polygon placement \a flags, which dictate how polygon labels can be placed.
513 : : *
514 : : * \see polygonPlacementFlags()
515 : : * \since QGIS 3.14
516 : : */
517 : : void setPolygonPlacementFlags( QgsLabeling::PolygonPlacementFlags flags ) { mPolygonPlacementFlags = flags; }
518 : :
519 : : /**
520 : : * TRUE if feature centroid should be calculated from the whole feature, or
521 : : * FALSE if only the visible part of the feature should be considered.
522 : : */
523 : : bool centroidWhole = false;
524 : :
525 : : /**
526 : : * TRUE if centroid positioned labels must be placed inside their corresponding
527 : : * feature polygon, or FALSE if centroids which fall outside the polygon
528 : : * are permitted.
529 : : */
530 : : bool centroidInside = false;
531 : :
532 : : /**
533 : : * Ordered list of predefined label positions for points. Positions earlier
534 : : * in the list will be prioritized over later positions. Only used when the placement
535 : : * is set to QgsPalLayerSettings::OrderedPositionsAroundPoint.
536 : : * \note not available in Python bindings
537 : : */
538 : : QVector< PredefinedPointPosition > predefinedPositionOrder SIP_SKIP;
539 : :
540 : : /**
541 : : * TRUE if only labels which completely fit within a polygon are allowed.
542 : : */
543 : : bool fitInPolygonOnly = false;
544 : :
545 : : /**
546 : : * Distance from feature to the label. Units are specified via distUnits.
547 : : * \see distUnits
548 : : * \see distMapUnitScale
549 : : */
550 : : double dist = 0;
551 : :
552 : : /**
553 : : * Units the distance from feature to the label.
554 : : * \see dist
555 : : * \see distMapUnitScale
556 : : */
557 : : QgsUnitTypes::RenderUnit distUnits = QgsUnitTypes::RenderMillimeters;
558 : :
559 : : /**
560 : : * Map unit scale for label feature distance.
561 : : * \see dist
562 : : * \see distUnits
563 : : */
564 : : QgsMapUnitScale distMapUnitScale;
565 : :
566 : : //! Offset type for layer (only applies in certain placement modes)
567 : : OffsetType offsetType = FromPoint;
568 : :
569 : : /**
570 : : * Distance for repeating labels for a single feature.
571 : : * \see repeatDistanceUnit
572 : : * \see repeatDistanceMapUnitScale
573 : : */
574 : : double repeatDistance = 0;
575 : :
576 : : /**
577 : : * Units for repeating labels for a single feature.
578 : : * \see repeatDistance
579 : : * \see repeatDistanceMapUnitScale
580 : : */
581 : : QgsUnitTypes::RenderUnit repeatDistanceUnit = QgsUnitTypes::RenderMillimeters;
582 : :
583 : : /**
584 : : * Map unit scale for repeating labels for a single feature.
585 : : * \see repeatDistance
586 : : * \see repeatDistanceUnit
587 : : */
588 : : QgsMapUnitScale repeatDistanceMapUnitScale;
589 : :
590 : : /**
591 : : * Sets the quadrant in which to offset labels from feature.
592 : : */
593 : : QuadrantPosition quadOffset = QuadrantOver;
594 : :
595 : : /**
596 : : * Horizontal offset of label. Units are specified via offsetUnits.
597 : : * \see yOffset
598 : : * \see offsetUnits
599 : : * \see labelOffsetMapUnitScale
600 : : */
601 : : double xOffset = 0;
602 : :
603 : : /**
604 : : * Vertical offset of label. Units are specified via offsetUnits.
605 : : * \see xOffset
606 : : * \see offsetUnits
607 : : * \see labelOffsetMapUnitScale
608 : : */
609 : : double yOffset = 0;
610 : :
611 : : /**
612 : : * Units for offsets of label.
613 : : * \see xOffset
614 : : * \see yOffset
615 : : * \see labelOffsetMapUnitScale
616 : : */
617 : : QgsUnitTypes::RenderUnit offsetUnits = QgsUnitTypes::RenderMillimeters;
618 : :
619 : : /**
620 : : * Map unit scale for label offset.
621 : : * \see xOffset
622 : : * \see yOffset
623 : : * \see offsetUnits
624 : : */
625 : : QgsMapUnitScale labelOffsetMapUnitScale;
626 : :
627 : : //! Label rotation, in degrees clockwise
628 : : double angleOffset = 0;
629 : :
630 : : //! True if label rotation should be preserved during label pin/unpin operations.
631 : : bool preserveRotation = true;
632 : :
633 : : /**
634 : : * Maximum angle between inside curved label characters (valid range 20.0 to 60.0).
635 : : * \see maxCurvedCharAngleOut
636 : : */
637 : : double maxCurvedCharAngleIn = 25.0;
638 : :
639 : : /**
640 : : * Maximum angle between outside curved label characters (valid range -20.0 to -95.0)
641 : : * \see maxCurvedCharAngleIn
642 : : */
643 : : double maxCurvedCharAngleOut = -25.0;
644 : :
645 : : /**
646 : : * Label priority. Valid ranges are from 0 to 10, where 0 = lowest priority
647 : : * and 10 = highest priority.
648 : : */
649 : : int priority = 5;
650 : :
651 : : //-- rendering
652 : :
653 : : /**
654 : : * Set to TRUE to limit label visibility to a range of scales.
655 : : * \see maximumScale
656 : : * \see minimumScale
657 : : */
658 : : bool scaleVisibility = false;
659 : :
660 : : /**
661 : : * The maximum map scale (i.e. most "zoomed in" scale) at which the labels will be visible.
662 : : * The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
663 : : * A scale of 0 indicates no maximum scale visibility.
664 : : *
665 : : * This setting is only considered if scaleVisibility is TRUE.
666 : : *
667 : : * \see minimumScale
668 : : * \see scaleVisibility
669 : : */
670 : : double maximumScale = 0;
671 : :
672 : : /**
673 : : * The minimum map scale (i.e. most "zoomed out" scale) at which the labels will be visible.
674 : : * The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
675 : : * A scale of 0 indicates no minimum scale visibility.
676 : : *
677 : : * This setting is only considered if scaleVisibility is TRUE.
678 : : *
679 : : * \see maximumScale
680 : : * \see scaleVisibility
681 : : */
682 : : double minimumScale = 0;
683 : :
684 : : /**
685 : : * TRUE if label sizes should be limited by pixel size.
686 : : * \see fontMinPixelSize
687 : : * \see fontMaxPixelSize
688 : : */
689 : : bool fontLimitPixelSize = false;
690 : :
691 : : /**
692 : : * Minimum pixel size for showing rendered map unit labels (1 - 1000).
693 : : * \see fontLimitPixelSize
694 : : * \see fontMaxPixelSize
695 : : */
696 : : int fontMinPixelSize = 0;
697 : :
698 : : /**
699 : : * Maximum pixel size for showing rendered map unit labels (1 - 10000).
700 : : * \see fontLimitPixelSize
701 : : * \see fontMinPixelSize
702 : : */
703 : : int fontMaxPixelSize = 10000;
704 : :
705 : : //! If TRUE, all features will be labelled even when overlaps occur.
706 : : bool displayAll = false;
707 : :
708 : : //! Controls whether upside down labels are displayed and how they are handled.
709 : : UpsideDownLabels upsidedownLabels = Upright;
710 : :
711 : : /**
712 : : * TRUE if every part of a multi-part feature should be labeled. If FALSE,
713 : : * only the largest part will be labeled.
714 : : */
715 : : bool labelPerPart = false;
716 : :
717 : : // TODO QGIS 4.0 - remove this junk
718 : :
719 : : #ifdef SIP_RUN
720 : : SIP_PROPERTY( name = limitNumLabels, get = _limitNumLabels, set = _setLimitNumLabels )
721 : : SIP_PROPERTY( name = maxNumLabels, get = _maxNumLabels, set = _setMaxNumLabels )
722 : : SIP_PROPERTY( name = minFeatureSize, get = _minFeatureSize, set = _setMinFeatureSize )
723 : : SIP_PROPERTY( name = obstacle, get = _getIsObstacle, set = _setIsObstacle )
724 : : SIP_PROPERTY( name = obstacleFactor, get = _getObstacleFactor, set = _setObstacleFactor )
725 : : SIP_PROPERTY( name = obstacleType, get = _getObstacleType, set = _setObstacleType )
726 : : SIP_PROPERTY( name = placementFlags, get = _getLinePlacementFlags, set = _setLinePlacementFlags )
727 : : SIP_PROPERTY( name = mergeLines, get = _getMergeLines, set = _setMergeLines )
728 : : SIP_PROPERTY( name = addDirectionSymbol, get = _getAddDirectionSymbol, set = _setAddDirectionSymbol )
729 : : SIP_PROPERTY( name = leftDirectionSymbol, get = _getLeftDirectionSymbol, set = _setLeftDirectionSymbol )
730 : : SIP_PROPERTY( name = rightDirectionSymbol, get = _getRightDirectionSymbol, set = _setRightDirectionSymbol )
731 : : SIP_PROPERTY( name = reverseDirectionSymbol, get = _getReverseDirectionSymbol, set = _setReverseDirectionSymbol )
732 : : SIP_PROPERTY( name = placeDirectionSymbol, get = _getPlaceDirectionSymbol, set = _setPlaceDirectionSymbol )
733 : :
734 : : SIP_PROPERTY( name = overrunDistance, get = _getOverrunDistance, set = _setOverrunDistance )
735 : : SIP_PROPERTY( name = overrunDistanceUnit, get = _getOverrunDistanceUnit, set = _setOverrunDistanceUnit )
736 : : SIP_PROPERTY( name = overrunDistanceMapUnitScale, get = _getOverrunDistanceMapUnitScale, set = _setOverrunDistanceMapUnitScale )
737 : : #endif
738 : :
739 : : ///@cond PRIVATE
740 : : bool _limitNumLabels() const { return mThinningSettings.limitNumberOfLabelsEnabled(); }
741 : : void _setLimitNumLabels( bool limit ) { mThinningSettings.setLimitNumberLabelsEnabled( limit ); }
742 : : int _maxNumLabels() const { return mThinningSettings.maximumNumberLabels(); }
743 : : void _setMaxNumLabels( int max ) { mThinningSettings.setMaximumNumberLabels( max ); }
744 : : double _minFeatureSize() const { return mThinningSettings.minimumFeatureSize(); }
745 : : void _setMinFeatureSize( double size ) { mThinningSettings.setMinimumFeatureSize( size ); }
746 : : bool _getIsObstacle() const { return mObstacleSettings.isObstacle(); }
747 : : void _setIsObstacle( bool obstacle ) { mObstacleSettings.setIsObstacle( obstacle ); }
748 : : double _getObstacleFactor() const { return mObstacleSettings.factor(); }
749 : : void _setObstacleFactor( double factor ) { mObstacleSettings.setFactor( factor ); }
750 : : ObstacleType _getObstacleType() const { return static_cast< ObstacleType>( mObstacleSettings.type() ); }
751 : : void _setObstacleType( ObstacleType type ) { mObstacleSettings.setType( static_cast< QgsLabelObstacleSettings::ObstacleType>( type ) ); }
752 : : unsigned int _getLinePlacementFlags() const { return static_cast< unsigned int >( mLineSettings.placementFlags() ); }
753 : : void _setLinePlacementFlags( unsigned int flags ) { mLineSettings.setPlacementFlags( static_cast< QgsLabeling::LinePlacementFlags >( flags ) ); }
754 : : bool _getMergeLines() const { return mLineSettings.mergeLines(); }
755 : : void _setMergeLines( bool merge ) { mLineSettings.setMergeLines( merge ); }
756 : : bool _getAddDirectionSymbol() const { return mLineSettings.addDirectionSymbol(); }
757 : : void _setAddDirectionSymbol( bool add ) { mLineSettings.setAddDirectionSymbol( add ); }
758 : : QString _getLeftDirectionSymbol() const { return mLineSettings.leftDirectionSymbol(); }
759 : : void _setLeftDirectionSymbol( const QString &symbol ) { mLineSettings.setLeftDirectionSymbol( symbol ); }
760 : : QString _getRightDirectionSymbol() const { return mLineSettings.rightDirectionSymbol(); }
761 : : void _setRightDirectionSymbol( const QString &symbol ) { mLineSettings.setRightDirectionSymbol( symbol ); }
762 : : bool _getReverseDirectionSymbol() const { return mLineSettings.reverseDirectionSymbol(); }
763 : : void _setReverseDirectionSymbol( bool reverse ) { mLineSettings.setReverseDirectionSymbol( reverse ); }
764 : : Q_NOWARN_DEPRECATED_PUSH
765 : : DirectionSymbols _getPlaceDirectionSymbol() const { return static_cast< DirectionSymbols>( mLineSettings.directionSymbolPlacement() ); }
766 : : void _setPlaceDirectionSymbol( DirectionSymbols placement ) { mLineSettings.setDirectionSymbolPlacement( static_cast< QgsLabelLineSettings::DirectionSymbolPlacement>( placement ) ); }
767 : : Q_NOWARN_DEPRECATED_POP
768 : : double _getOverrunDistance() const { return mLineSettings.overrunDistance(); }
769 : : void _setOverrunDistance( double distance ) { mLineSettings.setOverrunDistance( distance ); }
770 : : QgsUnitTypes::RenderUnit _getOverrunDistanceUnit() const { return mLineSettings.overrunDistanceUnit(); }
771 : : void _setOverrunDistanceUnit( QgsUnitTypes::RenderUnit unit ) { mLineSettings.setOverrunDistanceUnit( unit ); }
772 : : QgsMapUnitScale _getOverrunDistanceMapUnitScale() const { return mLineSettings.overrunDistanceMapUnitScale(); }
773 : : void _setOverrunDistanceMapUnitScale( const QgsMapUnitScale &scale ) { mLineSettings.setOverrunDistanceMapUnitScale( scale ); }
774 : : ///@endcond
775 : :
776 : : //! Z-Index of label, where labels with a higher z-index are rendered on top of labels with a lower z-index
777 : : double zIndex = 0;
778 : :
779 : : //! The geometry generator expression. Null if disabled.
780 : : QString geometryGenerator;
781 : :
782 : : //! The type of the result geometry of the geometry generator.
783 : : QgsWkbTypes::GeometryType geometryGeneratorType = QgsWkbTypes::GeometryType::PointGeometry;
784 : :
785 : : //! Defines if the geometry generator is enabled or not. If disabled, the standard geometry will be taken.
786 : : bool geometryGeneratorEnabled = false;
787 : :
788 : : /**
789 : : * Geometry type of layers associated with these settings.
790 : : * \since QGIS 3.10
791 : : */
792 : : QgsWkbTypes::GeometryType layerType = QgsWkbTypes::UnknownGeometry;
793 : :
794 : : /**
795 : : * Calculates the space required to render the provided \a text in map units.
796 : : * Results will be written to \a labelX and \a labelY.
797 : : * If the text orientation is set to rotation-based, the spaced taken to render
798 : : * vertically oriented text will be written to \a rotatedLabelX and \a rotatedLabelY .
799 : : */
800 : : #ifndef SIP_RUN
801 : : void calculateLabelSize( const QFontMetricsF *fm, const QString &text, double &labelX, double &labelY, const QgsFeature *f = nullptr, QgsRenderContext *context = nullptr, double *rotatedLabelX SIP_OUT = nullptr, double *rotatedLabelY SIP_OUT = nullptr,
802 : : QgsTextDocument *document = nullptr );
803 : : #else
804 : : void calculateLabelSize( const QFontMetricsF *fm, const QString &text, double &labelX, double &labelY, const QgsFeature *f = nullptr, QgsRenderContext *context = nullptr, double *rotatedLabelX SIP_OUT = nullptr, double *rotatedLabelY SIP_OUT = nullptr );
805 : : #endif
806 : :
807 : : /**
808 : : * Register a feature for labeling.
809 : : * \param f feature to label
810 : : * \param context render context. The QgsExpressionContext contained within the render context
811 : : * must have already had the feature and fields sets prior to calling this method.
812 : : * \param labelFeature if using QgsLabelingEngine, this will receive the label feature. Not available
813 : : * in Python bindings.
814 : : * \param obstacleGeometry optional obstacle geometry, if a different geometry to the feature's geometry
815 : : * should be used as an obstacle for labels (e.g., if the feature has been rendered with an offset point
816 : : * symbol, the obstacle geometry should represent the bounds of the offset symbol). If not set,
817 : : * the feature's original geometry will be used as an obstacle for labels. Not available
818 : : * in Python bindings.
819 : : * \param symbol feature symbol to label (ownership is not transferred, and \a symbol must exist until the labeling is complete)
820 : : */
821 : : void registerFeature( const QgsFeature &f, QgsRenderContext &context,
822 : : QgsLabelFeature **labelFeature SIP_PYARGREMOVE = nullptr,
823 : : QgsGeometry obstacleGeometry SIP_PYARGREMOVE = QgsGeometry(), const QgsSymbol *symbol SIP_PYARGREMOVE = nullptr );
824 : :
825 : : /**
826 : : * Read settings from a DOM element
827 : : * \since QGIS 2.12
828 : : */
829 : : void readXml( const QDomElement &elem, const QgsReadWriteContext &context );
830 : :
831 : : /**
832 : : * Write settings into a DOM element
833 : : * \since QGIS 2.12
834 : : */
835 : : QDomElement writeXml( QDomDocument &doc, const QgsReadWriteContext &context ) const;
836 : :
837 : : /**
838 : : * Returns a reference to the label's property collection, used for data defined overrides.
839 : : * \see setDataDefinedProperties()
840 : : * \since QGIS 3.0
841 : : */
842 : 0 : QgsPropertyCollection &dataDefinedProperties() { return mDataDefinedProperties; }
843 : :
844 : : /**
845 : : * Returns a reference to the label's property collection, used for data defined overrides.
846 : : * \see setDataDefinedProperties()
847 : : * \see Property
848 : : * \note not available in Python bindings
849 : : * \since QGIS 3.0
850 : : */
851 : 0 : const QgsPropertyCollection &dataDefinedProperties() const SIP_SKIP { return mDataDefinedProperties; }
852 : :
853 : : /**
854 : : * Sets the label's property collection, used for data defined overrides.
855 : : * \param collection property collection. Existing properties will be replaced.
856 : : * \see dataDefinedProperties()
857 : : * \see Property
858 : : * \since QGIS 3.0
859 : : */
860 : 0 : void setDataDefinedProperties( const QgsPropertyCollection &collection ) { mDataDefinedProperties = collection; }
861 : :
862 : : /**
863 : : * Returns the label text formatting settings, e.g., font settings, buffer settings, etc.
864 : : * \see setFormat()
865 : : * \since QGIS 3.0
866 : : */
867 : 0 : const QgsTextFormat &format() const { return mFormat; }
868 : :
869 : : /**
870 : : * Sets the label text formatting settings, e.g., font settings, buffer settings, etc.
871 : : * \param format label text format
872 : : * \see format()
873 : : * \since QGIS 3.0
874 : : */
875 : 0 : void setFormat( const QgsTextFormat &format ) { mFormat = format; }
876 : :
877 : : /**
878 : : * Returns the label callout renderer, responsible for drawing label callouts.
879 : : *
880 : : * Ownership is not transferred.
881 : : *
882 : : * \see setCallout()
883 : : * \since QGIS 3.10
884 : : */
885 : 0 : QgsCallout *callout() const { return mCallout.get(); }
886 : :
887 : : /**
888 : : * Sets the label \a callout renderer, responsible for drawing label callouts.
889 : : *
890 : : * Ownership of \a callout is transferred to the settings.
891 : :
892 : : * \see callout()
893 : : * \since QGIS 3.10
894 : : */
895 : : void setCallout( QgsCallout *callout SIP_TRANSFER );
896 : :
897 : : /**
898 : : * Returns the label line settings, which contain settings related to how the label
899 : : * engine places and formats labels for line features (or polygon features which are labeled in
900 : : * a "perimeter" style mode).
901 : : * \see setLineSettings()
902 : : * \note Not available in Python bindings
903 : : * \since QGIS 3.16
904 : : */
905 : : const QgsLabelLineSettings &lineSettings() const { return mLineSettings; } SIP_SKIP
906 : :
907 : : /**
908 : : * Returns the label line settings, which contain settings related to how the label
909 : : * engine places and formats labels for line features (or polygon features which are labeled in
910 : : * a "perimeter" style mode).
911 : : * \see setLineSettings()
912 : : * \since QGIS 3.16
913 : : */
914 : 0 : QgsLabelLineSettings &lineSettings() { return mLineSettings; }
915 : :
916 : : /**
917 : : * Sets the label line \a settings, which contain settings related to how the label
918 : : * engine places and formats labels for line features (or polygon features which are labeled in
919 : : * a "perimeter" style mode).
920 : : * \see lineSettings()
921 : : * \since QGIS 3.16
922 : : */
923 : : void setLineSettings( const QgsLabelLineSettings &settings ) { mLineSettings = settings; }
924 : :
925 : : /**
926 : : * Returns the label obstacle settings.
927 : : * \see setObstacleSettings()
928 : : * \note Not available in Python bindings
929 : : * \since QGIS 3.10.2
930 : : */
931 : : const QgsLabelObstacleSettings &obstacleSettings() const { return mObstacleSettings; } SIP_SKIP
932 : :
933 : : /**
934 : : * Returns the label obstacle settings.
935 : : * \see setObstacleSettings()
936 : : * \since QGIS 3.10.2
937 : : */
938 : 0 : QgsLabelObstacleSettings &obstacleSettings() { return mObstacleSettings; }
939 : :
940 : : /**
941 : : * Sets the label obstacle \a settings.
942 : : * \see obstacleSettings()
943 : : * \since QGIS 3.10.2
944 : : */
945 : : void setObstacleSettings( const QgsLabelObstacleSettings &settings ) { mObstacleSettings = settings; }
946 : :
947 : : /**
948 : : * Returns the label thinning settings.
949 : : * \see setThinningSettings()
950 : : * \note Not available in Python bindings
951 : : * \since QGIS 3.12
952 : : */
953 : : const QgsLabelThinningSettings &thinningSettings() const { return mThinningSettings; } SIP_SKIP
954 : :
955 : : /**
956 : : * Returns the label thinning settings.
957 : : * \see setThinningSettings()
958 : : * \since QGIS 3.12
959 : : */
960 : : QgsLabelThinningSettings &thinningSettings() { return mThinningSettings; }
961 : :
962 : : /**
963 : : * Sets the label thinning \a settings.
964 : : * \see thinningSettings()
965 : : * \since QGIS 3.12
966 : : */
967 : : void setThinningSettings( const QgsLabelThinningSettings &settings ) { mThinningSettings = settings; }
968 : :
969 : : /**
970 : : * Returns a pixmap preview for label \a settings.
971 : : * \param settings label settings
972 : : * \param size target pixmap size
973 : : * \param previewText text to render in preview, or empty for default text
974 : : * \param padding space between icon edge and color ramp
975 : : * \since QGIS 3.10
976 : : */
977 : : static QPixmap labelSettingsPreviewPixmap( const QgsPalLayerSettings &settings, QSize size, const QString &previewText = QString(), int padding = 0 );
978 : :
979 : : // temporary stuff: set when layer gets prepared or labeled
980 : : const QgsFeature *mCurFeat = nullptr;
981 : : QgsFields mCurFields;
982 : : int fieldIndex = 0;
983 : : const QgsMapToPixel *xform = nullptr;
984 : : QgsCoordinateTransform ct;
985 : :
986 : : QgsPointXY ptZero;
987 : : QgsPointXY ptOne;
988 : : QgsGeometry extentGeom;
989 : : int mFeaturesToLabel = 0; // total features that will probably be labeled, may be less (figured before PAL)
990 : : int mFeatsSendingToPal = 0; // total features tested for sending into PAL (relative to maxNumLabels)
991 : : int mFeatsRegPal = 0; // number of features registered in PAL, when using limitNumLabels
992 : : private:
993 : :
994 : : friend class QgsVectorLayer; // to allow calling readFromLayerCustomProperties()
995 : :
996 : : /**
997 : : * Reads labeling configuration from layer's custom properties to support loading of simple labeling from QGIS 2.x projects.
998 : : * \since QGIS 3.0
999 : : */
1000 : : void readFromLayerCustomProperties( QgsVectorLayer *layer );
1001 : :
1002 : : /**
1003 : : * Reads data defined properties from a QGIS 2.x project.
1004 : : */
1005 : : void readOldDataDefinedPropertyMap( QgsVectorLayer *layer, QDomElement *parentElem );
1006 : :
1007 : : /**
1008 : : * Reads a data defined property from a QGIS 2.x project.
1009 : : */
1010 : : void readOldDataDefinedProperty( QgsVectorLayer *layer, QgsPalLayerSettings::Property p );
1011 : :
1012 : : enum DataDefinedValueType
1013 : : {
1014 : : DDBool,
1015 : : DDInt,
1016 : : DDIntPos,
1017 : : DDDouble,
1018 : : DDDoublePos,
1019 : : DDRotation180,
1020 : : DDOpacity, //!< Data defined opacity (double between 0 and 100)
1021 : : DDString,
1022 : : DDUnits,
1023 : : DDColor,
1024 : : DDJoinStyle,
1025 : : DDBlendMode,
1026 : : DDPointF,
1027 : : DDSizeF, //!< Data defined size
1028 : : };
1029 : :
1030 : : // convenience data defined evaluation function
1031 : : bool dataDefinedValEval( DataDefinedValueType valType,
1032 : : QgsPalLayerSettings::Property p,
1033 : : QVariant &exprVal, QgsExpressionContext &context, const QVariant &originalValue = QVariant() );
1034 : :
1035 : : void parseTextStyle( QFont &labelFont,
1036 : : QgsUnitTypes::RenderUnit fontunits,
1037 : : QgsRenderContext &context );
1038 : :
1039 : : void parseTextBuffer( QgsRenderContext &context );
1040 : :
1041 : : void parseTextMask( QgsRenderContext &context );
1042 : :
1043 : : void parseTextFormatting( QgsRenderContext &context );
1044 : :
1045 : : void parseShapeBackground( QgsRenderContext &context );
1046 : :
1047 : : void parseDropShadow( QgsRenderContext &context );
1048 : :
1049 : : /**
1050 : : * Checks if a feature is larger than a minimum size (in mm)
1051 : : * \returns TRUE if above size, FALSE if below
1052 : : */
1053 : : bool checkMinimumSizeMM( const QgsRenderContext &ct, const QgsGeometry &geom, double minSize ) const;
1054 : :
1055 : : /**
1056 : : * Registers a feature as an obstacle only (no label rendered)
1057 : : */
1058 : : void registerObstacleFeature( const QgsFeature &f, QgsRenderContext &context, QgsLabelFeature **obstacleFeature, const QgsGeometry &obstacleGeometry = QgsGeometry() );
1059 : :
1060 : : QMap<Property, QVariant> dataDefinedValues;
1061 : :
1062 : : //! Property collection for data defined label settings
1063 : : QgsPropertyCollection mDataDefinedProperties;
1064 : :
1065 : : QgsExpression *expression = nullptr;
1066 : :
1067 : : QFontDatabase mFontDB;
1068 : :
1069 : : QgsTextFormat mFormat;
1070 : :
1071 : : std::unique_ptr< QgsCallout > mCallout;
1072 : :
1073 : : QgsLabelLineSettings mLineSettings;
1074 : : QgsLabelObstacleSettings mObstacleSettings;
1075 : : QgsLabelThinningSettings mThinningSettings;
1076 : :
1077 : : QgsLabeling::PolygonPlacementFlags mPolygonPlacementFlags = QgsLabeling::PolygonPlacementFlag::AllowPlacementInsideOfPolygon;
1078 : :
1079 : : QgsExpression mGeometryGeneratorExpression;
1080 : :
1081 : : bool mRenderStarted = false;
1082 : :
1083 : : static void initPropertyDefinitions();
1084 : : };
1085 : :
1086 : : /**
1087 : : * \ingroup core
1088 : : * \brief Represents a label candidate.
1089 : : */
1090 : : class CORE_EXPORT QgsLabelCandidate
1091 : : {
1092 : : public:
1093 : 0 : QgsLabelCandidate( const QRectF &r, double c ): rect( r ), cost( c ) {}
1094 : :
1095 : : QRectF rect;
1096 : : double cost;
1097 : : };
1098 : :
1099 : : /**
1100 : : * \ingroup core
1101 : : * \class QgsPalLabeling
1102 : : * \brief PAL labeling utilities.
1103 : : */
1104 : : class CORE_EXPORT QgsPalLabeling
1105 : : {
1106 : : public:
1107 : :
1108 : : /**
1109 : : * Called to find out whether a specified \a layer is used for labeling.
1110 : : * \since QGIS 2.4
1111 : : */
1112 : : static bool staticWillUseLayer( const QgsMapLayer *layer );
1113 : :
1114 : : //! \note not available in Python bindings
1115 : : static void drawLabelCandidateRect( pal::LabelPosition *lp, QPainter *painter, const QgsMapToPixel *xform, QList<QgsLabelCandidate> *candidates = nullptr ) SIP_SKIP;
1116 : :
1117 : : /**
1118 : : * Prepares a geometry for registration with PAL. Handles reprojection, rotation, clipping, etc.
1119 : : * \param geometry geometry to prepare
1120 : : * \param context render context
1121 : : * \param ct coordinate transform, or invalid transform if no transformation required
1122 : : * \param clipGeometry geometry to clip features to, if applicable
1123 : : * \param mergeLines TRUE if touching lines from this layer will be merged and treated as single features during labeling
1124 : : * \returns prepared geometry
1125 : : * \since QGIS 2.9
1126 : : */
1127 : : static QgsGeometry prepareGeometry( const QgsGeometry &geometry, QgsRenderContext &context, const QgsCoordinateTransform &ct, const QgsGeometry &clipGeometry = QgsGeometry(), bool mergeLines = false ) SIP_FACTORY;
1128 : :
1129 : : /**
1130 : : * Checks whether a geometry requires preparation before registration with PAL
1131 : : * \param geometry geometry to prepare
1132 : : * \param context render context
1133 : : * \param ct coordinate transform, or invalid transform if no transformation required
1134 : : * \param clipGeometry geometry to clip features to, if applicable
1135 : : * \param mergeLines TRUE if touching lines from this layer will be merged and treated as single features during labeling
1136 : : * \returns TRUE if geometry requires preparation
1137 : : * \since QGIS 2.9
1138 : : */
1139 : : static bool geometryRequiresPreparation( const QgsGeometry &geometry, QgsRenderContext &context, const QgsCoordinateTransform &ct, const QgsGeometry &clipGeometry = QgsGeometry(), bool mergeLines = false );
1140 : :
1141 : : /**
1142 : : * Splits a \a text string to a list of separate lines, using a specified wrap character (\a wrapCharacter).
1143 : : * The text string will be split on either newline characters or the wrap character.
1144 : : *
1145 : : * Since QGIS 3.4 the \a autoWrapLength argument can be used to specify an ideal length of line to automatically
1146 : : * wrap text to (automatic wrapping is disabled if \a autoWrapLength is 0). This automatic wrapping is performed
1147 : : * after processing wrapping using \a wrapCharacter. When auto wrapping is enabled, the \a useMaxLineLengthWhenAutoWrapping
1148 : : * argument controls whether the lines should be wrapped to an ideal maximum of \a autoWrapLength characters, or
1149 : : * if FALSE then the lines are wrapped to an ideal minimum length of \a autoWrapLength characters.
1150 : : *
1151 : : * \since QGIS 2.9
1152 : : */
1153 : : static QStringList splitToLines( const QString &text, const QString &wrapCharacter, int autoWrapLength = 0, bool useMaxLineLengthWhenAutoWrapping = true );
1154 : :
1155 : : /**
1156 : : * Splits a text string to a list of graphemes, which are the smallest allowable character
1157 : : * divisions in the string. This accounts for scripts were individual characters are not
1158 : : * allowed to be split apart (e.g., Arabic and Indic based scripts)
1159 : : * \param text string to split
1160 : : * \returns list of graphemes
1161 : : * \since QGIS 2.10
1162 : : */
1163 : : static QStringList splitToGraphemes( const QString &text );
1164 : :
1165 : : private:
1166 : : //! Update temporary QgsPalLayerSettings with any data defined text style values
1167 : : static void dataDefinedTextStyle( QgsPalLayerSettings &tmpLyr,
1168 : : const QMap< QgsPalLayerSettings::Property, QVariant > &ddValues );
1169 : :
1170 : : //! Update temporary QgsPalLayerSettings with any data defined text formatting values
1171 : : static void dataDefinedTextFormatting( QgsPalLayerSettings &tmpLyr,
1172 : : const QMap< QgsPalLayerSettings::Property, QVariant > &ddValues );
1173 : :
1174 : : //! Update temporary QgsPalLayerSettings with any data defined text buffer values
1175 : : static void dataDefinedTextBuffer( QgsPalLayerSettings &tmpLyr,
1176 : : const QMap< QgsPalLayerSettings::Property, QVariant > &ddValues );
1177 : :
1178 : : //! Update temporary QgsPalLayerSettings with any data defined mask values
1179 : : static void dataDefinedTextMask( QgsPalLayerSettings &tmpLyr,
1180 : : const QMap< QgsPalLayerSettings::Property, QVariant > &ddValues );
1181 : :
1182 : : //! Update temporary QgsPalLayerSettings with any data defined shape background values
1183 : : static void dataDefinedShapeBackground( QgsPalLayerSettings &tmpLyr,
1184 : : const QMap< QgsPalLayerSettings::Property, QVariant > &ddValues );
1185 : :
1186 : : //! Update temporary QgsPalLayerSettings with any data defined drop shadow values
1187 : : static void dataDefinedDropShadow( QgsPalLayerSettings &tmpLyr,
1188 : : const QMap< QgsPalLayerSettings::Property, QVariant > &ddValues );
1189 : :
1190 : : friend class QgsVectorLayerLabelProvider; // to allow calling the static methods above
1191 : : friend class QgsDxfExport; // to allow calling the static methods above
1192 : :
1193 : : /**
1194 : : * Checks whether a geometry exceeds the minimum required size for a geometry to be labeled.
1195 : : * \param context render context
1196 : : * \param geom geometry
1197 : : * \param minSize minimum size for geometry
1198 : : * \returns TRUE if geometry exceeds minimum size
1199 : : * \since QGIS 2.9
1200 : : */
1201 : : static bool checkMinimumSizeMM( const QgsRenderContext &context, const QgsGeometry &geom, double minSize );
1202 : :
1203 : : friend class QgsPalLayerSettings;
1204 : : };
1205 : :
1206 : :
1207 : : #endif // QGSPALLABELING_H
|
