mirror of
https://github.com/qgis/QGIS.git
synced 2025-10-08 00:05:09 -04:00
402 lines
17 KiB
Plaintext
402 lines
17 KiB
Plaintext
/************************************************************************
|
|
* This file has been generated automatically from *
|
|
* *
|
|
* src/core/textrenderer/qgstextrenderer.h *
|
|
* *
|
|
* Do not edit manually ! Edit header and run scripts/sipify.py again *
|
|
************************************************************************/
|
|
|
|
|
|
|
|
|
|
|
|
|
|
class QgsTextRenderer
|
|
{
|
|
%Docstring(signature="appended")
|
|
Handles rendering text using rich formatting options, including drop
|
|
shadows, buffers and background shapes.
|
|
%End
|
|
|
|
%TypeHeaderCode
|
|
#include "qgstextrenderer.h"
|
|
%End
|
|
public:
|
|
|
|
static Qgis::TextHorizontalAlignment convertQtHAlignment( Qt::Alignment alignment );
|
|
%Docstring
|
|
Converts a Qt horizontal ``alignment`` flag to a
|
|
:py:class:`Qgis`.TextHorizontalAlignment value.
|
|
|
|
.. seealso:: :py:func:`convertQtVAlignment`
|
|
|
|
.. versionadded:: 3.16
|
|
%End
|
|
|
|
static Qgis::TextVerticalAlignment convertQtVAlignment( Qt::Alignment alignment );
|
|
%Docstring
|
|
Converts a Qt vertical ``alignment`` flag to a
|
|
:py:class:`Qgis`.TextVerticalAlignment value.
|
|
|
|
.. seealso:: :py:func:`convertQtHAlignment`
|
|
|
|
.. versionadded:: 3.16
|
|
%End
|
|
|
|
static int sizeToPixel( double size, const QgsRenderContext &c, Qgis::RenderUnit unit, const QgsMapUnitScale &mapUnitScale = QgsMapUnitScale() );
|
|
%Docstring
|
|
Calculates pixel size (considering output size should be in pixel or map
|
|
units, scale factors and optionally oversampling)
|
|
|
|
:param size: size to convert
|
|
:param c: rendercontext
|
|
:param unit: size units
|
|
:param mapUnitScale: a mapUnitScale clamper
|
|
|
|
:return: font pixel size
|
|
%End
|
|
|
|
|
|
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 );
|
|
%Docstring
|
|
Draws text within a rectangle using the specified settings.
|
|
|
|
:param rect: destination rectangle for text, in painter units
|
|
:param rotation: text rotation
|
|
:param alignment: horizontal alignment
|
|
:param textLines: list of lines of text to draw
|
|
:param context: render context
|
|
:param format: text format
|
|
:param 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
|
|
:py:func:`QgsRenderContext.setTextRenderFormat()`
|
|
instead.
|
|
:param vAlignment: vertical alignment (since QGIS 3.16)
|
|
:param flags: text rendering flags (since QGIS 3.24)
|
|
:param mode: text layout mode. Only
|
|
:py:class:`Qgis`.TextLayoutMode.Rectangle,
|
|
:py:class:`Qgis`.TextLayoutMode.RectangleCapHeightBased and
|
|
:py:class:`Qgis`.TextLayoutMode.RectangleAscentBased are
|
|
accepted (since QGIS 3.30)
|
|
|
|
.. seealso:: :py:func:`drawDocument` which is more efficient if the text document and metrics have already been calculated.
|
|
%End
|
|
|
|
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() );
|
|
%Docstring
|
|
Draws a text document within a rectangle using the specified settings.
|
|
|
|
Calling this method is more efficient than calling
|
|
:py:func:`~QgsTextRenderer.drawText` if the text document and metrics
|
|
have already been calculated.
|
|
|
|
.. warning::
|
|
|
|
Unlike :py:func:`~QgsTextRenderer.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``.
|
|
|
|
:param rect: destination rectangle for text, in painter units
|
|
:param format: base text format
|
|
:param document: text document to draw
|
|
:param metrics: precalculated text metrics
|
|
:param context: destination render context
|
|
:param horizontalAlignment: horizontal alignment
|
|
:param verticalAlignment: vertical alignment
|
|
:param rotation: text rotation
|
|
:param mode: text layout mode. Only
|
|
:py:class:`Qgis`.TextLayoutMode.Rectangle,
|
|
:py:class:`Qgis`.TextLayoutMode.RectangleCapHeightBased and
|
|
:py:class:`Qgis`.TextLayoutMode.RectangleAscentBased are
|
|
accepted.
|
|
:param flags: text rendering flags
|
|
|
|
.. versionadded:: 3.30
|
|
%End
|
|
|
|
static void drawText( QPointF point, double rotation, Qgis::TextHorizontalAlignment alignment, const QStringList &textLines,
|
|
QgsRenderContext &context, const QgsTextFormat &format,
|
|
bool drawAsOutlines = true );
|
|
%Docstring
|
|
Draws text at a point origin using the specified settings.
|
|
|
|
:param point: origin of text, in painter units
|
|
:param rotation: text rotation
|
|
:param alignment: horizontal alignment
|
|
:param textLines: list of lines of text to draw
|
|
:param context: render context
|
|
:param format: text format
|
|
:param 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
|
|
:py:func:`QgsRenderContext.setTextRenderFormat()`
|
|
instead.
|
|
%End
|
|
|
|
static void drawDocument( QPointF point,
|
|
const QgsTextFormat &format,
|
|
const QgsTextDocument &document,
|
|
const QgsTextDocumentMetrics &metrics,
|
|
QgsRenderContext &context,
|
|
Qgis::TextHorizontalAlignment alignment,
|
|
double rotation,
|
|
Qgis::TextLayoutMode mode = Qgis::TextLayoutMode::Point );
|
|
%Docstring
|
|
Draws a text document at a point origin using the specified settings.
|
|
|
|
Calling this method is more efficient than calling
|
|
:py:func:`~QgsTextRenderer.drawText` if the text document and metrics
|
|
have already been calculated.
|
|
|
|
.. warning::
|
|
|
|
Unlike :py:func:`~QgsTextRenderer.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``.
|
|
|
|
:param point: origin of text, in painter units
|
|
:param format: base text format
|
|
:param document: text document to draw
|
|
:param metrics: precalculated text metrics
|
|
:param context: destination render context
|
|
:param alignment: horizontal alignment
|
|
:param rotation: text rotation
|
|
:param mode: optional layout mode (since QGIS 3.42)
|
|
|
|
.. versionadded:: 3.40
|
|
%End
|
|
|
|
static void drawTextOnLine( const QPolygonF &line, const QString &text,
|
|
QgsRenderContext &context, const QgsTextFormat &format,
|
|
double offsetAlongLine = 0, double offsetFromLine = 0 );
|
|
%Docstring
|
|
Draws text along a line using the specified settings.
|
|
|
|
:param line: line to render text along, in painter units
|
|
:param text: text to draw
|
|
:param context: render context
|
|
:param format: text format
|
|
:param offsetAlongLine: offset along the line (in painter units) to
|
|
start text at
|
|
:param 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.
|
|
|
|
.. versionadded:: 3.32
|
|
%End
|
|
|
|
static void drawDocumentOnLine( const QPolygonF &line,
|
|
const QgsTextFormat &format,
|
|
const QgsTextDocument &document,
|
|
QgsRenderContext &context,
|
|
double offsetAlongLine = 0,
|
|
double offsetFromLine = 0 );
|
|
%Docstring
|
|
Draws a text document along a line using the specified settings.
|
|
|
|
:param line: line to render text along, in painter units
|
|
:param format: text format
|
|
:param document: text document to draw
|
|
:param context: render context
|
|
:param offsetAlongLine: offset along the line (in painter units) to
|
|
start text at
|
|
:param 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.
|
|
|
|
.. versionadded:: 3.32
|
|
%End
|
|
|
|
static void drawPart( const QRectF &rect, double rotation, Qgis::TextHorizontalAlignment alignment, const QStringList &textLines,
|
|
QgsRenderContext &context, const QgsTextFormat &format,
|
|
Qgis::TextComponent part, bool drawAsOutlines = true ) /Deprecated="Since 3.40. Private API only, will be removed in 4.0."/;
|
|
%Docstring
|
|
Draws a single component of rendered text using the specified settings.
|
|
|
|
:param rect: destination rectangle for text, in painter units
|
|
:param rotation: text rotation
|
|
:param alignment: horizontal alignment
|
|
:param textLines: list of lines of text to draw
|
|
:param context: render context
|
|
:param format: text format
|
|
:param 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)
|
|
:param 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
|
|
:py:func:`QgsRenderContext.setTextRenderFormat()`
|
|
instead.
|
|
|
|
.. deprecated:: 3.40
|
|
|
|
Private API only, will be removed in 4.0.
|
|
%End
|
|
|
|
static void drawPart( QPointF origin, double rotation, Qgis::TextHorizontalAlignment alignment, const QStringList &textLines,
|
|
QgsRenderContext &context, const QgsTextFormat &format,
|
|
Qgis::TextComponent part, bool drawAsOutlines = true ) /Deprecated="Since 3.40. Private API only, will be removed in 4.0."/;
|
|
%Docstring
|
|
Draws a single component of rendered text using the specified settings.
|
|
|
|
:param origin: origin for start of text, in painter units. Y coordinate
|
|
will be used as baseline.
|
|
:param rotation: text rotation
|
|
:param alignment: horizontal alignment
|
|
:param textLines: list of lines of text to draw
|
|
:param context: render context
|
|
:param format: text format
|
|
:param 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)
|
|
:param 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
|
|
:py:func:`QgsRenderContext.setTextRenderFormat()`
|
|
instead.
|
|
|
|
.. deprecated:: 3.40
|
|
|
|
Private API only, will be removed in 4.0.
|
|
%End
|
|
|
|
static QFontMetricsF fontMetrics( QgsRenderContext &context, const QgsTextFormat &format, double scaleFactor = 1.0 );
|
|
%Docstring
|
|
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
|
|
:py:func:`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.
|
|
|
|
.. versionadded:: 3.2
|
|
%End
|
|
|
|
static double textWidth( const QgsRenderContext &context, const QgsTextFormat &format, const QStringList &textLines,
|
|
QFontMetricsF *fontMetrics = 0 );
|
|
%Docstring
|
|
Returns the width of a text based on a given format.
|
|
|
|
:param context: render context
|
|
:param format: text format
|
|
:param textLines: list of lines of text to calculate width from
|
|
:param fontMetrics: font metrics
|
|
%End
|
|
|
|
static double textHeight( const QgsRenderContext &context, const QgsTextFormat &format, const QStringList &textLines, Qgis::TextLayoutMode mode = Qgis::TextLayoutMode::Point,
|
|
QFontMetricsF *fontMetrics = 0, Qgis::TextRendererFlags flags = Qgis::TextRendererFlags(), double maxLineWidth = 0 );
|
|
%Docstring
|
|
Returns the height of a text based on a given format.
|
|
|
|
:param context: render context
|
|
:param format: text format
|
|
:param textLines: list of lines of text to calculate width from
|
|
:param mode: draw mode
|
|
:param fontMetrics: font metrics
|
|
:param flags: text renderer flags (since QGIS 3.24)
|
|
:param maxLineWidth: maximum line width, in painter units. Used when the
|
|
:py:class:`Qgis`.TextRendererFlag.WrapLines flag is
|
|
used (since QGIS 3.24)
|
|
%End
|
|
|
|
static double textHeight( const QgsRenderContext &context, const QgsTextFormat &format, QChar character, bool includeEffects = false );
|
|
%Docstring
|
|
Returns the height of a character when rendered with the specified text
|
|
``format``.
|
|
|
|
:param context: render context
|
|
:param format: text format
|
|
:param character: character to determine height of. If ``character`` is
|
|
invalid, then the maximum character height will be
|
|
returned.
|
|
:param 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.
|
|
|
|
.. versionadded:: 3.16
|
|
%End
|
|
|
|
static bool textRequiresWrapping( const QgsRenderContext &context, const QString &text, double width, const QgsTextFormat &format );
|
|
%Docstring
|
|
Returns ``True`` if the specified ``text`` requires line wrapping in
|
|
order to fit within the specified ``width`` (in painter units).
|
|
|
|
.. seealso:: :py:func:`wrappedText`
|
|
|
|
.. versionadded:: 3.24
|
|
%End
|
|
|
|
static QStringList wrappedText( const QgsRenderContext &context, const QString &text, double width, const QgsTextFormat &format );
|
|
%Docstring
|
|
Wraps a ``text`` string to multiple lines, such that each individual
|
|
line will fit within the specified ``width`` (in painter units).
|
|
|
|
.. seealso:: :py:func:`textRequiresWrapping`
|
|
|
|
.. versionadded:: 3.24
|
|
%End
|
|
|
|
static const double FONT_WORKAROUND_SCALE;
|
|
|
|
static double calculateScaleFactorForFormat( const QgsRenderContext &context, const QgsTextFormat &format );
|
|
%Docstring
|
|
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.
|
|
|
|
.. versionadded:: 3.40
|
|
%End
|
|
|
|
|
|
static const double SUPERSCRIPT_SUBSCRIPT_FONT_SIZE_SCALING_FACTOR;
|
|
|
|
};
|
|
|
|
/************************************************************************
|
|
* This file has been generated automatically from *
|
|
* *
|
|
* src/core/textrenderer/qgstextrenderer.h *
|
|
* *
|
|
* Do not edit manually ! Edit header and run scripts/sipify.py again *
|
|
************************************************************************/
|