QGIS API Documentation 3.29.0-Master (006c3c0232)
Classes | Static Public Member Functions | Static Public Attributes | Friends | List of all members
QgsTextRenderer Class Reference

Handles rendering text using rich formatting options, including drop shadows, buffers and background shapes. More...

#include <qgstextrenderer.h>

Static Public Member Functions

static Qgis::TextHorizontalAlignment convertQtHAlignment (Qt::Alignment alignment)
 Converts a Qt horizontal alignment flag to a Qgis::TextHorizontalAlignment value. More...
 
static Qgis::TextVerticalAlignment convertQtVAlignment (Qt::Alignment alignment)
 Converts a Qt vertical alignment flag to a Qgis::TextVerticalAlignment value. More...
 
static void drawDocument (const QRectF &rect, const QgsTextFormat &format, const QgsTextDocument &document, const QgsTextDocumentMetrics &metrics, QgsRenderContext &context, Qgis::TextHorizontalAlignment horizontalAlignment=Qgis::TextHorizontalAlignment::Left, Qgis::TextVerticalAlignment verticalAlignment=Qgis::TextVerticalAlignment::Top, double rotation=0, Qgis::TextLayoutMode mode=Qgis::TextLayoutMode::Rectangle, Qgis::TextRendererFlags flags=Qgis::TextRendererFlags())
 Draws a text document within a rectangle using the specified settings. More...
 
static Q_DECL_DEPRECATED void drawPart (const QRectF &rect, double rotation, Qgis::TextHorizontalAlignment alignment, const QStringList &textLines, QgsRenderContext &context, const QgsTextFormat &format, Qgis::TextComponent part, bool drawAsOutlines=true)
 Draws a single component of rendered text using the specified settings. More...
 
static Q_DECL_DEPRECATED void drawPart (QPointF origin, double rotation, Qgis::TextHorizontalAlignment alignment, const QStringList &textLines, QgsRenderContext &context, const QgsTextFormat &format, Qgis::TextComponent part, bool drawAsOutlines=true)
 Draws a single component of rendered text using the specified settings. More...
 
static void drawText (const QRectF &rect, double rotation, Qgis::TextHorizontalAlignment alignment, const QStringList &textLines, QgsRenderContext &context, const QgsTextFormat &format, bool drawAsOutlines=true, Qgis::TextVerticalAlignment vAlignment=Qgis::TextVerticalAlignment::Top, Qgis::TextRendererFlags flags=Qgis::TextRendererFlags(), Qgis::TextLayoutMode mode=Qgis::TextLayoutMode::Rectangle)
 Draws text within a rectangle using the specified settings. More...
 
static void drawText (QPointF point, double rotation, Qgis::TextHorizontalAlignment alignment, const QStringList &textLines, QgsRenderContext &context, const QgsTextFormat &format, bool drawAsOutlines=true)
 Draws text at a point origin using the specified settings. More...
 
static QFontMetricsF fontMetrics (QgsRenderContext &context, const QgsTextFormat &format, double scaleFactor=1.0)
 Returns the font metrics for the given text format, when rendered in the specified render context. More...
 
static int sizeToPixel (double size, const QgsRenderContext &c, QgsUnitTypes::RenderUnit unit, const QgsMapUnitScale &mapUnitScale=QgsMapUnitScale())
 Calculates pixel size (considering output size should be in pixel or map units, scale factors and optionally oversampling) More...
 
static double textHeight (const QgsRenderContext &context, const QgsTextFormat &format, const QStringList &textLines, Qgis::TextLayoutMode mode=Qgis::TextLayoutMode::Point, QFontMetricsF *fontMetrics=nullptr, Qgis::TextRendererFlags flags=Qgis::TextRendererFlags(), double maxLineWidth=0)
 Returns the height of a text based on a given format. More...
 
static double textHeight (const QgsRenderContext &context, const QgsTextFormat &format, QChar character, bool includeEffects=false)
 Returns the height of a character when rendered with the specified text format. More...
 
static bool textRequiresWrapping (const QgsRenderContext &context, const QString &text, double width, const QgsTextFormat &format)
 Returns true if the specified text requires line wrapping in order to fit within the specified width (in painter units). More...
 
static double textWidth (const QgsRenderContext &context, const QgsTextFormat &format, const QStringList &textLines, QFontMetricsF *fontMetrics=nullptr)
 Returns the width of a text based on a given format. More...
 
static QStringList wrappedText (const QgsRenderContext &context, const QString &text, double width, const QgsTextFormat &format)
 Wraps a text string to multiple lines, such that each individual line will fit within the specified width (in painter units). More...
 

Static Public Attributes

static constexpr double FONT_WORKAROUND_SCALE = 10
 Scale factor for upscaling font sizes and downscaling destination painter devices. More...
 

Friends

class QgsLabelPreview
 
class QgsVectorLayerLabelProvider
 

Detailed Description

Handles rendering text using rich formatting options, including drop shadows, buffers and background shapes.

Since
QGIS 3.0

Definition at line 42 of file qgstextrenderer.h.

Member Function Documentation

◆ convertQtHAlignment()

Qgis::TextHorizontalAlignment QgsTextRenderer::convertQtHAlignment ( Qt::Alignment  alignment)
static

Converts a Qt horizontal alignment flag to a Qgis::TextHorizontalAlignment value.

See also
convertQtVAlignment()
Since
QGIS 3.16

Definition at line 46 of file qgstextrenderer.cpp.

◆ convertQtVAlignment()

Qgis::TextVerticalAlignment QgsTextRenderer::convertQtVAlignment ( Qt::Alignment  alignment)
static

Converts a Qt vertical alignment flag to a Qgis::TextVerticalAlignment value.

See also
convertQtHAlignment()
Since
QGIS 3.16

Definition at line 61 of file qgstextrenderer.cpp.

◆ drawDocument()

void QgsTextRenderer::drawDocument ( const QRectF &  rect,
const QgsTextFormat format,
const QgsTextDocument document,
const QgsTextDocumentMetrics metrics,
QgsRenderContext context,
Qgis::TextHorizontalAlignment  horizontalAlignment = Qgis::TextHorizontalAlignment::Left,
Qgis::TextVerticalAlignment  verticalAlignment = Qgis::TextVerticalAlignment::Top,
double  rotation = 0,
Qgis::TextLayoutMode  mode = Qgis::TextLayoutMode::Rectangle,
Qgis::TextRendererFlags  flags = Qgis::TextRendererFlags() 
)
static

Draws a text document within a rectangle using the specified settings.

Calling this method is more efficient than calling drawText() if the text document and metrics have already been calculated.

Warning
Unlike drawText(), this method does not automatically update data defined properties in the text format. This is the caller's responsibility to do, and must be done prior to generating the text document and metrics.
Parameters
rectdestination rectangle for text
formatbase text format
documenttext document to draw
metricsprecalculated text metrics
contextdestination render context
horizontalAlignmenthorizontal alignment
verticalAlignmentvertical alignment
rotationtext rotation
modetext layout mode. Only Qgis::TextLayoutMode::Rectangle, Qgis::TextLayoutMode::RectangleCapHeightBased and Qgis::TextLayoutMode::RectangleAscentBased are accepted.
flagstext rendering flags
Since
QGIS 3.30

Definition at line 110 of file qgstextrenderer.cpp.

◆ drawPart() [1/2]

void QgsTextRenderer::drawPart ( const QRectF &  rect,
double  rotation,
Qgis::TextHorizontalAlignment  alignment,
const QStringList &  textLines,
QgsRenderContext context,
const QgsTextFormat format,
Qgis::TextComponent  part,
bool  drawAsOutlines = true 
)
static

Draws a single component of rendered text using the specified settings.

Parameters
rectdestination rectangle for text
rotationtext rotation
alignmenthorizontal alignment
textLineslist of lines of text to draw
contextrender context
formattext format
partcomponent of text to draw. Note that Shadow parts cannot be drawn individually and instead are drawn with their associated part (e.g., drawn together with the text or background parts)
drawAsOutlinesset to false to render text as text. This allows outputs to formats like SVG to maintain text as text objects, but at the cost of degraded rendering and may result in side effects like misaligned text buffers. This setting is deprecated and has no effect as of QGIS 3.4.3 and the text format should be set using QgsRenderContext::setTextRenderFormat() instead.
Deprecated:
Private API only, will be removed in 4.0

Definition at line 173 of file qgstextrenderer.cpp.

◆ drawPart() [2/2]

void QgsTextRenderer::drawPart ( QPointF  origin,
double  rotation,
Qgis::TextHorizontalAlignment  alignment,
const QStringList &  textLines,
QgsRenderContext context,
const QgsTextFormat format,
Qgis::TextComponent  part,
bool  drawAsOutlines = true 
)
static

Draws a single component of rendered text using the specified settings.

Parameters
originorigin for start of text. Y coordinate will be used as baseline.
rotationtext rotation
alignmenthorizontal alignment
textLineslist of lines of text to draw
contextrender context
formattext format
partcomponent of text to draw. Note that Shadow parts cannot be drawn individually and instead are drawn with their associated part (e.g., drawn together with the text or background parts)
drawAsOutlinesset to false to render text as text. This allows outputs to formats like SVG to maintain text as text objects, but at the cost of degraded rendering and may result in side effects like misaligned text buffers. This setting is deprecated and has no effect as of QGIS 3.4.3 and the text format should be set using QgsRenderContext::setTextRenderFormat() instead.
Deprecated:
Private API only, will be removed in 4.0

Definition at line 256 of file qgstextrenderer.cpp.

◆ drawText() [1/2]

void QgsTextRenderer::drawText ( const QRectF &  rect,
double  rotation,
Qgis::TextHorizontalAlignment  alignment,
const QStringList &  textLines,
QgsRenderContext context,
const QgsTextFormat format,
bool  drawAsOutlines = true,
Qgis::TextVerticalAlignment  vAlignment = Qgis::TextVerticalAlignment::Top,
Qgis::TextRendererFlags  flags = Qgis::TextRendererFlags(),
Qgis::TextLayoutMode  mode = Qgis::TextLayoutMode::Rectangle 
)
static

Draws text within a rectangle using the specified settings.

Parameters
rectdestination rectangle for text
rotationtext rotation
alignmenthorizontal alignment
textLineslist of lines of text to draw
contextrender context
formattext format
drawAsOutlinesset to false to render text as text. This allows outputs to formats like SVG to maintain text as text objects, but at the cost of degraded rendering and may result in side effects like misaligned text buffers. This setting is deprecated and has no effect as of QGIS 3.4.3 and the text format should be set using QgsRenderContext::setTextRenderFormat() instead.
vAlignmentvertical alignment (since QGIS 3.16)
flagstext rendering flags (since QGIS 3.24)
modetext layout mode. Only Qgis::TextLayoutMode::Rectangle, Qgis::TextLayoutMode::RectangleCapHeightBased and Qgis::TextLayoutMode::RectangleAscentBased are accepted (since QGIS 3.30)
See also
drawDocument(), which is more efficient if the text document and metrics have already been calculated.

Definition at line 81 of file qgstextrenderer.cpp.

◆ drawText() [2/2]

void QgsTextRenderer::drawText ( QPointF  point,
double  rotation,
Qgis::TextHorizontalAlignment  alignment,
const QStringList &  textLines,
QgsRenderContext context,
const QgsTextFormat format,
bool  drawAsOutlines = true 
)
static

Draws text at a point origin using the specified settings.

Parameters
pointorigin of text
rotationtext rotation
alignmenthorizontal alignment
textLineslist of lines of text to draw
contextrender context
formattext format
drawAsOutlinesset to false to render text as text. This allows outputs to formats like SVG to maintain text as text objects, but at the cost of degraded rendering and may result in side effects like misaligned text buffers. This setting is deprecated and has no effect as of QGIS 3.4.3 and the text format should be set using QgsRenderContext::setTextRenderFormat() instead.

Definition at line 127 of file qgstextrenderer.cpp.

◆ fontMetrics()

QFontMetricsF QgsTextRenderer::fontMetrics ( QgsRenderContext context,
const QgsTextFormat format,
double  scaleFactor = 1.0 
)
static

Returns the font metrics for the given text format, when rendered in the specified render context.

The font metrics will take into account all scaling required by the render context.

The optional scaleFactor argument can specify a font size scaling factor. It is recommended to set this to QgsTextRenderer::FONT_WORKAROUND_SCALE and then manually scale painter devices or calculations based on the resultant font metrics. Failure to do so will result in poor quality text rendering at small font sizes.

Since
QGIS 3.2

Definition at line 308 of file qgstextrenderer.cpp.

◆ sizeToPixel()

int QgsTextRenderer::sizeToPixel ( double  size,
const QgsRenderContext c,
QgsUnitTypes::RenderUnit  unit,
const QgsMapUnitScale mapUnitScale = QgsMapUnitScale() 
)
static

Calculates pixel size (considering output size should be in pixel or map units, scale factors and optionally oversampling)

Parameters
sizesize to convert
crendercontext
unitsize units
mapUnitScalea mapUnitScale clamper
Returns
font pixel size

Definition at line 76 of file qgstextrenderer.cpp.

◆ textHeight() [1/2]

double QgsTextRenderer::textHeight ( const QgsRenderContext context,
const QgsTextFormat format,
const QStringList &  textLines,
Qgis::TextLayoutMode  mode = Qgis::TextLayoutMode::Point,
QFontMetricsF *  fontMetrics = nullptr,
Qgis::TextRendererFlags  flags = Qgis::TextRendererFlags(),
double  maxLineWidth = 0 
)
static

Returns the height of a text based on a given format.

Parameters
contextrender context
formattext format
textLineslist of lines of text to calculate width from
modedraw mode
fontMetricsfont metrics
flagstext renderer flags (since QGIS 3.24)
maxLineWidthmaximum line width, in painter units. Used when the Qgis::TextRendererFlag::WrapLines flag is used (since QGIS 3.24)

Definition at line 617 of file qgstextrenderer.cpp.

◆ textHeight() [2/2]

double QgsTextRenderer::textHeight ( const QgsRenderContext context,
const QgsTextFormat format,
QChar  character,
bool  includeEffects = false 
)
static

Returns the height of a character when rendered with the specified text format.

Parameters
contextrender context
formattext format
charactercharacter to determine height of. If character is invalid, then the maximum character height will be returned.
includeEffectsif true, then the size of formatting effects such as buffers and shadows will be considered in the returned height. If false, then the returned size considers the character only.
Since
QGIS 3.16

Definition at line 642 of file qgstextrenderer.cpp.

◆ textRequiresWrapping()

bool QgsTextRenderer::textRequiresWrapping ( const QgsRenderContext context,
const QString &  text,
double  width,
const QgsTextFormat format 
)
static

Returns true if the specified text requires line wrapping in order to fit within the specified width (in painter units).

See also
wrappedText()
Since
QGIS 3.24

Definition at line 689 of file qgstextrenderer.cpp.

◆ textWidth()

double QgsTextRenderer::textWidth ( const QgsRenderContext context,
const QgsTextFormat format,
const QStringList &  textLines,
QFontMetricsF *  fontMetrics = nullptr 
)
static

Returns the width of a text based on a given format.

Parameters
contextrender context
formattext format
textLineslist of lines of text to calculate width from
fontMetricsfont metrics

Definition at line 588 of file qgstextrenderer.cpp.

◆ wrappedText()

QStringList QgsTextRenderer::wrappedText ( const QgsRenderContext context,
const QString &  text,
double  width,
const QgsTextFormat format 
)
static

Wraps a text string to multiple lines, such that each individual line will fit within the specified width (in painter units).

See also
textRequiresWrapping()
Since
QGIS 3.24

Definition at line 699 of file qgstextrenderer.cpp.

Friends And Related Function Documentation

◆ QgsLabelPreview

friend class QgsLabelPreview
friend

Definition at line 428 of file qgstextrenderer.h.

◆ QgsVectorLayerLabelProvider

friend class QgsVectorLayerLabelProvider
friend

Definition at line 427 of file qgstextrenderer.h.

Member Data Documentation

◆ FONT_WORKAROUND_SCALE

constexpr double QgsTextRenderer::FONT_WORKAROUND_SCALE = 10
staticconstexpr

Scale factor for upscaling font sizes and downscaling destination painter devices.

Using this scale factor and manually adjusting any font metric based calculations results in more stable font metrics and sizes for small font sizes.

Since
QGIS 3.16

Definition at line 266 of file qgstextrenderer.h.


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