QGIS API Documentation 3.99.0-Master (9e5f463f1a9)
qgstextrenderer.h
Go to the documentation of this file.
1/***************************************************************************
2 qgstextrenderer.h
3 -----------------
4 begin : September 2015
5 copyright : (C) Nyall Dawson
6 email : nyall dot dawson at gmail dot com
7 ***************************************************************************
8 * *
9 * This program is free software; you can redistribute it and/or modify *
10 * it under the terms of the GNU General Public License as published by *
11 * the Free Software Foundation; either version 2 of the License, or *
12 * (at your option) any later version. *
13 * *
14 ***************************************************************************/
15
16#ifndef QGSTEXTRENDERER_H
17#define QGSTEXTRENDERER_H
18
19#include "qgis_sip.h"
20#include "qgis_core.h"
21#include "qgstextblock.h"
22#include "qgsmapunitscale.h"
23#include "qgis.h"
24
25#include <QPicture>
26#include <QPainterPath>
27
28class QgsTextDocument;
29class QgsTextDocumentMetrics;
30class QgsTextFormat;
31class QgsRenderContext;
32
33class QFontMetricsF;
34
41class CORE_EXPORT QgsTextRenderer
42{
43 public:
44
51 static Qgis::TextHorizontalAlignment convertQtHAlignment( Qt::Alignment alignment );
52
59 static Qgis::TextVerticalAlignment convertQtVAlignment( Qt::Alignment alignment );
60
69 static int sizeToPixel( double size, const QgsRenderContext &c, Qgis::RenderUnit unit, const QgsMapUnitScale &mapUnitScale = QgsMapUnitScale() );
70
71 // TODO QGIS 4.0 -- remove drawAsOutlines from below methods!
72
91 static void drawText( const QRectF &rect, double rotation, Qgis::TextHorizontalAlignment alignment, const QStringList &textLines,
92 QgsRenderContext &context, const QgsTextFormat &format,
93 bool drawAsOutlines = true, Qgis::TextVerticalAlignment vAlignment = Qgis::TextVerticalAlignment::Top,
94 Qgis::TextRendererFlags flags = Qgis::TextRendererFlags(),
95 Qgis::TextLayoutMode mode = Qgis::TextLayoutMode::Rectangle );
96
119 static void drawDocument( const QRectF &rect,
120 const QgsTextFormat &format,
121 const QgsTextDocument &document,
122 const QgsTextDocumentMetrics &metrics,
123 QgsRenderContext &context,
124 Qgis::TextHorizontalAlignment horizontalAlignment = Qgis::TextHorizontalAlignment::Left,
125 Qgis::TextVerticalAlignment verticalAlignment = Qgis::TextVerticalAlignment::Top,
126 double rotation = 0,
127 Qgis::TextLayoutMode mode = Qgis::TextLayoutMode::Rectangle,
128 Qgis::TextRendererFlags flags = Qgis::TextRendererFlags() );
129
143 static void drawText( QPointF point, double rotation, Qgis::TextHorizontalAlignment alignment, const QStringList &textLines,
144 QgsRenderContext &context, const QgsTextFormat &format,
145 bool drawAsOutlines = true );
146
167 static void drawDocument( QPointF point,
168 const QgsTextFormat &format,
169 const QgsTextDocument &document,
170 const QgsTextDocumentMetrics &metrics,
171 QgsRenderContext &context,
172 Qgis::TextHorizontalAlignment alignment,
173 double rotation,
174 Qgis::TextLayoutMode mode = Qgis::TextLayoutMode::Point );
175
188 static void drawTextOnLine( const QPolygonF &line, const QString &text,
189 QgsRenderContext &context, const QgsTextFormat &format,
190 double offsetAlongLine = 0, double offsetFromLine = 0 );
191
204 static void drawDocumentOnLine( const QPolygonF &line,
205 const QgsTextFormat &format,
206 const QgsTextDocument &document,
207 QgsRenderContext &context,
208 double offsetAlongLine = 0,
209 double offsetFromLine = 0 );
210
229 Q_DECL_DEPRECATED static void drawPart( const QRectF &rect, double rotation, Qgis::TextHorizontalAlignment alignment, const QStringList &textLines,
230 QgsRenderContext &context, const QgsTextFormat &format,
231 Qgis::TextComponent part, bool drawAsOutlines = true ) SIP_DEPRECATED;
232
251 Q_DECL_DEPRECATED static void drawPart( QPointF origin, double rotation, Qgis::TextHorizontalAlignment alignment, const QStringList &textLines,
252 QgsRenderContext &context, const QgsTextFormat &format,
253 Qgis::TextComponent part, bool drawAsOutlines = true ) SIP_DEPRECATED;
254
267 static QFontMetricsF fontMetrics( QgsRenderContext &context, const QgsTextFormat &format, double scaleFactor = 1.0 );
268
276 static double textWidth( const QgsRenderContext &context, const QgsTextFormat &format, const QStringList &textLines,
277 QFontMetricsF *fontMetrics = nullptr );
278
289 static double textHeight( const QgsRenderContext &context, const QgsTextFormat &format, const QStringList &textLines, Qgis::TextLayoutMode mode = Qgis::TextLayoutMode::Point,
290 QFontMetricsF *fontMetrics = nullptr, Qgis::TextRendererFlags flags = Qgis::TextRendererFlags(), double maxLineWidth = 0 );
291
303 static double textHeight( const QgsRenderContext &context, const QgsTextFormat &format, QChar character, bool includeEffects = false );
304
311 static bool textRequiresWrapping( const QgsRenderContext &context, const QString &text, double width, const QgsTextFormat &format );
312
319 static QStringList wrappedText( const QgsRenderContext &context, const QString &text, double width, const QgsTextFormat &format );
320
331 static constexpr double FONT_WORKAROUND_SCALE = 10;
332
341 static double calculateScaleFactorForFormat( const QgsRenderContext &context, const QgsTextFormat &format );
342
343 // to match QTextEngine handling of superscript/subscript font sizes
344
350 static constexpr double SUPERSCRIPT_SUBSCRIPT_FONT_SIZE_SCALING_FACTOR = 2.0 / 3.0;
351
352 private:
353
354 struct Component
355 {
357 QgsTextBlock block;
358
360 int blockIndex = 0;
361
363 int firstFragmentIndex = 0;
364
366 QPointF origin;
368 bool useOrigin = false;
370 double rotation = 0.0;
372 double rotationOffset = 0.0;
374 QPointF center;
376 QSizeF size;
378 QPointF offset;
380 QPicture picture;
381
386 double pictureBuffer = 0.0;
388 double dpiRatio = 1.0;
390 Qgis::TextHorizontalAlignment hAlign = Qgis::TextHorizontalAlignment::Left;
391
393 double extraWordSpacing = 0;
395 double extraLetterSpacing = 0;
396 };
397
398 static double textWidth( const QgsRenderContext &context, const QgsTextFormat &format, const QgsTextDocument &document );
399 static double textHeight( const QgsRenderContext &context, const QgsTextFormat &format, const QgsTextDocument &document, Qgis::TextLayoutMode mode = Qgis::TextLayoutMode::Point );
400
418 static void drawParts( const QRectF &rect, double rotation, Qgis::TextHorizontalAlignment alignment, Qgis::TextVerticalAlignment vAlignment, const QgsTextDocument &document, const QgsTextDocumentMetrics &metrics,
419 QgsRenderContext &context, const QgsTextFormat &format,
420 Qgis::TextComponents parts, Qgis::TextLayoutMode mode );
421
438 static void drawParts( QPointF origin, double rotation, Qgis::TextHorizontalAlignment alignment, const QgsTextDocument &document,
439 const QgsTextDocumentMetrics &metrics,
440 QgsRenderContext &context, const QgsTextFormat &format,
441 Qgis::TextComponents parts,
442 Qgis::TextLayoutMode mode );
443
444 static double drawBuffer( QgsRenderContext &context,
445 const Component &component,
446 const QgsTextFormat &format,
447 const QgsTextDocumentMetrics &metrics,
448 Qgis::TextLayoutMode mode );
449
450 static void drawBackground( QgsRenderContext &context,
451 const Component &component,
452 const QgsTextFormat &format,
453 const QgsTextDocumentMetrics &metrics,
454 Qgis::TextLayoutMode mode = Qgis::TextLayoutMode::Rectangle );
455
456 static void drawShadow( QgsRenderContext &context,
457 const Component &component,
458 const QgsTextFormat &format );
459
460 static void drawMask( QgsRenderContext &context,
461 const Component &component,
462 const QgsTextFormat &format,
463 const QgsTextDocumentMetrics &metrics,
464 Qgis::TextLayoutMode mode );
465
466 static void drawText( QgsRenderContext &context,
467 const Component &component,
468 const QgsTextFormat &format );
469
470 static void drawTextInternal( Qgis::TextComponents components,
471 QgsRenderContext &context,
472 const QgsTextFormat &format,
473 const Component &component,
474 const QgsTextDocument &document,
475 const QgsTextDocumentMetrics &metrics,
476 Qgis::TextHorizontalAlignment alignment,
477 Qgis::TextVerticalAlignment vAlignment,
478 Qgis::TextLayoutMode mode = Qgis::TextLayoutMode::Rectangle );
479
480 static Qgis::TextOrientation calculateRotationAndOrientationForComponent( const QgsTextFormat &format, const Component &component, double &rotation );
481
482 static void calculateExtraSpacingForLineJustification( double spaceToDistribute, const QgsTextBlock &block, double &extraWordSpace, double &extraLetterSpace );
483 static void applyExtraSpacingForLineJustification( QFont &font, double extraWordSpace, double extraLetterSpace );
484
485 static void drawTextInternalHorizontal( QgsRenderContext &context,
486 const QgsTextFormat &format,
487 Qgis::TextComponents components,
488 Qgis::TextLayoutMode mode,
489 const Component &component,
490 const QgsTextDocument &document,
491 const QgsTextDocumentMetrics &metrics,
492 double fontScale,
493 Qgis::TextHorizontalAlignment hAlignment,
494 Qgis::TextVerticalAlignment vAlignment,
495 double rotation );
496
497 static void drawTextInternalVertical( QgsRenderContext &context,
498 const QgsTextFormat &format,
499 Qgis::TextComponents components,
500 Qgis::TextLayoutMode mode,
501 const Component &component,
502 const QgsTextDocument &document,
503 const QgsTextDocumentMetrics &metrics,
504 double fontScale,
505 Qgis::TextHorizontalAlignment hAlignment,
506 Qgis::TextVerticalAlignment vAlignment,
507 double rotation );
508
509 struct DeferredRenderFragment
510 {
511 // mandatory
512 QColor color;
513 QPointF point;
514 // optional
515 QPainterPath path;
516 // optional
517 QFont font;
518 QString text;
519 };
520
521 struct BlockMetrics
522 {
523 double xOffset = 0;
524 double backgroundXOffset = 0;
525 double width = 0;
526 double backgroundWidth = 0;
527 double extraWordSpace = 0;
528 double extraLetterSpace = 0;
529 };
530
531 static QVector< QgsTextRenderer::BlockMetrics > calculateBlockMetrics( const QgsTextDocument &document, const QgsTextDocumentMetrics &metrics, Qgis::TextLayoutMode mode, double targetWidth, const Qgis::TextHorizontalAlignment hAlignment );
532
533 struct DeferredRenderBlock
534 {
535 QPointF origin;
536 Component component;
537 QVector< DeferredRenderFragment > fragments;
538 };
539
540 static QBrush createBrushForPath( QgsRenderContext &context, const QString &path );
541
542 static void renderBlockHorizontal( const QgsTextBlock &block, int blockIndex,
543 const QgsTextDocumentMetrics &metrics, QgsRenderContext &context,
544 const QgsTextFormat &format,
545 QPainter *painter, bool forceRenderAsPaths,
546 double fontScale, double extraWordSpace, double extraLetterSpace,
547 Qgis::TextLayoutMode mode,
548 DeferredRenderBlock *deferredRenderBlock );
549 static void renderDocumentBackgrounds( QgsRenderContext &context, const QgsTextDocument &document, const QgsTextDocumentMetrics &metrics, const Component &component, const QVector< QgsTextRenderer::BlockMetrics > &blockMetrics, Qgis::TextLayoutMode mode, double verticalAlignOffset, double rotation );
550 static void renderDeferredBlocks( QgsRenderContext &context, const QgsTextFormat &format, Qgis::TextComponents components, const std::vector<DeferredRenderBlock> &deferredBlocks, bool usePathsForText, double fontScale, const Component &component, double rotation );
551 static void renderDeferredBuffer( QgsRenderContext &context, const QgsTextFormat &format, Qgis::TextComponents components, const std::vector<DeferredRenderBlock> &deferredBlocks, double fontScale, const Component &component, double rotation );
552 static void renderDeferredShadowForText( QgsRenderContext &context, const QgsTextFormat &format, const std::vector<DeferredRenderBlock> &deferredBlocks, double fontScale, const Component &component, double rotation );
553 static void renderDeferredText( QgsRenderContext &context, const std::vector<DeferredRenderBlock> &deferredBlocks, bool usePathsForText, double fontScale, const Component &component, double rotation );
554
555 friend class QgsVectorLayerLabelProvider;
556 friend class QgsLabelPreview;
557
558 static QgsTextFormat updateShadowPosition( const QgsTextFormat &format );
559
563 static bool usePathsToRender( const QgsRenderContext &context, const QgsTextFormat &format, const QgsTextDocument &document );
564
568 static bool usePictureToRender( const QgsRenderContext &context, const QgsTextFormat &format, const QgsTextDocument &document );
569
570};
571
572#endif // QGSTEXTRENDERER_H
Qgis::TextLayoutMode
TextLayoutMode
Text layout modes.
Definition qgis.h:2851
Qgis::TextLayoutMode::Point
@ Point
Text at point of origin layout mode.
Qgis::TextLayoutMode::Rectangle
@ Rectangle
Text within rectangle layout mode.
Qgis::TextRendererFlags
QFlags< TextRendererFlag > TextRendererFlags
Definition qgis.h:3314
Qgis::TextOrientation
TextOrientation
Text orientations.
Definition qgis.h:2836
Qgis::RenderUnit
RenderUnit
Rendering size units.
Definition qgis.h:5064
Qgis::TextVerticalAlignment
TextVerticalAlignment
Text vertical alignment.
Definition qgis.h:2911
Qgis::TextComponents
QFlags< TextComponent > TextComponents
Text components.
Definition qgis.h:2881
Qgis::TextHorizontalAlignment
TextHorizontalAlignment
Text horizontal alignment.
Definition qgis.h:2892
Qgis::TextComponent
TextComponent
Text components.
Definition qgis.h:2868
QgsMapUnitScale
Struct for storing maximum and minimum scales for measurements in map units.
Definition qgsmapunitscale.h:37
QgsRenderContext
Contains information about the context of a rendering operation.
Definition qgsrendercontext.h:62
QgsTextBlock
Represents a block of text consisting of one or more QgsTextFragment objects.
Definition qgstextblock.h:37
QgsTextDocumentMetrics
Contains pre-calculated metrics of a QgsTextDocument.
Definition qgstextdocumentmetrics.h:97
QgsTextDocument
Represents a document consisting of one or more QgsTextBlock objects.
Definition qgstextdocument.h:41
QgsTextFormat
Container for all settings relating to text rendering.
Definition qgstextformat.h:41
QgsTextRenderer
Handles rendering text using rich formatting options, including drop shadows, buffers and background ...
Definition qgstextrenderer.h:42
QgsVectorLayerLabelProvider
Implements a label provider for vector layers.
Definition qgsvectorlayerlabelprovider.h:41
c
As part of the API refactoring and improvements which landed in the Processing API was substantially reworked from the x version This was done in order to allow much of the underlying Processing framework to be ported into c
Definition porting_processing.dox:1
qgis_sip.h
SIP_DEPRECATED
#define SIP_DEPRECATED
Definition qgis_sip.h:114
FONT_WORKAROUND_SCALE
#define FONT_WORKAROUND_SCALE
Definition qgslegendsettings.cpp:200
Generated on Sun Jul 13 2025 13:27:20 for QGIS API Documentation by doxygen 1.9.8