Branch data     Line data    Source code

       1                 :            : /***************************************************************************
       2                 :            :   qgstextformat.h
       3                 :            :   ---------------
       4                 :            :    begin                : May 2020
       5                 :            :    copyright            : (C) Nyall Dawson
       6                 :            :    email                : nyall dot dawson at gmail dot com
       7                 :            :  ***************************************************************************
       8                 :            :  *                                                                         *
       9                 :            :  *   This program is free software; you can redistribute it and/or modify  *
      10                 :            :  *   it under the terms of the GNU General Public License as published by  *
      11                 :            :  *   the Free Software Foundation; either version 2 of the License, or     *
      12                 :            :  *   (at your option) any later version.                                   *
      13                 :            :  *                                                                         *
      14                 :            :  ***************************************************************************/
      15                 :            : 
      16                 :            : #ifndef QGSTEXTFORMAT_H
      17                 :            : #define QGSTEXTFORMAT_H
      18                 :            : 
      19                 :            : #include "qgis_sip.h"
      20                 :            : #include "qgis_core.h"
      21                 :            : #include "qgsunittypes.h"
      22                 :            : #include "qgstextbuffersettings.h"
      23                 :            : #include "qgstextbackgroundsettings.h"
      24                 :            : #include "qgstextshadowsettings.h"
      25                 :            : #include "qgstextmasksettings.h"
      26                 :            : #include "qgsstringutils.h"
      27                 :            : 
      28                 :            : #include <QSharedDataPointer>
      29                 :            : 
      30                 :            : class QMimeData;
      31                 :            : class QgsTextSettingsPrivate;
      32                 :            : 
      33                 :            : /**
      34                 :            :  * \class QgsTextFormat
      35                 :            :   * \ingroup core
      36                 :            :   * \brief Container for all settings relating to text rendering.
      37                 :            :   * \note QgsTextFormat objects are implicitly shared.
      38                 :            :   * \since QGIS 3.0
      39                 :            :  */
      40                 :            : class CORE_EXPORT QgsTextFormat
      41                 :            : {
      42                 :            :   public:
      43                 :            : 
      44                 :            :     //! Text orientation
      45                 :            :     enum TextOrientation
      46                 :            :     {
      47                 :            :       HorizontalOrientation, //!< Vertically oriented text
      48                 :            :       VerticalOrientation, //!< Horizontally oriented text
      49                 :            :       RotationBasedOrientation, //!< Horizontally or vertically oriented text based on rotation (only available for map labeling)
      50                 :            :     };
      51                 :            : 
      52                 :            :     /**
      53                 :            :      * Default constructor for QgsTextFormat. Creates a text format initially
      54                 :            :      * set to an invalid state (see isValid()).
      55                 :            :      */
      56                 :            :     QgsTextFormat();
      57                 :            : 
      58                 :            :     /**
      59                 :            :      * Copy constructor.
      60                 :            :      * \param other source QgsTextFormat
      61                 :            :      */
      62                 :            :     QgsTextFormat( const QgsTextFormat &other );
      63                 :            : 
      64                 :            :     QgsTextFormat &operator=( const QgsTextFormat &other );
      65                 :            : 
      66                 :            :     ~QgsTextFormat();
      67                 :            : 
      68                 :            :     bool operator==( const QgsTextFormat &other ) const;
      69                 :            :     bool operator!=( const QgsTextFormat &other ) const;
      70                 :            : 
      71                 :            :     /**
      72                 :            :      * Returns TRUE if the format is valid.
      73                 :            :      *
      74                 :            :      * A default constructed QgsTextFormat is invalid, until at least one or more properties
      75                 :            :      * have been set on the format. An invalid state can be used as a representation of a "not set"
      76                 :            :      * text format, e.g. for indicating that a default text format should be used.
      77                 :            :      *
      78                 :            :      * \note Calling any setter on a QgsTextFormat object will automatically set the format as valid.
      79                 :            :      *
      80                 :            :      * \see setValid()
      81                 :            :      * \since QGIS 3.16
      82                 :            :      */
      83                 :            :     bool isValid() const;
      84                 :            : 
      85                 :            :     /**
      86                 :            :      * Sets the format to a valid state, without changing any of the default format settings.
      87                 :            :      *
      88                 :            :      * \see isValid()
      89                 :            :      * \since QGIS 3.16
      90                 :            :      */
      91                 :            :     void setValid();
      92                 :            : 
      93                 :            :     /**
      94                 :            :      * Returns a reference to the text buffer settings.
      95                 :            :      * \see setBuffer()
      96                 :            :      */
      97                 :            :     QgsTextBufferSettings &buffer();
      98                 :            : 
      99                 :            :     /**
     100                 :            :      * Returns a reference to the text buffer settings.
     101                 :            :      * \see setBuffer()
     102                 :            :      */
     103                 :          0 :     SIP_SKIP QgsTextBufferSettings buffer() const { return mBufferSettings; }
     104                 :            : 
     105                 :            :     /**
     106                 :            :      * Sets the text's buffer settings.
     107                 :            :      * \param bufferSettings buffer settings
     108                 :            :      * \see buffer()
     109                 :            :      */
     110                 :            :     void setBuffer( const QgsTextBufferSettings &bufferSettings );
     111                 :            : 
     112                 :            :     /**
     113                 :            :      * Returns a reference to the text background settings.
     114                 :            :      * \see setBackground()
     115                 :            :      */
     116                 :            :     QgsTextBackgroundSettings &background();
     117                 :            : 
     118                 :            :     /**
     119                 :            :      * Returns a reference to the text background settings.
     120                 :            :      * \see setBackground()
     121                 :            :      */
     122                 :          0 :     SIP_SKIP QgsTextBackgroundSettings background() const { return mBackgroundSettings; }
     123                 :            : 
     124                 :            :     /**
     125                 :            :      * Sets the text's background settings.q
     126                 :            :      * \param backgroundSettings background settings
     127                 :            :      * \see background()
     128                 :            :      */
     129                 :            :     void setBackground( const QgsTextBackgroundSettings &backgroundSettings );
     130                 :            : 
     131                 :            :     /**
     132                 :            :      * Returns a reference to the text drop shadow settings.
     133                 :            :      * \see setShadow()
     134                 :            :      */
     135                 :            :     QgsTextShadowSettings &shadow();
     136                 :            : 
     137                 :            :     /**
     138                 :            :      * Returns a reference to the text drop shadow settings.
     139                 :            :      * \see setShadow()
     140                 :            :      */
     141                 :          0 :     SIP_SKIP QgsTextShadowSettings shadow() const { return mShadowSettings; }
     142                 :            : 
     143                 :            :     /**
     144                 :            :      * Sets the text's drop shadow settings.
     145                 :            :      * \param shadowSettings shadow settings
     146                 :            :      * \see shadow()
     147                 :            :      */
     148                 :            :     void setShadow( const QgsTextShadowSettings &shadowSettings );
     149                 :            : 
     150                 :            :     /**
     151                 :            :      * Returns a reference to the masking settings.
     152                 :            :      * \see setMask()
     153                 :            :      */
     154                 :            :     QgsTextMaskSettings &mask();
     155                 :            : 
     156                 :            :     /**
     157                 :            :      * Returns a reference to the masking settings.
     158                 :            :      * Masks may be defined in contexts where the text is rendered over some map layers, for labeling especially.
     159                 :            :      * \see setMask()
     160                 :            :      * \since QGIS 3.12
     161                 :            :      */
     162                 :          0 :     SIP_SKIP QgsTextMaskSettings mask() const { return mMaskSettings; }
     163                 :            : 
     164                 :            :     /**
     165                 :            :      * Sets the text's masking settings.
     166                 :            :      * Masks may be defined in contexts where the text is rendered over some map layers, for labeling especially.
     167                 :            :      * \param maskSettings mask settings
     168                 :            :      * \see mask()
     169                 :            :      * \since QGIS 3.12
     170                 :            :      */
     171                 :            :     void setMask( const QgsTextMaskSettings &maskSettings );
     172                 :            : 
     173                 :            :     /**
     174                 :            :      * Returns the font used for rendering text. Note that the size of the font
     175                 :            :      * is not used, and size() should be called instead to determine the size
     176                 :            :      * of rendered text.
     177                 :            :      * \see scaledFont()
     178                 :            :      * \see setFont()
     179                 :            :      * \see namedStyle()
     180                 :            :      * \see toQFont()
     181                 :            :      */
     182                 :            :     QFont font() const;
     183                 :            : 
     184                 :            :     /**
     185                 :            :      * Returns a font with the size scaled to match the format's size settings (including
     186                 :            :      * units and map unit scale) for a specified render context.
     187                 :            :      * \param context destination render context
     188                 :            :      * \param scaleFactor optional font size scaling factor. It is recommended to set this to
     189                 :            :      * QgsTextRenderer::FONT_WORKAROUND_SCALE and then manually scale painter devices or calculations
     190                 :            :      * based on the resultant font metrics. Failure to do so will result in poor quality text rendering
     191                 :            :      * at small font sizes.
     192                 :            :      * \returns font with scaled size
     193                 :            :      * \see font()
     194                 :            :      * \see size()
     195                 :            :      */
     196                 :            :     QFont scaledFont( const QgsRenderContext &context, double scaleFactor = 1.0 ) const;
     197                 :            : 
     198                 :            :     /**
     199                 :            :      * Sets the font used for rendering text. Note that the size of the font
     200                 :            :      * is not used, and setSize() should be called instead to explicitly set the size
     201                 :            :      * of rendered text.
     202                 :            :      * \param font desired font
     203                 :            :      * \see font()
     204                 :            :      * \see setNamedStyle()
     205                 :            :      * \see fromQFont()
     206                 :            :      */
     207                 :            :     void setFont( const QFont &font );
     208                 :            : 
     209                 :            :     /**
     210                 :            :      * Returns the named style for the font used for rendering text (e.g., "bold").
     211                 :            :      * \see setNamedStyle()
     212                 :            :      * \see font()
     213                 :            :      */
     214                 :            :     QString namedStyle() const;
     215                 :            : 
     216                 :            :     /**
     217                 :            :      * Sets the named style for the font used for rendering text.
     218                 :            :      * \param style named style, e.g., "bold"
     219                 :            :      * \see namedStyle()
     220                 :            :      * \see setFont()
     221                 :            :      */
     222                 :            :     void setNamedStyle( const QString &style );
     223                 :            : 
     224                 :            :     /**
     225                 :            :      * Returns the size for rendered text. Units are retrieved using sizeUnit().
     226                 :            :      * \see setSize()
     227                 :            :      * \see sizeUnit()
     228                 :            :      */
     229                 :            :     double size() const;
     230                 :            : 
     231                 :            :     /**
     232                 :            :      * Sets the size for rendered text.
     233                 :            :      * \param size size of rendered text. Units are set using setSizeUnit()
     234                 :            :      * \see size()
     235                 :            :      * \see setSizeUnit()
     236                 :            :      */
     237                 :            :     void setSize( double size );
     238                 :            : 
     239                 :            :     /**
     240                 :            :      * Returns the units for the size of rendered text.
     241                 :            :      * \see size()
     242                 :            :      * \see setSizeUnit()
     243                 :            :      * \see sizeMapUnitScale()
     244                 :            :      */
     245                 :            :     QgsUnitTypes::RenderUnit sizeUnit() const;
     246                 :            : 
     247                 :            :     /**
     248                 :            :      * Sets the units for the size of rendered text.
     249                 :            :      * \param unit size units
     250                 :            :      * \see setSize()
     251                 :            :      * \see sizeUnit()
     252                 :            :      * \see setSizeMapUnitScale()
     253                 :            :      */
     254                 :            :     void setSizeUnit( QgsUnitTypes::RenderUnit unit );
     255                 :            : 
     256                 :            :     /**
     257                 :            :      * Returns the map unit scale object for the size. This is only used if the
     258                 :            :      * sizeUnit() is set to QgsUnitTypes::RenderMapUnit.
     259                 :            :      * \see setSizeMapUnitScale()
     260                 :            :      * \see sizeUnit()
     261                 :            :      */
     262                 :            :     QgsMapUnitScale sizeMapUnitScale() const;
     263                 :            : 
     264                 :            :     /**
     265                 :            :      * Sets the map unit scale object for the size. This is only used if the
     266                 :            :      * sizeUnit() is set to QgsUnitTypes::RenderMapUnit.
     267                 :            :      * \see sizeMapUnitScale()
     268                 :            :      * \see setSizeUnit()
     269                 :            :      */
     270                 :            :     void setSizeMapUnitScale( const QgsMapUnitScale &scale );
     271                 :            : 
     272                 :            :     /**
     273                 :            :      * Returns the color that text will be rendered in.
     274                 :            :      * \see setColor()
     275                 :            :      */
     276                 :            :     QColor color() const;
     277                 :            : 
     278                 :            :     /**
     279                 :            :      * Sets the color that text will be rendered in.
     280                 :            :      * \param color text color
     281                 :            :      * \see color()
     282                 :            :      */
     283                 :            :     void setColor( const QColor &color );
     284                 :            : 
     285                 :            :     /**
     286                 :            :      * Returns the text's opacity. The opacity is a double value between 0 (fully transparent) and 1 (totally
     287                 :            :      * opaque).
     288                 :            :      * \see setOpacity()
     289                 :            :      */
     290                 :            :     double opacity() const;
     291                 :            : 
     292                 :            :     /**
     293                 :            :      * Sets the text's opacity.
     294                 :            :      * \param opacity opacity as a double value between 0 (fully transparent) and 1 (totally
     295                 :            :      * opaque)
     296                 :            :      * \see opacity()
     297                 :            :      */
     298                 :            :     void setOpacity( double opacity );
     299                 :            : 
     300                 :            :     /**
     301                 :            :      * Returns the blending mode used for drawing the text.
     302                 :            :      * \see setBlendMode()
     303                 :            :      */
     304                 :            :     QPainter::CompositionMode blendMode() const;
     305                 :            : 
     306                 :            :     /**
     307                 :            :      * Sets the blending mode used for drawing the text.
     308                 :            :      * \param mode blending mode
     309                 :            :      * \see blendMode()
     310                 :            :      */
     311                 :            :     void setBlendMode( QPainter::CompositionMode mode );
     312                 :            : 
     313                 :            :     /**
     314                 :            :      * Returns the line height for text. This is a number between
     315                 :            :      * 0.0 and 10.0 representing the leading between lines as a
     316                 :            :      * multiplier of line height.
     317                 :            :      * \see setLineHeight()
     318                 :            :      */
     319                 :            :     double lineHeight() const;
     320                 :            : 
     321                 :            :     /**
     322                 :            :      * Sets the line height for text.
     323                 :            :      * \param height a number between
     324                 :            :      * 0.0 and 10.0 representing the leading between lines as a
     325                 :            :      * multiplier of line height.
     326                 :            :      * \see lineHeight()
     327                 :            :      */
     328                 :            :     void setLineHeight( double height );
     329                 :            : 
     330                 :            :     /**
     331                 :            :      * Returns the orientation of the text.
     332                 :            :      * \see setOrientation()
     333                 :            :      * \since QGIS 3.10
     334                 :            :      */
     335                 :            :     TextOrientation orientation() const;
     336                 :            : 
     337                 :            :     /**
     338                 :            :      * Sets the \a orientation for the text.
     339                 :            :      * \see orientation()
     340                 :            :      * \since QGIS 3.10
     341                 :            :      */
     342                 :            :     void setOrientation( TextOrientation orientation );
     343                 :            : 
     344                 :            :     /**
     345                 :            :      * Returns the text capitalization style.
     346                 :            :      *
     347                 :            :      * \see setCapitalization()
     348                 :            :      * \since QGIS 3.16
     349                 :            :      */
     350                 :            :     QgsStringUtils::Capitalization capitalization() const;
     351                 :            : 
     352                 :            :     /**
     353                 :            :      * Sets the text \a capitalization style.
     354                 :            :      *
     355                 :            :      * \see capitalization()
     356                 :            :      * \since QGIS 3.16
     357                 :            :      */
     358                 :            :     void setCapitalization( QgsStringUtils::Capitalization capitalization );
     359                 :            : 
     360                 :            :     /**
     361                 :            :      * Returns TRUE if text should be treated as a HTML document and HTML tags should be used for formatting
     362                 :            :      * the rendered text.
     363                 :            :      *
     364                 :            :      * \warning Only a small subset of HTML formatting is supported. Currently this is restricted to:
     365                 :            :      *
     366                 :            :      * - text color formatting
     367                 :            :      * - strikethrough
     368                 :            :      * - underline
     369                 :            :      * - overline
     370                 :            :      *
     371                 :            :      * \see setAllowHtmlFormatting()
     372                 :            :      * \since QGIS 3.14
     373                 :            :      */
     374                 :            :     bool allowHtmlFormatting() const;
     375                 :            : 
     376                 :            :     /**
     377                 :            :      * Sets whether text should be treated as a HTML document and HTML tags should be used for formatting
     378                 :            :      * the rendered text.
     379                 :            :      *
     380                 :            :      * \warning Only a small subset of HTML formatting is supported. Currently this is restricted to:
     381                 :            :      *
     382                 :            :      * - text color formatting
     383                 :            :      * - strikethrough
     384                 :            :      * - underline
     385                 :            :      * - overline
     386                 :            :      *
     387                 :            :      * \see allowHtmlFormatting()
     388                 :            :      * \since QGIS 3.14
     389                 :            :      */
     390                 :            :     void setAllowHtmlFormatting( bool allow );
     391                 :            : 
     392                 :            :     /**
     393                 :            :      * Returns the background color for text previews.
     394                 :            :      * \see setPreviewBackgroundColor()
     395                 :            :      * \since QGIS 3.10
     396                 :            :      */
     397                 :            :     QColor previewBackgroundColor() const;
     398                 :            : 
     399                 :            :     /**
     400                 :            :      * Sets the background \a color that text will be rendered on for previews.
     401                 :            :      * \see previewBackgroundColor()
     402                 :            :      * \since QGIS 3.10
     403                 :            :      */
     404                 :            :     void setPreviewBackgroundColor( const QColor &color );
     405                 :            : 
     406                 :            :     /**
     407                 :            :      * Reads settings from a layer's custom properties (for QGIS 2.x projects).
     408                 :            :      * \param layer source vector layer
     409                 :            :      */
     410                 :            :     void readFromLayer( QgsVectorLayer *layer );
     411                 :            : 
     412                 :            :     /**
     413                 :            :      * Read settings from a DOM element.
     414                 :            :      * \see writeXml()
     415                 :            :      */
     416                 :            :     void readXml( const QDomElement &elem, const QgsReadWriteContext &context );
     417                 :            : 
     418                 :            :     /**
     419                 :            :      * Write settings into a DOM element.
     420                 :            :      * \see readXml()
     421                 :            :      */
     422                 :            :     QDomElement writeXml( QDomDocument &doc, const QgsReadWriteContext &context ) const;
     423                 :            : 
     424                 :            :     /**
     425                 :            :      * Returns new mime data representing the text format settings.
     426                 :            :      * Caller takes responsibility for deleting the returned object.
     427                 :            :      * \see fromMimeData()
     428                 :            :      */
     429                 :            :     QMimeData *toMimeData() const SIP_FACTORY;
     430                 :            : 
     431                 :            :     /**
     432                 :            :      * Returns a text format matching the settings from an input \a font.
     433                 :            :      * Unlike setFont(), this method also handles the size and size units
     434                 :            :      * from \a font.
     435                 :            :      * \see toQFont()
     436                 :            :      * \since QGIS 3.2
     437                 :            :      */
     438                 :            :     static QgsTextFormat fromQFont( const QFont &font );
     439                 :            : 
     440                 :            :     /**
     441                 :            :      * Returns a QFont matching the relevant settings from this text format.
     442                 :            :      * Unlike font(), this method also handles the size and size units
     443                 :            :      * from the text format.
     444                 :            :      * \see fromQFont()
     445                 :            :      * \since QGIS 3.2
     446                 :            :      */
     447                 :            :     QFont toQFont() const;
     448                 :            : 
     449                 :            :     /**
     450                 :            :      * Attempts to parse the provided mime \a data as a QgsTextFormat.
     451                 :            :      * If data can be parsed as a text format, \a ok will be set to TRUE.
     452                 :            :      * \see toMimeData()
     453                 :            :      */
     454                 :            :     static QgsTextFormat fromMimeData( const QMimeData *data, bool *ok SIP_OUT = nullptr );
     455                 :            : 
     456                 :            :     /**
     457                 :            :      * Returns TRUE if any component of the font format requires advanced effects
     458                 :            :      * such as blend modes, which require output in raster formats to be fully respected.
     459                 :            :      */
     460                 :            :     bool containsAdvancedEffects() const;
     461                 :            : 
     462                 :            :     /**
     463                 :            :      * Returns TRUE if the specified font was found on the system, or FALSE
     464                 :            :      * if the font was not found and a replacement was used instead.
     465                 :            :      * \see resolvedFontFamily()
     466                 :            :      */
     467                 :            :     bool fontFound() const { return mTextFontFound; }
     468                 :            : 
     469                 :            :     /**
     470                 :            :      * Returns the family for the resolved font, ie if the specified font
     471                 :            :      * was not found on the system this will return the name of the replacement
     472                 :            :      * font.
     473                 :            :      * \see fontFound()
     474                 :            :      */
     475                 :            :     QString resolvedFontFamily() const { return mTextFontFamily; }
     476                 :            : 
     477                 :            :     /**
     478                 :            :      * Returns a reference to the format's property collection, used for data defined overrides.
     479                 :            :      * \see setDataDefinedProperties()
     480                 :            :      * \since QGIS 3.10
     481                 :            :      */
     482                 :            :     QgsPropertyCollection &dataDefinedProperties();
     483                 :            : 
     484                 :            :     /**
     485                 :            :      * Returns a reference to the format's property collection, used for data defined overrides.
     486                 :            :      * \see setDataDefinedProperties()
     487                 :            :      * \note not available in Python bindings
     488                 :            :      * \since QGIS 3.10
     489                 :            :      */
     490                 :            :     const QgsPropertyCollection &dataDefinedProperties() const SIP_SKIP;
     491                 :            : 
     492                 :            :     /**
     493                 :            :      * Returns all field names referenced by the configuration (e.g. from data defined properties).
     494                 :            :      * \since QGIS 3.14
     495                 :            :      */
     496                 :            :     QSet<QString> referencedFields( const QgsRenderContext &context ) const;
     497                 :            : 
     498                 :            :     /**
     499                 :            :      * Sets the format's property collection, used for data defined overrides.
     500                 :            :      * \param collection property collection. Existing properties will be replaced.
     501                 :            :      * \see dataDefinedProperties()
     502                 :            :      * \since QGIS 3.10
     503                 :            :      */
     504                 :            :     void setDataDefinedProperties( const QgsPropertyCollection &collection );
     505                 :            : 
     506                 :            :     /**
     507                 :            :      * Updates the format by evaluating current values of data defined properties.
     508                 :            :      * \since QGIS 3.10
     509                 :            :      */
     510                 :            :     void updateDataDefinedProperties( QgsRenderContext &context );
     511                 :            : 
     512                 :            :     /**
     513                 :            :     * Returns a pixmap preview for a text \a format.
     514                 :            :     * \param format text format
     515                 :            :     * \param size target pixmap size
     516                 :            :     * \param previewText text to render in preview, or empty for default text
     517                 :            :     * \param padding space between icon edge and color ramp
     518                 :            :     * \since QGIS 3.10
     519                 :            :     */
     520                 :            :     static QPixmap textFormatPreviewPixmap( const QgsTextFormat &format, QSize size, const QString &previewText = QString(), int padding = 0 );
     521                 :            : 
     522                 :            :   private:
     523                 :            : 
     524                 :            :     QgsTextBufferSettings mBufferSettings;
     525                 :            :     QgsTextBackgroundSettings mBackgroundSettings;
     526                 :            :     QgsTextShadowSettings mShadowSettings;
     527                 :            :     QgsTextMaskSettings mMaskSettings;
     528                 :            : 
     529                 :            :     QString mTextFontFamily;
     530                 :            :     bool mTextFontFound = true;
     531                 :            : 
     532                 :            :     QSharedDataPointer<QgsTextSettingsPrivate> d;
     533                 :            : 
     534                 :            : };
     535                 :            : 
     536                 :          5 : Q_DECLARE_METATYPE( QgsTextFormat )
     537                 :            : 
     538                 :            : #endif // QGSTEXTFORMAT_H