QGIS API Documentation 3.39.0-Master (9ea1ddbe645)
|
Handles rendering text using rich formatting options, including drop shadows, buffers and background shapes. More...
#include <qgstextrenderer.h>
Static Public Member Functions | |
static double | calculateScaleFactorForFormat (const QgsRenderContext &context, const QgsTextFormat &format) |
Returns the scale factor used for upscaling font sizes and downscaling destination painter devices. | |
static Qgis::TextHorizontalAlignment | convertQtHAlignment (Qt::Alignment alignment) |
Converts a Qt horizontal alignment flag to a Qgis::TextHorizontalAlignment value. | |
static Qgis::TextVerticalAlignment | convertQtVAlignment (Qt::Alignment alignment) |
Converts a Qt vertical alignment flag to a Qgis::TextVerticalAlignment value. | |
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. | |
static void | drawDocumentOnLine (const QPolygonF &line, const QgsTextFormat &format, const QgsTextDocument &document, QgsRenderContext &context, double offsetAlongLine=0, double offsetFromLine=0) |
Draws a text document along a line using the specified settings. | |
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. | |
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. | |
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. | |
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. | |
static void | drawTextOnLine (const QPolygonF &line, const QString &text, QgsRenderContext &context, const QgsTextFormat &format, double offsetAlongLine=0, double offsetFromLine=0) |
Draws text along a line using the specified settings. | |
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. | |
static int | sizeToPixel (double size, const QgsRenderContext &c, Qgis::RenderUnit unit, const QgsMapUnitScale &mapUnitScale=QgsMapUnitScale()) |
Calculates pixel size (considering output size should be in pixel or map units, scale factors and optionally oversampling) | |
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. | |
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. | |
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). | |
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. | |
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). | |
Static Public Attributes | |
static constexpr double | FONT_WORKAROUND_SCALE = 10 |
Scale factor for upscaling font sizes and downscaling destination painter devices. | |
static constexpr double | SUPERSCRIPT_SUBSCRIPT_FONT_SIZE_SCALING_FACTOR = 2.0 / 3.0 |
Scale factor to use for super or subscript text which doesn't have an explicit font size set. | |
Friends | |
class | QgsLabelPreview |
class | QgsVectorLayerLabelProvider |
Handles rendering text using rich formatting options, including drop shadows, buffers and background shapes.
Definition at line 40 of file qgstextrenderer.h.
|
static |
Returns the scale factor used 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.
Definition at line 2236 of file qgstextrenderer.cpp.
|
static |
Converts a Qt horizontal alignment flag to a Qgis::TextHorizontalAlignment value.
Definition at line 38 of file qgstextrenderer.cpp.
|
static |
Converts a Qt vertical alignment flag to a Qgis::TextVerticalAlignment value.
Definition at line 53 of file qgstextrenderer.cpp.
|
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.
rect | destination rectangle for text, in painter units |
format | base text format |
document | text document to draw |
metrics | precalculated text metrics |
context | destination render context |
horizontalAlignment | horizontal alignment |
verticalAlignment | vertical alignment |
rotation | text rotation |
mode | text layout mode. Only Qgis::TextLayoutMode::Rectangle, Qgis::TextLayoutMode::RectangleCapHeightBased and Qgis::TextLayoutMode::RectangleAscentBased are accepted. |
flags | text rendering flags |
Definition at line 104 of file qgstextrenderer.cpp.
|
static |
Draws a text document along a line using the specified settings.
line | line to render text along, in painter units |
format | text format |
document | text document to draw |
context | render context |
offsetAlongLine | offset along the line (in painter units) to start text at |
offsetFromLine | offset from the line (in painter units). Negative values will shift the text to the left of the line, positive values will shift the text to the right. |
Definition at line 163 of file qgstextrenderer.cpp.
|
static |
Draws a single component of rendered text using the specified settings.
rect | destination rectangle for text, in painter units |
rotation | text rotation |
alignment | horizontal alignment |
textLines | list of lines of text to draw |
context | render context |
format | text format |
part | component 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) |
drawAsOutlines | set 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 403 of file qgstextrenderer.cpp.
|
static |
Draws a single component of rendered text using the specified settings.
origin | origin for start of text, in painter units. Y coordinate will be used as baseline. |
rotation | text rotation |
alignment | horizontal alignment |
textLines | list of lines of text to draw |
context | render context |
format | text format |
part | component 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) |
drawAsOutlines | set 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 486 of file qgstextrenderer.cpp.
|
static |
Draws text within a rectangle using the specified settings.
rect | destination rectangle for text, in painter units |
rotation | text rotation |
alignment | horizontal alignment |
textLines | list of lines of text to draw |
context | render context |
format | text format |
drawAsOutlines | set 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. |
vAlignment | vertical alignment (since QGIS 3.16) |
flags | text rendering flags (since QGIS 3.24) |
mode | text layout mode. Only Qgis::TextLayoutMode::Rectangle, Qgis::TextLayoutMode::RectangleCapHeightBased and Qgis::TextLayoutMode::RectangleAscentBased are accepted (since QGIS 3.30) |
Definition at line 73 of file qgstextrenderer.cpp.
|
static |
Draws text at a point origin using the specified settings.
point | origin of text, in painter units |
rotation | text rotation |
alignment | horizontal alignment |
textLines | list of lines of text to draw |
context | render context |
format | text format |
drawAsOutlines | set 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 121 of file qgstextrenderer.cpp.
|
static |
Draws text along a line using the specified settings.
line | line to render text along, in painter units |
text | text to draw |
context | render context |
format | text format |
offsetAlongLine | offset along the line (in painter units) to start text at |
offsetFromLine | offset from the line (in painter units). Negative values will shift the text to the left of the line, positive values will shift the text to the right. |
Definition at line 147 of file qgstextrenderer.cpp.
|
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::calculateScaleFactorForFormat() 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.
Definition at line 538 of file qgstextrenderer.cpp.
|
static |
Calculates pixel size (considering output size should be in pixel or map units, scale factors and optionally oversampling)
size | size to convert |
c | rendercontext |
unit | size units |
mapUnitScale | a mapUnitScale clamper |
Definition at line 68 of file qgstextrenderer.cpp.
|
static |
Returns the height of a text based on a given format.
context | render context |
format | text format |
textLines | list of lines of text to calculate width from |
mode | draw mode |
fontMetrics | font metrics |
flags | text renderer flags (since QGIS 3.24) |
maxLineWidth | maximum line width, in painter units. Used when the Qgis::TextRendererFlag::WrapLines flag is used (since QGIS 3.24) |
Definition at line 852 of file qgstextrenderer.cpp.
|
static |
Returns the height of a character when rendered with the specified text format.
context | render context |
format | text format |
character | character to determine height of. If character is invalid, then the maximum character height will be returned. |
includeEffects | if 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. |
Definition at line 877 of file qgstextrenderer.cpp.
|
static |
Returns true
if the specified text requires line wrapping in order to fit within the specified width (in painter units).
Definition at line 924 of file qgstextrenderer.cpp.
|
static |
Returns the width of a text based on a given format.
context | render context |
format | text format |
textLines | list of lines of text to calculate width from |
fontMetrics | font metrics |
Definition at line 823 of file qgstextrenderer.cpp.
|
static |
Wraps a text string to multiple lines, such that each individual line will fit within the specified width (in painter units).
Definition at line 934 of file qgstextrenderer.cpp.
|
friend |
Definition at line 480 of file qgstextrenderer.h.
|
friend |
Definition at line 479 of file qgstextrenderer.h.
|
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.
Definition at line 301 of file qgstextrenderer.h.
|
staticconstexpr |
Scale factor to use for super or subscript text which doesn't have an explicit font size set.
Definition at line 320 of file qgstextrenderer.h.