Branch data     Line data    Source code

       1                 :            : /***************************************************************************
       2                 :            :     qgslabelingenginesettings.h
       3                 :            :     ---------------------
       4                 :            :     begin                : April 2017
       5                 :            :     copyright            : (C) 2017 by Martin Dobias
       6                 :            :     email                : wonder dot sk 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                 :            : #ifndef QGSLABELINGENGINESETTINGS_H
      16                 :            : #define QGSLABELINGENGINESETTINGS_H
      17                 :            : 
      18                 :            : #include "qgis_core.h"
      19                 :            : #include "qgis_sip.h"
      20                 :            : #include "qgsrendercontext.h"
      21                 :            : #include <QFlags>
      22                 :            : 
      23                 :            : class QgsProject;
      24                 :            : 
      25                 :            : /**
      26                 :            :  * \ingroup core
      27                 :            :  * \brief Stores global configuration for labeling engine
      28                 :            :  * \since QGIS 3.0
      29                 :            :  */
      30                 :          8 : class CORE_EXPORT QgsLabelingEngineSettings
      31                 :            : {
      32                 :            :   public:
      33                 :            :     //! Various flags that affect drawing and placement of labels
      34                 :            :     enum Flag
      35                 :            :     {
      36                 :            :       UseAllLabels          = 1 << 1,  //!< Whether to draw all labels even if there would be collisions
      37                 :            :       UsePartialCandidates  = 1 << 2,  //!< Whether to use also label candidates that are partially outside of the map view
      38                 :            :       // TODO QGIS 4.0: remove
      39                 :            :       RenderOutlineLabels   = 1 << 3,  //!< Whether to render labels as text or outlines. Deprecated and of QGIS 3.4.3 - use defaultTextRenderFormat() instead.
      40                 :            :       DrawLabelRectOnly     = 1 << 4,  //!< Whether to only draw the label rect and not the actual label text (used for unit tests)
      41                 :            :       DrawCandidates        = 1 << 5,  //!< Whether to draw rectangles of generated candidates (good for debugging)
      42                 :            :       DrawUnplacedLabels    = 1 << 6,  //!< Whether to render unplaced labels as an indicator/warning for users
      43                 :            :     };
      44                 :            :     Q_DECLARE_FLAGS( Flags, Flag )
      45                 :            : 
      46                 :            :     // TODO QGIS 4 - remove
      47                 :            : 
      48                 :            :     /**
      49                 :            :      * Search methods in the PAL library to remove colliding labels
      50                 :            :      * (methods have different processing speed and number of labels placed)
      51                 :            :      */
      52                 :            :     enum Search
      53                 :            :     {
      54                 :            :       Chain,
      55                 :            :       Popmusic_Tabu,
      56                 :            :       Popmusic_Chain,
      57                 :            :       Popmusic_Tabu_Chain,
      58                 :            :       Falp
      59                 :            :     };
      60                 :            : 
      61                 :            :     /**
      62                 :            :      * Placement engine version.
      63                 :            :      *
      64                 :            :      * \since QGIS 3.10.2
      65                 :            :      */
      66                 :            :     enum PlacementEngineVersion
      67                 :            :     {
      68                 :            :       PlacementEngineVersion1, //!< Version 1, matches placement from QGIS <= 3.10.1
      69                 :            :       PlacementEngineVersion2, //!< Version 2 (default for new projects since QGIS 3.12)
      70                 :            :     };
      71                 :            : 
      72                 :            :     QgsLabelingEngineSettings();
      73                 :            : 
      74                 :            :     //! Returns the configuration to the defaults
      75                 :            :     void clear();
      76                 :            : 
      77                 :            :     //! Sets flags of the labeling engine
      78                 :            :     void setFlags( Flags flags ) { mFlags = flags; }
      79                 :            :     //! Gets flags of the labeling engine
      80                 :          0 :     Flags flags() const { return mFlags; }
      81                 :            :     //! Test whether a particular flag is enabled
      82                 :          0 :     bool testFlag( Flag f ) const { return mFlags.testFlag( f ); }
      83                 :            :     //! Sets whether a particual flag is enabled
      84                 :          0 :     void setFlag( Flag f, bool enabled = true ) { if ( enabled ) mFlags |= f; else mFlags &= ~f; }
      85                 :            : 
      86                 :            :     /**
      87                 :            :      * Returns the maximum number of line label candidate positions per centimeter.
      88                 :            :      *
      89                 :            :      * \see setMaximumLineCandidatesPerCm()
      90                 :            :      * \since QGIS 3.12
      91                 :            :      */
      92                 :          0 :     double maximumLineCandidatesPerCm() const { return mMaxLineCandidatesPerCm; }
      93                 :            : 
      94                 :            :     /**
      95                 :            :      * Sets the maximum number of line label \a candidates per centimeter.
      96                 :            :      *
      97                 :            :      * \see maximumLineCandidatesPerCm()
      98                 :            :      * \since QGIS 3.12
      99                 :            :      */
     100                 :            :     void setMaximumLineCandidatesPerCm( double candidates ) { mMaxLineCandidatesPerCm = candidates; }
     101                 :            : 
     102                 :            :     /**
     103                 :            :      * Returns the maximum number of polygon label candidate positions per centimeter squared.
     104                 :            :      *
     105                 :            :      * \see setMaximumPolygonCandidatesPerCmSquared()
     106                 :            :      * \since QGIS 3.12
     107                 :            :      */
     108                 :          0 :     double maximumPolygonCandidatesPerCmSquared() const { return mMaxPolygonCandidatesPerCmSquared; }
     109                 :            : 
     110                 :            :     /**
     111                 :            :      * Sets the maximum number of polygon label \a candidates per centimeter squared.
     112                 :            :      *
     113                 :            :      * \see maximumPolygonCandidatesPerCmSquared()
     114                 :            :      * \since QGIS 3.12
     115                 :            :      */
     116                 :            :     void setMaximumPolygonCandidatesPerCmSquared( double candidates ) { mMaxPolygonCandidatesPerCmSquared = candidates; }
     117                 :            : 
     118                 :            :     /**
     119                 :            :      * Gets number of candidate positions that will be generated for each label feature.
     120                 :            :      * \deprecated since QGIS 3.12 use maximumPolygonCandidatesPerCmSquared() and maximumLineCandidatesPerCm() instead.
     121                 :            :      */
     122                 :            :     Q_DECL_DEPRECATED void numCandidatePositions( int &candPoint, int &candLine, int &candPolygon ) const SIP_DEPRECATED
     123                 :            :     {
     124                 :            :       Q_UNUSED( candPoint )
     125                 :            :       Q_UNUSED( candLine )
     126                 :            :       Q_UNUSED( candPolygon )
     127                 :            :     }
     128                 :            : 
     129                 :            :     /**
     130                 :            :      * Sets the number of candidate positions that will be generated for each label feature.
     131                 :            :      * \deprecated since QGIS 3.12 use setMaximumPolygonCandidatesPerCmSquared() and setMaximumLineCandidatesPerCm() instead.
     132                 :            :      */
     133                 :            :     Q_DECL_DEPRECATED void setNumCandidatePositions( int candPoint, int candLine, int candPolygon ) SIP_DEPRECATED
     134                 :            :     {
     135                 :            :       Q_UNUSED( candPoint )
     136                 :            :       Q_UNUSED( candLine )
     137                 :            :       Q_UNUSED( candPolygon )
     138                 :            :     }
     139                 :            : 
     140                 :            :     /**
     141                 :            :      * Used to set which search method to use for removal collisions between labels
     142                 :            :      * \deprecated since QGIS 3.10 - Chain is always used.
     143                 :            :      */
     144                 :            :     Q_DECL_DEPRECATED void setSearchMethod( Search s ) SIP_DEPRECATED { Q_UNUSED( s ) }
     145                 :            : 
     146                 :            :     /**
     147                 :            :      * Which search method to use for removal collisions between labels
     148                 :            :      * \deprecated since QGIS 3.10 - Chain is always used.
     149                 :            :      */
     150                 :            :     Q_DECL_DEPRECATED Search searchMethod() const SIP_DEPRECATED { return Chain; }
     151                 :            : 
     152                 :            :     //! Read configuration of the labeling engine from a project
     153                 :            :     void readSettingsFromProject( QgsProject *project );
     154                 :            :     //! Write configuration of the labeling engine to a project
     155                 :            :     void writeSettingsToProject( QgsProject *project );
     156                 :            : 
     157                 :            :     // TODO QGIS 4.0: In reality the text render format settings don't only apply to labels, but also
     158                 :            :     // ANY text rendered using QgsTextRenderer (including some non-label text items in layouts).
     159                 :            :     // These methods should possibly be moved out of here and into the general QgsProject settings.
     160                 :            : 
     161                 :            :     /**
     162                 :            :      * Returns the default text rendering format for the labels.
     163                 :            :      *
     164                 :            :      * \see setDefaultTextRenderFormat()
     165                 :            :      * \since QGIS 3.4.3
     166                 :            :      */
     167                 :          0 :     QgsRenderContext::TextRenderFormat defaultTextRenderFormat() const
     168                 :            :     {
     169                 :          0 :       return mDefaultTextRenderFormat;
     170                 :            :     }
     171                 :            : 
     172                 :            :     /**
     173                 :            :      * Sets the default text rendering \a format for the labels.
     174                 :            :      *
     175                 :            :      * \see defaultTextRenderFormat()
     176                 :            :      * \since QGIS 3.4.3
     177                 :            :      */
     178                 :          0 :     void setDefaultTextRenderFormat( QgsRenderContext::TextRenderFormat format )
     179                 :            :     {
     180                 :          0 :       mDefaultTextRenderFormat = format;
     181                 :          0 :     }
     182                 :            : 
     183                 :            :     /**
     184                 :            :      * Returns the color to use when rendering unplaced labels.
     185                 :            :      *
     186                 :            :      * \see setUnplacedLabelColor()
     187                 :            :      * \since QGIS 3.10
     188                 :            :      */
     189                 :            :     QColor unplacedLabelColor() const;
     190                 :            : 
     191                 :            :     /**
     192                 :            :      * Sets the \a color to use when rendering unplaced labels.
     193                 :            :      *
     194                 :            :      * \see unplacedLabelColor()
     195                 :            :      * \since QGIS 3.10
     196                 :            :      */
     197                 :            :     void setUnplacedLabelColor( const QColor &color );
     198                 :            : 
     199                 :            :     /**
     200                 :            :      * Returns the placement engine version, which dictates how the label placement problem is solved.
     201                 :            :      *
     202                 :            :      * \see setPlacementVersion()
     203                 :            :      * \since QGIS 3.10.2
     204                 :            :      */
     205                 :            :     PlacementEngineVersion placementVersion() const;
     206                 :            : 
     207                 :            :     /**
     208                 :            :      * Sets the placement engine \a version, which dictates how the label placement problem is solved.
     209                 :            :      *
     210                 :            :      * \see placementVersion()
     211                 :            :      * \since QGIS 3.10.2
     212                 :            :      */
     213                 :            :     void setPlacementVersion( PlacementEngineVersion version );
     214                 :            : 
     215                 :            :   private:
     216                 :            :     //! Flags
     217                 :            :     Flags mFlags;
     218                 :            :     //! search method to use for removal collisions between labels
     219                 :            :     Search mSearchMethod = Chain;
     220                 :            : 
     221                 :            :     // maximum density of line/polygon candidates per mm
     222                 :            :     double mMaxLineCandidatesPerCm = 5;
     223                 :            :     double mMaxPolygonCandidatesPerCmSquared = 2.5;
     224                 :            : 
     225                 :            :     QColor mUnplacedLabelColor = QColor( 255, 0, 0 );
     226                 :            : 
     227                 :            :     PlacementEngineVersion mPlacementVersion = PlacementEngineVersion2;
     228                 :            : 
     229                 :            :     QgsRenderContext::TextRenderFormat mDefaultTextRenderFormat = QgsRenderContext::TextFormatAlwaysOutlines;
     230                 :            : 
     231                 :            : };
     232                 :            : 
     233                 :            : Q_DECLARE_OPERATORS_FOR_FLAGS( QgsLabelingEngineSettings::Flags )
     234                 :            : 
     235                 :            : #endif // QGSLABELINGENGINESETTINGS_H