/************************************************************************
 * This file has been generated automatically from                      *
 *                                                                      *
 * src/core/textrenderer/qgstextformat.h                                *
 *                                                                      *
 * Do not edit manually ! Edit header and run scripts/sipify.py again   *
 ************************************************************************/





class QgsTextFormat
{
%Docstring(signature="appended")
Container for all settings relating to text rendering.

.. note::

   :py:class:`QgsTextFormat` objects are implicitly shared.
%End

%TypeHeaderCode
#include "qgstextformat.h"
%End
  public:

    QgsTextFormat();
%Docstring
Default constructor for QgsTextFormat. Creates a text format initially
set to an invalid state (see :py:func:`~QgsTextFormat.isValid`).
%End

    QgsTextFormat( const QgsTextFormat &other );


    ~QgsTextFormat();

    bool operator==( const QgsTextFormat &other ) const;
    bool operator!=( const QgsTextFormat &other ) const;

    bool isValid() const;
%Docstring
Returns ``True`` if the format is valid.

A default constructed QgsTextFormat is invalid, until at least one or
more properties have been set on the format. An invalid state can be
used as a representation of a "not set" text format, e.g. for indicating
that a default text format should be used.

.. note::

   Calling any setter on a QgsTextFormat object will automatically set the format as valid.

.. seealso:: :py:func:`setValid`

.. versionadded:: 3.16
%End

    void setValid();
%Docstring
Sets the format to a valid state, without changing any of the default
format settings.

.. seealso:: :py:func:`isValid`

.. versionadded:: 3.16
%End

    QgsTextBufferSettings &buffer();
%Docstring
Returns a reference to the text buffer settings.

.. seealso:: :py:func:`setBuffer`
%End


    void setBuffer( const QgsTextBufferSettings &bufferSettings );
%Docstring
Sets the text's buffer settings.

:param bufferSettings: buffer settings

.. seealso:: :py:func:`buffer`
%End

    QgsTextBackgroundSettings &background();
%Docstring
Returns a reference to the text background settings.

.. seealso:: :py:func:`setBackground`
%End


    void setBackground( const QgsTextBackgroundSettings &backgroundSettings );
%Docstring
Sets the text's background settings.q

:param backgroundSettings: background settings

.. seealso:: :py:func:`background`
%End

    QgsTextShadowSettings &shadow();
%Docstring
Returns a reference to the text drop shadow settings.

.. seealso:: :py:func:`setShadow`
%End


    void setShadow( const QgsTextShadowSettings &shadowSettings );
%Docstring
Sets the text's drop shadow settings.

:param shadowSettings: shadow settings

.. seealso:: :py:func:`shadow`
%End

    QgsTextMaskSettings &mask();
%Docstring
Returns a reference to the masking settings.

.. seealso:: :py:func:`setMask`
%End


    void setMask( const QgsTextMaskSettings &maskSettings );
%Docstring
Sets the text's masking settings. Masks may be defined in contexts where
the text is rendered over some map layers, for labeling especially.

:param maskSettings: mask settings

.. seealso:: :py:func:`mask`

.. versionadded:: 3.12
%End

    QFont font() const;
%Docstring
Returns the font used for rendering text. Note that the size of the font
is not used, and :py:func:`~QgsTextFormat.size` should be called instead
to determine the size of rendered text.

.. seealso:: :py:func:`scaledFont`

.. seealso:: :py:func:`setFont`

.. seealso:: :py:func:`namedStyle`

.. seealso:: :py:func:`toQFont`
%End

    QFont scaledFont( const QgsRenderContext &context, double scaleFactor = 1.0 ) const;
%Docstring
Returns a font with the size scaled to match the format's size settings
(including units and map unit scale) for a specified render context.

:param context: destination render context
:param scaleFactor: optional 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.

:return: font with scaled size

.. seealso:: :py:func:`font`

.. seealso:: :py:func:`size`
%End

    void setFont( const QFont &font );
%Docstring
Sets the font used for rendering text. Note that the size of the font is
not used, and :py:func:`~QgsTextFormat.setSize` should be called instead
to explicitly set the size of rendered text.

:param font: desired font

.. seealso:: :py:func:`font`

.. seealso:: :py:func:`setNamedStyle`

.. seealso:: :py:func:`fromQFont`
%End

    QString namedStyle() const;
%Docstring
Returns the named style for the font used for rendering text (e.g.,
"bold").

.. seealso:: :py:func:`setNamedStyle`

.. seealso:: :py:func:`font`
%End

    void setNamedStyle( const QString &style );
%Docstring
Sets the named style for the font used for rendering text.

:param style: named style, e.g., "bold"

.. seealso:: :py:func:`namedStyle`

.. seealso:: :py:func:`setFont`
%End

    bool forcedBold() const;
%Docstring
Returns ``True`` if the format is set to force a bold style.

.. warning::

   Unlike setting a font's style via :py:func:`~QgsTextFormat.setNamedStyle`, this will ensure that a font is
   always rendered in bold regardless of whether the font family actually has a bold variant. A
   "faux bold" effect will be emulated, which may result in poor quality font rendering. For this
   reason it is greatly preferred to call :py:func:`~QgsTextFormat.setNamedStyle` instead.

.. seealso:: :py:func:`setForcedBold`

.. versionadded:: 3.26
%End

    void setForcedBold( bool forced );
%Docstring
Sets whether the format is set to force a bold style.

.. warning::

   Unlike setting a font's style via :py:func:`~QgsTextFormat.setNamedStyle`, this will ensure that a font is
   always rendered in bold regardless of whether the font family actually has a bold variant. A
   "faux bold" effect will be emulated, which may result in poor quality font rendering. For this
   reason it is greatly preferred to call :py:func:`~QgsTextFormat.setNamedStyle` instead.

.. seealso:: :py:func:`forcedBold`

.. versionadded:: 3.26
%End

    bool forcedItalic() const;
%Docstring
Returns ``True`` if the format is set to force an italic style.

.. warning::

   Unlike setting a font's style via :py:func:`~QgsTextFormat.setNamedStyle`, this will ensure that a font is
   always rendered in italic regardless of whether the font family actually has an italic variant. A
   "faux italic" slanted text effect will be emulated, which may result in poor quality font rendering. For this
   reason it is greatly preferred to call :py:func:`~QgsTextFormat.setNamedStyle` instead.

.. seealso:: :py:func:`setForcedItalic`

.. versionadded:: 3.26
%End

    void setForcedItalic( bool forced );
%Docstring
Sets whether the format is set to force an italic style.

.. warning::

   Unlike setting a font's style via :py:func:`~QgsTextFormat.setNamedStyle`, this will ensure that a font is
   always rendered in italic regardless of whether the font family actually has an italic variant. A
   "faux italic" slanted text effect will be emulated, which may result in poor quality font rendering. For this
   reason it is greatly preferred to call :py:func:`~QgsTextFormat.setNamedStyle` instead.

.. seealso:: :py:func:`forcedItalic`

.. versionadded:: 3.26
%End

    QStringList families() const;
%Docstring
Returns the list of font families to use when restoring the text format,
in order of precedence.

.. warning::

   The list of families returned by this method is ONLY used when restoring the text format
   from serialized versions, and will not affect the current :py:func:`~QgsTextFormat.font` familily used by the format.

.. seealso:: :py:func:`setFamilies`

.. versionadded:: 3.20
%End

    void setFamilies( const QStringList &families );
%Docstring
Sets a list of font ``families`` to use for the text format, in order of
precedence.

When restoring serialized versions of the text format then the first
matching font family from this list will be used for the text format.
This provides a way to specify a list of possible font families which
are used as fallbacks if a family isn't available on a particular QGIS
install (CSS style).

.. warning::

   The list of families set by calling this method is ONLY used when restoring the text format
   from serialized versions, and will not affect the current :py:func:`~QgsTextFormat.font` familily used by the format.

.. seealso:: :py:func:`families`

.. versionadded:: 3.20
%End

    double size() const;
%Docstring
Returns the size for rendered text. Units are retrieved using
:py:func:`~QgsTextFormat.sizeUnit`.

.. seealso:: :py:func:`setSize`

.. seealso:: :py:func:`sizeUnit`
%End

    void setSize( double size );
%Docstring
Sets the size for rendered text.

:param size: size of rendered text. Units are set using
             :py:func:`~QgsTextFormat.setSizeUnit`

.. seealso:: :py:func:`size`

.. seealso:: :py:func:`setSizeUnit`
%End

    Qgis::RenderUnit sizeUnit() const;
%Docstring
Returns the units for the size of rendered text.

.. seealso:: :py:func:`size`

.. seealso:: :py:func:`setSizeUnit`

.. seealso:: :py:func:`sizeMapUnitScale`
%End

    void setSizeUnit( Qgis::RenderUnit unit );
%Docstring
Sets the units for the size of rendered text.

:param unit: size units

.. seealso:: :py:func:`setSize`

.. seealso:: :py:func:`sizeUnit`

.. seealso:: :py:func:`setSizeMapUnitScale`
%End

    QgsMapUnitScale sizeMapUnitScale() const;
%Docstring
Returns the map unit scale object for the size. This is only used if the
:py:func:`~QgsTextFormat.sizeUnit` is set to
:py:class:`QgsUnitTypes`.RenderMapUnit.

.. seealso:: :py:func:`setSizeMapUnitScale`

.. seealso:: :py:func:`sizeUnit`
%End

    void setSizeMapUnitScale( const QgsMapUnitScale &scale );
%Docstring
Sets the map unit scale object for the size. This is only used if the
:py:func:`~QgsTextFormat.sizeUnit` is set to
:py:class:`QgsUnitTypes`.RenderMapUnit.

.. seealso:: :py:func:`sizeMapUnitScale`

.. seealso:: :py:func:`setSizeUnit`
%End

    QColor color() const;
%Docstring
Returns the color that text will be rendered in.

.. seealso:: :py:func:`setColor`
%End

    void setColor( const QColor &color );
%Docstring
Sets the color that text will be rendered in.

:param color: text color

.. seealso:: :py:func:`color`
%End

    double opacity() const;
%Docstring
Returns the text's opacity. The opacity is a double value between 0
(fully transparent) and 1 (totally opaque).

.. seealso:: :py:func:`setOpacity`
%End

    void multiplyOpacity( double opacityFactor );
%Docstring
Multiply opacity by ``opacityFactor``.

This method multiplies the opacity of all the labeling elements (text,
shadow, buffer etc.) by ``opacityFactor`` effectively changing the
opacity of the whole labeling.

.. versionadded:: 3.32
%End

    void setOpacity( double opacity );
%Docstring
Sets the text's opacity.

:param opacity: opacity as a double value between 0 (fully transparent)
                and 1 (totally opaque)

.. seealso:: :py:func:`opacity`
%End

    int stretchFactor() const;
%Docstring
Returns the text's stretch factor.

The stretch factor matches a condensed or expanded version of the font
or applies a stretch transform that changes the width of all characters
in the font by factor percent.

For example, a factor of 150 results in all characters in the font being
1.5 times (ie. 150%) wider. The minimum stretch factor is 1, and the
maximum stretch factor is 4000.

.. seealso:: :py:func:`setStretchFactor`

.. versionadded:: 3.24
%End

    void setStretchFactor( int factor );
%Docstring
Sets the text's stretch ``factor``.

The stretch factor matches a condensed or expanded version of the font
or applies a stretch transform that changes the width of all characters
in the font by factor percent.

For example, setting ``factor`` to 150 results in all characters in the
font being 1.5 times (ie. 150%) wider. The minimum stretch factor is 1,
and the maximum stretch factor is 4000.

.. seealso:: :py:func:`stretchFactor`

.. versionadded:: 3.24
%End

    QPainter::CompositionMode blendMode() const;
%Docstring
Returns the blending mode used for drawing the text.

.. seealso:: :py:func:`setBlendMode`
%End

    void setBlendMode( QPainter::CompositionMode mode );
%Docstring
Sets the blending mode used for drawing the text.

:param mode: blending mode

.. seealso:: :py:func:`blendMode`
%End

    double lineHeight() const;
%Docstring
Returns the line height for text.

If :py:func:`~QgsTextFormat.lineHeightUnit` is
:py:class:`QgsUnitTypes`.RenderPercentage (the default), then this is a
number representing the leading between lines as a multiplier of line
height (where 0 - 1.0 represents 0 to 100% of text line height).
Otherwise the line height is an absolute measurement in
:py:func:`~QgsTextFormat.lineHeightUnit`.

.. seealso:: :py:func:`setLineHeight`

.. seealso:: :py:func:`lineHeightUnit`
%End

    void setLineHeight( double height );
%Docstring
Sets the line height for text.

If :py:func:`~QgsTextFormat.lineHeightUnit` is
:py:class:`QgsUnitTypes`.RenderPercentage (the default), then ``height``
is a number representing the leading between lines as a multiplier of
line height (where 0 - 1.0 represents 0 to 100% of text line height).
Otherwise ``height`` is an absolute measurement in
:py:func:`~QgsTextFormat.lineHeightUnit`.

.. seealso:: :py:func:`lineHeight`

.. seealso:: :py:func:`setLineHeightUnit`
%End

    Qgis::RenderUnit lineHeightUnit() const;
%Docstring
Returns the units for the line height for text.

.. seealso:: :py:func:`setLineHeightUnit`

.. seealso:: :py:func:`lineHeight`

.. versionadded:: 3.28
%End

    void setLineHeightUnit( Qgis::RenderUnit unit );
%Docstring
Sets the ``unit`` for the line height for text.

.. seealso:: :py:func:`lineHeightUnit`

.. seealso:: :py:func:`setLineHeight`

.. versionadded:: 3.28
%End

    double tabStopDistance() const;
%Docstring
Returns the distance for tab stops.

.. seealso:: :py:func:`tabStopDistanceUnit`

.. seealso:: :py:func:`setTabStopDistance`

.. versionadded:: 3.38
%End

    void setTabStopDistance( double distance );
%Docstring
Sets the ``distance`` for tab stops. The units are specified using
:py:func:`~QgsTextFormat.setTabStopDistanceUnit`.

.. seealso:: :py:func:`tabStopDistance`

.. seealso:: :py:func:`setTabStopDistanceUnit`

.. versionadded:: 3.38
%End

    Qgis::RenderUnit tabStopDistanceUnit() const;
%Docstring
Returns the units for the tab stop distance.

.. seealso:: :py:func:`tabStopDistance`

.. seealso:: :py:func:`setTabStopDistanceUnit`

.. versionadded:: 3.38
%End

    void setTabStopDistanceUnit( Qgis::RenderUnit unit );
%Docstring
Sets the ``unit`` used for the tab stop distance.

.. seealso:: :py:func:`setTabStopDistance`

.. seealso:: :py:func:`tabStopDistanceUnit`

.. versionadded:: 3.38
%End

    QgsMapUnitScale tabStopDistanceMapUnitScale() const;
%Docstring
Returns the map unit scale object for the tab stop distance. This is
only used if the tab stop distance is set to
:py:class:`Qgis`.RenderUnit.MapUnits.

.. seealso:: :py:func:`setTabStopDistanceMapUnitScale`

.. seealso:: :py:func:`tabStopDistanceUnit`

.. versionadded:: 3.38
%End

    void setTabStopDistanceMapUnitScale( const QgsMapUnitScale &scale );
%Docstring
Sets the map unit ``scale`` object for the tab stop distance. This is
only used if the tab stop distance is set to
:py:class:`Qgis`.RenderUnit.MapUnits.

.. seealso:: :py:func:`tabStopDistanceMapUnitScale`

.. seealso:: :py:func:`setTabStopDistanceUnit`

.. versionadded:: 3.38
%End

    Qgis::TextOrientation orientation() const;
%Docstring
Returns the orientation of the text.

.. seealso:: :py:func:`setOrientation`

.. versionadded:: 3.10
%End

    void setOrientation( Qgis::TextOrientation orientation );
%Docstring
Sets the ``orientation`` for the text.

.. seealso:: :py:func:`orientation`

.. versionadded:: 3.10
%End

    Qgis::Capitalization capitalization() const;
%Docstring
Returns the text capitalization style.

.. seealso:: :py:func:`setCapitalization`

.. versionadded:: 3.16
%End

    void setCapitalization( Qgis::Capitalization capitalization );
%Docstring
Sets the text ``capitalization`` style.

.. seealso:: :py:func:`capitalization`

.. versionadded:: 3.16
%End

    bool allowHtmlFormatting() const;
%Docstring
Returns ``True`` if text should be treated as a HTML document and HTML
tags should be used for formatting the rendered text.

.. warning::

   Only a small subset of HTML formatting is supported. Currently this is restricted to:

- text color formatting
- strikethrough
- underline
- overline

.. seealso:: :py:func:`setAllowHtmlFormatting`

.. versionadded:: 3.14
%End

    void setAllowHtmlFormatting( bool allow );
%Docstring
Sets whether text should be treated as a HTML document and HTML tags
should be used for formatting the rendered text.

.. warning::

   Only a small subset of HTML formatting is supported. Currently this is restricted to:

- text color formatting
- strikethrough
- underline
- overline

.. seealso:: :py:func:`allowHtmlFormatting`

.. versionadded:: 3.14
%End

    QColor previewBackgroundColor() const;
%Docstring
Returns the background color for text previews.

.. seealso:: :py:func:`setPreviewBackgroundColor`

.. versionadded:: 3.10
%End

    void setPreviewBackgroundColor( const QColor &color );
%Docstring
Sets the background ``color`` that text will be rendered on for
previews.

.. seealso:: :py:func:`previewBackgroundColor`

.. versionadded:: 3.10
%End

    void readFromLayer( QgsVectorLayer *layer );
%Docstring
Reads settings from a layer's custom properties (for QGIS 2.x projects).

:param layer: source vector layer
%End

    void readXml( const QDomElement &elem, const QgsReadWriteContext &context );
%Docstring
Read settings from a DOM element.

.. seealso:: :py:func:`writeXml`
%End

    QDomElement writeXml( QDomDocument &doc, const QgsReadWriteContext &context ) const;
%Docstring
Write settings into a DOM element.

.. seealso:: :py:func:`readXml`
%End

    QMimeData *toMimeData() const /Factory/;
%Docstring
Returns new mime data representing the text format settings. Caller
takes responsibility for deleting the returned object.

.. seealso:: :py:func:`fromMimeData`
%End

    static QgsTextFormat fromQFont( const QFont &font );
%Docstring
Returns a text format matching the settings from an input ``font``.
Unlike :py:func:`~QgsTextFormat.setFont`, this method also handles the
size and size units from ``font``.

.. seealso:: :py:func:`toQFont`

.. versionadded:: 3.2
%End

    QFont toQFont() const;
%Docstring
Returns a QFont matching the relevant settings from this text format.
Unlike :py:func:`~QgsTextFormat.font`, this method also handles the size
and size units from the text format.

.. seealso:: :py:func:`fromQFont`

.. versionadded:: 3.2
%End

    static QgsTextFormat fromMimeData( const QMimeData *data, bool *ok /Out/ = 0 );
%Docstring
Attempts to parse the provided mime ``data`` as a QgsTextFormat. If data
can be parsed as a text format, ``ok`` will be set to ``True``.

.. seealso:: :py:func:`toMimeData`
%End

    bool containsAdvancedEffects() const;
%Docstring
Returns ``True`` if any component of the font format requires advanced
effects such as blend modes, which require output in raster formats to
be fully respected.
%End

    bool fontFound() const;
%Docstring
Returns ``True`` if the specified font was found on the system, or
``False`` if the font was not found and a replacement was used instead.

.. seealso:: :py:func:`resolvedFontFamily`
%End

    QString resolvedFontFamily() const;
%Docstring
Returns the family for the resolved font, ie if the specified font was
not found on the system this will return the name of the replacement
font.

.. seealso:: :py:func:`fontFound`
%End

    QgsPropertyCollection &dataDefinedProperties();
%Docstring
Returns a reference to the format's property collection, used for data
defined overrides.

.. seealso:: :py:func:`setDataDefinedProperties`

.. versionadded:: 3.10
%End


    QSet<QString> referencedFields( const QgsRenderContext &context ) const;
%Docstring
Returns all field names referenced by the configuration (e.g. from data
defined properties).

.. versionadded:: 3.14
%End

    void setDataDefinedProperties( const QgsPropertyCollection &collection );
%Docstring
Sets the format's property collection, used for data defined overrides.

:param collection: property collection. Existing properties will be
                   replaced.

.. seealso:: :py:func:`dataDefinedProperties`

.. versionadded:: 3.10
%End

    void updateDataDefinedProperties( QgsRenderContext &context );
%Docstring
Updates the format by evaluating current values of data defined
properties.

.. versionadded:: 3.10
%End

    static QPixmap textFormatPreviewPixmap( const QgsTextFormat &format, QSize size, const QString &previewText = QString(), int padding = 0, const QgsScreenProperties &screen = QgsScreenProperties() );
%Docstring
Returns a pixmap preview for a text ``format``.

:param format: text format
:param size: target pixmap size
:param previewText: text to render in preview, or empty for default text
:param padding: space between icon edge and color ramp
:param screen: can be used to specify the destination screen properties
               for the icon. This allows the icon to be generated using
               the correct DPI and device pixel ratio for the target
               screen (since QGIS 3.32)

.. versionadded:: 3.10
%End

    QString asCSS( double pointToPixelMultiplier = 1.0 ) const;
%Docstring
Returns a CSS string representing the specified text format as closely
as possible.

:param pointToPixelMultiplier: scaling factor to apply to convert point
                               sizes to pixel font sizes. The CSS
                               returned by this function will always use
                               pixels for font sizes, so this parameter
                               should be set to a suitable value to
                               convert point sizes to pixels (e.g.,
                               taking into account destination DPI)

:return: partial CSS string, e.g., "line-height: 120%;"

.. versionadded:: 3.34
%End

};


/************************************************************************
 * This file has been generated automatically from                      *
 *                                                                      *
 * src/core/textrenderer/qgstextformat.h                                *
 *                                                                      *
 * Do not edit manually ! Edit header and run scripts/sipify.py again   *
 ************************************************************************/