qgstextformat.sip.in

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





class QgsTextFormat
{
%Docstring
Container for all settings relating to text rendering.

.. note::

   QgsTextFormat objects are implicitly shared.

.. versionadded:: 3.0
%End

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

    enum TextOrientation
    {
      HorizontalOrientation,
      VerticalOrientation,
      RotationBasedOrientation,
    };

    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 );
%Docstring
Copy constructor.

:param other: source QgsTextFormat
%End


    ~QgsTextFormat();

    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
                    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.

: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

    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

    QgsUnitTypes::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( QgsUnitTypes::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 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 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 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

    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. This is a number between
0.0 and 10.0 representing the leading between lines as a
multiplier of line height.

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

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

:param height: a number between
               0.0 and 10.0 representing the leading between lines as a
               multiplier of line height.

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

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

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

.. versionadded:: 3.10
%End

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

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

.. versionadded:: 3.10
%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 );
%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

.. versionadded:: 3.10
%End

};


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