Branch data     Line data    Source code

       1                 :            : /***************************************************************************
       2                 :            :                             qgslayoutitemscalebar.h
       3                 :            :                             ------------------------
       4                 :            :     begin                : November 2017
       5                 :            :     copyright            : (C) 2017 by Nyall Dawson
       6                 :            :     email                : nyall dot dawson at gmail dot com
       7                 :            :  ***************************************************************************/
       8                 :            : /***************************************************************************
       9                 :            :  *                                                                         *
      10                 :            :  *   This program is free software; you can redistribute it and/or modify  *
      11                 :            :  *   it under the terms of the GNU General Public License as published by  *
      12                 :            :  *   the Free Software Foundation; either version 2 of the License, or     *
      13                 :            :  *   (at your option) any later version.                                   *
      14                 :            :  *                                                                         *
      15                 :            :  ***************************************************************************/
      16                 :            : #ifndef QGSLAYOUTITEMSCALEBAR_H
      17                 :            : #define QGSLAYOUTITEMSCALEBAR_H
      18                 :            : 
      19                 :            : #include "qgis_core.h"
      20                 :            : #include "qgis_sip.h"
      21                 :            : #include "qgslayoutitem.h"
      22                 :            : #include "scalebar/qgsscalebarsettings.h"
      23                 :            : #include "scalebar/qgsscalebarrenderer.h"
      24                 :            : #include <QFont>
      25                 :            : #include <QPen>
      26                 :            : #include <QColor>
      27                 :            : 
      28                 :            : class QgsLayoutItemMap;
      29                 :            : 
      30                 :            : /**
      31                 :            :  * \ingroup core
      32                 :            :  * \brief A layout item subclass for scale bars.
      33                 :            :  * \since QGIS 3.0
      34                 :            :  */
      35                 :            : class CORE_EXPORT QgsLayoutItemScaleBar: public QgsLayoutItem
      36                 :            : {
      37                 :            :     Q_OBJECT
      38                 :            : 
      39                 :            :   public:
      40                 :            : 
      41                 :            :     /**
      42                 :            :      * Constructor for QgsLayoutItemScaleBar, with the specified parent \a layout.
      43                 :            :      */
      44                 :            :     QgsLayoutItemScaleBar( QgsLayout *layout );
      45                 :            : 
      46                 :            :     int type() const override;
      47                 :            :     QIcon icon() const override;
      48                 :            : 
      49                 :            :     /**
      50                 :            :      * Returns a new scale bar item for the specified \a layout.
      51                 :            :      *
      52                 :            :      * The caller takes responsibility for deleting the returned object.
      53                 :            :      */
      54                 :            :     static QgsLayoutItemScaleBar *create( QgsLayout *layout ) SIP_FACTORY;
      55                 :            :     QgsLayoutSize minimumSize() const override;
      56                 :            : 
      57                 :            :     /**
      58                 :            :      * Returns the number of segments included in the scalebar.
      59                 :            :      * \see setNumberOfSegments()
      60                 :            :      * \see numberOfSegmentsLeft()
      61                 :            :      */
      62                 :            :     int numberOfSegments() const { return mSettings.numberOfSegments(); }
      63                 :            : 
      64                 :            :     /**
      65                 :            :      * Sets the number of \a segments included in the scalebar.
      66                 :            :      * \see numberOfSegments()
      67                 :            :      * \see setNumberOfSegmentsLeft()
      68                 :            :      */
      69                 :            :     void setNumberOfSegments( int segments );
      70                 :            : 
      71                 :            :     /**
      72                 :            :      * Returns the number of segments included in the left part of the scalebar.
      73                 :            :      * \see setNumberOfSegmentsLeft()
      74                 :            :      * \see numberOfSegments()
      75                 :            :      */
      76                 :            :     int numberOfSegmentsLeft() const { return mSettings.numberOfSegmentsLeft(); }
      77                 :            : 
      78                 :            :     /**
      79                 :            :      * Sets the number of \a segments included in the left part of the scalebar.
      80                 :            :      * \see numberOfSegmentsLeft()
      81                 :            :      * \see setNumberOfSegments()
      82                 :            :      */
      83                 :            :     void setNumberOfSegmentsLeft( int segments );
      84                 :            : 
      85                 :            :     /**
      86                 :            :      * Returns the number of subdivisions for segments included in the right part of the scalebar (only used for some scalebar types).
      87                 :            :      *
      88                 :            :      * \note The number of subdivisions represents the number of subdivision segments, not the number of subdivision lines. E.g.
      89                 :            :      * if the number is 1 then NO subdivision lines will be shown.
      90                 :            :      *
      91                 :            :      * \see setNumberOfSubdivisions()
      92                 :            :      * \since QGIS 3.14
      93                 :            :      */
      94                 :            :     int numberOfSubdivisions()  const { return mSettings.numberOfSubdivisions(); }
      95                 :            : 
      96                 :            :     /**
      97                 :            :      * Sets the number of \a subdivisions for segments included in the right part of the scalebar (only used for some scalebar types).
      98                 :            :      *
      99                 :            :      * \note The number of subdivisions represents the number of subdivision segments, not the number of subdivision lines. E.g.
     100                 :            :      * if the number is 1 then NO subdivision lines will be shown.
     101                 :            :      *
     102                 :            :      * \see numberOfSubdivisions()
     103                 :            :      * \since QGIS 3.14
     104                 :            :      */
     105                 :            :     void setNumberOfSubdivisions( int subdivisions ) { mSettings.setNumberOfSubdivisions( subdivisions ); }
     106                 :            : 
     107                 :            :     /**
     108                 :            :      * Returns the scalebar subdivisions height (in millimeters) for segments included in the right part of the scalebar (only used for some scalebar types).
     109                 :            :      * \see setSubdivisionsHeight()
     110                 :            :      * \since QGIS 3.14
     111                 :            :      */
     112                 :            :     double subdivisionsHeight() const { return mSettings.subdivisionsHeight(); }
     113                 :            : 
     114                 :            :     /**
     115                 :            :      * Sets the scalebar subdivisions \a height (in millimeters) for segments included in the right part of the scalebar (only used for some scalebar types).
     116                 :            :      * \see subdivisionsHeight()
     117                 :            :      * \since QGIS 3.14
     118                 :            :      */
     119                 :            :     void setSubdivisionsHeight( double height ) { mSettings.setSubdivisionsHeight( height ); }
     120                 :            : 
     121                 :            :     /**
     122                 :            :      * Returns the number of scalebar units per segment.
     123                 :            :      * \see setUnitsPerSegment()
     124                 :            :      */
     125                 :            :     double unitsPerSegment() const { return mSettings.unitsPerSegment(); }
     126                 :            : 
     127                 :            :     /**
     128                 :            :      * Sets the number of scalebar \a units per segment.
     129                 :            :      * \see unitsPerSegment()
     130                 :            :      */
     131                 :            :     void setUnitsPerSegment( double units );
     132                 :            : 
     133                 :            :     /**
     134                 :            :      * Returns the size mode for the scale bar segments.
     135                 :            :      * \see setSegmentSizeMode()
     136                 :            :      * \see minimumBarWidth()
     137                 :            :      * \see maximumBarWidth()
     138                 :            :      */
     139                 :            :     QgsScaleBarSettings::SegmentSizeMode segmentSizeMode() const { return mSettings.segmentSizeMode(); }
     140                 :            : 
     141                 :            :     /**
     142                 :            :      * Sets the size \a mode for scale bar segments.
     143                 :            :      * \see segmentSizeMode()
     144                 :            :      * \see setMinimumBarWidth()
     145                 :            :      * \see setMaximumBarWidth()
     146                 :            :      */
     147                 :            :     void setSegmentSizeMode( QgsScaleBarSettings::SegmentSizeMode mode );
     148                 :            : 
     149                 :            :     /**
     150                 :            :      * Returns the minimum width (in millimeters) for scale bar segments. This
     151                 :            :      * property is only effective if the segmentSizeMode() is set
     152                 :            :      * to SegmentSizeFitWidth.
     153                 :            :      * \see segmentSizeMode()
     154                 :            :      * \see setMinimumBarWidth()
     155                 :            :      * \see maximumBarWidth()
     156                 :            :      */
     157                 :            :     double minimumBarWidth() const { return mSettings.minimumBarWidth(); }
     158                 :            : 
     159                 :            :     /**
     160                 :            :      * Sets the minimum \a width (in millimeters) for scale bar segments. This
     161                 :            :      * property is only effective if the segmentSizeMode() is set
     162                 :            :      * to SegmentSizeFitWidth.
     163                 :            :      * \see minimumBarWidth()
     164                 :            :      * \see setMaximumBarWidth()
     165                 :            :      * \see setSegmentSizeMode()
     166                 :            :      */
     167                 :            :     void setMinimumBarWidth( double minWidth );
     168                 :            : 
     169                 :            :     /**
     170                 :            :      * Returns the maximum width (in millimeters) for scale bar segments. This
     171                 :            :      * property is only effective if the segmentSizeMode() is set
     172                 :            :      * to SegmentSizeFitWidth.
     173                 :            :      * \see segmentSizeMode()
     174                 :            :      * \see setMaximumBarWidth()
     175                 :            :      * \see minimumBarWidth()
     176                 :            :      */
     177                 :            :     double maximumBarWidth() const { return mSettings.maximumBarWidth(); }
     178                 :            : 
     179                 :            :     /**
     180                 :            :      * Sets the maximum \a width (in millimeters) for scale bar segments. This
     181                 :            :      * property is only effective if the segmentSizeMode() is set
     182                 :            :      * to SegmentSizeFitWidth.
     183                 :            :      * \see minimumBarWidth()
     184                 :            :      * \see setMinimumBarWidth()
     185                 :            :      * \see setSegmentSizeMode()
     186                 :            :      */
     187                 :            :     void setMaximumBarWidth( double maxWidth );
     188                 :            : 
     189                 :            :     /**
     190                 :            :      * Returns the number of map units per scale bar unit used by the scalebar.
     191                 :            :      * \see setMapUnitsPerScaleBarUnit()
     192                 :            :      */
     193                 :            :     double mapUnitsPerScaleBarUnit() const { return mSettings.mapUnitsPerScaleBarUnit(); }
     194                 :            : 
     195                 :            :     /**
     196                 :            :      * Sets the number of map \a units per scale bar unit used by the scalebar.
     197                 :            :      * \see mapUnitsPerScaleBarUnit()
     198                 :            :      */
     199                 :          0 :     void setMapUnitsPerScaleBarUnit( double units ) { mSettings.setMapUnitsPerScaleBarUnit( units ); }
     200                 :            : 
     201                 :            :     /**
     202                 :            :      * Returns the label for units.
     203                 :            :      * \see setUnitLabel()
     204                 :            :      */
     205                 :            :     QString unitLabel() const { return mSettings.unitLabel(); }
     206                 :            : 
     207                 :            :     /**
     208                 :            :      * Sets the \a label for units.
     209                 :            :      * \see unitLabel()
     210                 :            :      */
     211                 :          0 :     void setUnitLabel( const QString &label ) { mSettings.setUnitLabel( label );}
     212                 :            : 
     213                 :            :     /**
     214                 :            :      * Returns the text format used for drawing text in the scalebar.
     215                 :            :      * \see setTextFormat()
     216                 :            :      * \since QGIS 3.2
     217                 :            :      */
     218                 :            :     QgsTextFormat textFormat() const;
     219                 :            : 
     220                 :            :     /**
     221                 :            :      * Sets the text \a format used for drawing text in the scalebar.
     222                 :            :      * \see textFormat()
     223                 :            :      * \since QGIS 3.2
     224                 :            :      */
     225                 :            :     void setTextFormat( const QgsTextFormat &format );
     226                 :            : 
     227                 :            : 
     228                 :            :     /**
     229                 :            :      * Returns the line symbol used to render the scalebar (only used for some scalebar types).
     230                 :            :      *
     231                 :            :      * Ownership is not transferred.
     232                 :            :      *
     233                 :            :      * \see setLineSymbol()
     234                 :            :      * \see divisionLineSymbol()
     235                 :            :      * \see subdivisionLineSymbol()
     236                 :            :      * \since QGIS 3.14
     237                 :            :      */
     238                 :            :     QgsLineSymbol *lineSymbol() const;
     239                 :            : 
     240                 :            :     /**
     241                 :            :      * Sets the line \a symbol used to render the scalebar (only used for some scalebar types). Ownership of \a symbol is
     242                 :            :      * transferred to the scalebar.
     243                 :            :      *
     244                 :            :      * \see lineSymbol()
     245                 :            :      * \see setDivisionLineSymbol()
     246                 :            :      * \see setSubdivisionLineSymbol()
     247                 :            :      * \since QGIS 3.14
     248                 :            :      */
     249                 :            :     void setLineSymbol( QgsLineSymbol *symbol SIP_TRANSFER );
     250                 :            : 
     251                 :            :     /**
     252                 :            :      * Returns the line symbol used to render the scalebar divisions (only used for some scalebar types).
     253                 :            :      *
     254                 :            :      * Ownership is not transferred.
     255                 :            :      *
     256                 :            :      * \see setDivisionLineSymbol()
     257                 :            :      * \see lineSymbol()
     258                 :            :      * \see subdivisionLineSymbol()
     259                 :            :      * \since QGIS 3.14
     260                 :            :      */
     261                 :            :     QgsLineSymbol *divisionLineSymbol() const;
     262                 :            : 
     263                 :            :     /**
     264                 :            :      * Sets the line \a symbol used to render the scalebar divisions (only used for some scalebar types). Ownership of \a symbol is
     265                 :            :      * transferred to the scalebar.
     266                 :            :      *
     267                 :            :      * \see divisionLineSymbol()
     268                 :            :      * \see setLineSymbol()
     269                 :            :      * \see setSubdivisionLineSymbol()
     270                 :            :      * \since QGIS 3.14
     271                 :            :      */
     272                 :            :     void setDivisionLineSymbol( QgsLineSymbol *symbol SIP_TRANSFER );
     273                 :            : 
     274                 :            :     /**
     275                 :            :      * Returns the line symbol used to render the scalebar subdivisions (only used for some scalebar types).
     276                 :            :      *
     277                 :            :      * Ownership is not transferred.
     278                 :            :      *
     279                 :            :      * \see setSubdivisionLineSymbol()
     280                 :            :      * \see lineSymbol()
     281                 :            :      * \see divisionLineSymbol()
     282                 :            :      * \since QGIS 3.14
     283                 :            :      */
     284                 :            :     QgsLineSymbol *subdivisionLineSymbol() const;
     285                 :            : 
     286                 :            :     /**
     287                 :            :      * Sets the line \a symbol used to render the scalebar subdivisions (only used for some scalebar types). Ownership of \a symbol is
     288                 :            :      * transferred to the scalebar.
     289                 :            :      *
     290                 :            :      * \see subdivisionLineSymbol()
     291                 :            :      * \see setLineSymbol()
     292                 :            :      * \see setDivisionLineSymbol()
     293                 :            :      * \since QGIS 3.14
     294                 :            :      */
     295                 :            :     void setSubdivisionLineSymbol( QgsLineSymbol *symbol SIP_TRANSFER );
     296                 :            : 
     297                 :            :     /**
     298                 :            :      * Returns the primary fill symbol used to render the scalebar (only used for some scalebar types).
     299                 :            :      *
     300                 :            :      * Ownership is not transferred.
     301                 :            :      *
     302                 :            :      * \see setFillSymbol()
     303                 :            :      * \see alternateFillSymbol()
     304                 :            :      * \since QGIS 3.14
     305                 :            :      */
     306                 :            :     QgsFillSymbol *fillSymbol() const;
     307                 :            : 
     308                 :            :     /**
     309                 :            :      * Sets the primary fill \a symbol used to render the scalebar (only used for some scalebar types). Ownership of \a symbol is
     310                 :            :      * transferred to the scalebar.
     311                 :            :      *
     312                 :            :      * \see fillSymbol()
     313                 :            :      * \see setAlternateFillSymbol()
     314                 :            :      * \since QGIS 3.14
     315                 :            :      */
     316                 :            :     void setFillSymbol( QgsFillSymbol *symbol SIP_TRANSFER );
     317                 :            : 
     318                 :            :     /**
     319                 :            :      * Returns the secondary fill symbol used to render the scalebar (only used for some scalebar types).
     320                 :            :      *
     321                 :            :      * Ownership is not transferred.
     322                 :            :      *
     323                 :            :      * \see setAlternateFillSymbol()
     324                 :            :      * \see fillSymbol()
     325                 :            :      * \since QGIS 3.14
     326                 :            :      */
     327                 :            :     QgsFillSymbol *alternateFillSymbol() const;
     328                 :            : 
     329                 :            :     /**
     330                 :            :      * Sets the secondary fill \a symbol used to render the scalebar (only used for some scalebar types). Ownership of \a symbol is
     331                 :            :      * transferred to the scalebar.
     332                 :            :      *
     333                 :            :      * \see alternateFillSymbol()
     334                 :            :      * \see setFillSymbol()
     335                 :            :      * \since QGIS 3.14
     336                 :            :      */
     337                 :            :     void setAlternateFillSymbol( QgsFillSymbol *symbol SIP_TRANSFER );
     338                 :            : 
     339                 :            :     /**
     340                 :            :      * Returns the font used for drawing text in the scalebar.
     341                 :            :      * \see setFont()
     342                 :            :      * \deprecated use textFormat() instead
     343                 :            :      */
     344                 :            :     Q_DECL_DEPRECATED QFont font() const SIP_DEPRECATED;
     345                 :            : 
     346                 :            :     /**
     347                 :            :      * Sets the \a font used for drawing text in the scalebar.
     348                 :            :      * \see font()
     349                 :            :      * \deprecated use setTextFormat() instead
     350                 :            :      */
     351                 :            :     Q_DECL_DEPRECATED void setFont( const QFont &font ) SIP_DEPRECATED;
     352                 :            : 
     353                 :            :     /**
     354                 :            :      * Returns the color used for drawing text in the scalebar.
     355                 :            :      * \see setFontColor()
     356                 :            :      * \see font()
     357                 :            :      * \deprecated use textFormat() instead
     358                 :            :      */
     359                 :            :     Q_DECL_DEPRECATED QColor fontColor() const SIP_DEPRECATED;
     360                 :            : 
     361                 :            :     /**
     362                 :            :      * Sets the \a color used for drawing text in the scalebar.
     363                 :            :      * \see fontColor()
     364                 :            :      * \see setFont()
     365                 :            :      * \deprecated use setTextFormat() instead
     366                 :            :      */
     367                 :            :     Q_DECL_DEPRECATED void setFontColor( const QColor &color ) SIP_DEPRECATED;
     368                 :            : 
     369                 :            :     /**
     370                 :            :      * Returns the color used for fills in the scalebar.
     371                 :            :      * \see setFillColor()
     372                 :            :      * \see fillColor2()
     373                 :            :      * \deprecated use fillSymbol() instead
     374                 :            :      */
     375                 :            :     Q_DECL_DEPRECATED QColor fillColor() const SIP_DEPRECATED;
     376                 :            : 
     377                 :            :     /**
     378                 :            :      * Sets the \a color used for fills in the scalebar.
     379                 :            :      * \see fillColor()
     380                 :            :      * \see setFillColor2()
     381                 :            :      * \deprecated use setFillSymbol() instead
     382                 :            :      */
     383                 :            :     Q_DECL_DEPRECATED void setFillColor( const QColor &color ) SIP_DEPRECATED;
     384                 :            : 
     385                 :            :     /**
     386                 :            :      * Returns the secondary color used for fills in the scalebar.
     387                 :            :      * \see setFillColor2()
     388                 :            :      * \see fillColor()
     389                 :            :      * \deprecated use alternateFillSymbol() instead
     390                 :            :      */
     391                 :            :     Q_DECL_DEPRECATED QColor fillColor2() const SIP_DEPRECATED;
     392                 :            : 
     393                 :            :     /**
     394                 :            :      * Sets the secondary \a color used for fills in the scalebar.
     395                 :            :      * \see fillColor2()
     396                 :            :      * \see setFillColor2()
     397                 :            :      * \deprecated use setAlternateFillSymbol() instead
     398                 :            :      */
     399                 :            :     Q_DECL_DEPRECATED void setFillColor2( const QColor &color ) SIP_DEPRECATED;
     400                 :            : 
     401                 :            :     /**
     402                 :            :      * Returns the color used for lines in the scalebar.
     403                 :            :      * \see setLineColor()
     404                 :            :      * \deprecated use lineSymbol() instead
     405                 :            :      */
     406                 :            :     Q_DECL_DEPRECATED QColor lineColor() const SIP_DEPRECATED;
     407                 :            : 
     408                 :            :     /**
     409                 :            :      * Sets the \a color used for lines in the scalebar.
     410                 :            :      * \see lineColor()
     411                 :            :      * \deprecated use setLineSymbol() instead
     412                 :            :      */
     413                 :            :     Q_DECL_DEPRECATED void setLineColor( const QColor &color ) SIP_DEPRECATED;
     414                 :            : 
     415                 :            :     /**
     416                 :            :      * Returns the line width in millimeters for lines in the scalebar.
     417                 :            :      * \see setLineWidth()
     418                 :            :      * \deprecated use lineSymbol() instead
     419                 :            :      */
     420                 :            :     Q_DECL_DEPRECATED double lineWidth() const SIP_DEPRECATED;
     421                 :            : 
     422                 :            :     /**
     423                 :            :      * Sets the line \a width in millimeters for lines in the scalebar.
     424                 :            :      * \see lineWidth()
     425                 :            :      * \deprecated use setLineSymbol() instead
     426                 :            :      */
     427                 :            :     Q_DECL_DEPRECATED void setLineWidth( double width ) SIP_DEPRECATED;
     428                 :            : 
     429                 :            :     /**
     430                 :            :      * Returns the pen used for drawing outlines in the scalebar.
     431                 :            :      * \see brush()
     432                 :            :      * \deprecated use lineSymbol() instead
     433                 :            :      */
     434                 :            :     Q_DECL_DEPRECATED QPen pen() const SIP_DEPRECATED;
     435                 :            : 
     436                 :            :     /**
     437                 :            :      * Returns the primary brush for the scalebar.
     438                 :            :      * \returns QBrush used for filling the scalebar
     439                 :            :      * \see brush2
     440                 :            :      * \see pen
     441                 :            :      * \deprecated use fillSymbol() instead
     442                 :            :      */
     443                 :            :     Q_DECL_DEPRECATED QBrush brush() const SIP_DEPRECATED;
     444                 :            : 
     445                 :            :     /**
     446                 :            :      * Returns the secondary brush for the scalebar. This is used for alternating color style scalebars, such
     447                 :            :      * as single and double box styles.
     448                 :            :      * \returns QBrush used for secondary color areas
     449                 :            :      * \see brush
     450                 :            :      * \deprecated use alternateFillSymbol() instead
     451                 :            :      */
     452                 :            :     Q_DECL_DEPRECATED QBrush brush2() const SIP_DEPRECATED;
     453                 :            : 
     454                 :            :     /**
     455                 :            :      * Returns the scalebar height (in millimeters).
     456                 :            :      * \see setHeight()
     457                 :            :      */
     458                 :            :     double height() const { return mSettings.height(); }
     459                 :            : 
     460                 :            :     /**
     461                 :            :      * Sets the scalebar \a height (in millimeters).
     462                 :            :      * \see height()
     463                 :            :      */
     464                 :          0 :     void setHeight( double height ) { mSettings.setHeight( height ); }
     465                 :            : 
     466                 :            :     /**
     467                 :            :      * Sets the \a map item linked to the scalebar.
     468                 :            :      * \see linkedMap()
     469                 :            :      */
     470                 :            :     void setLinkedMap( QgsLayoutItemMap *map );
     471                 :            : 
     472                 :            :     /**
     473                 :            :      * Returns the map item linked to the scalebar.
     474                 :            :      * \see setLinkedMap()
     475                 :            :      */
     476                 :            :     QgsLayoutItemMap *linkedMap() const { return mMap; }
     477                 :            : 
     478                 :            :     /**
     479                 :            :      * Returns the spacing (in millimeters) between labels and the scalebar.
     480                 :            :      * \see setLabelBarSpace()
     481                 :            :      */
     482                 :            :     double labelBarSpace() const { return mSettings.labelBarSpace(); }
     483                 :            : 
     484                 :            :     /**
     485                 :            :      * Sets the spacing (in millimeters) between labels and the scalebar.
     486                 :            :      * \see labelBarSpace()
     487                 :            :      */
     488                 :          0 :     void setLabelBarSpace( double space ) {mSettings.setLabelBarSpace( space );}
     489                 :            : 
     490                 :            :     /**
     491                 :            :      * Returns the spacing (margin) between the scalebar box and content in millimeters.
     492                 :            :      * \see setBoxContentSpace()
     493                 :            :      */
     494                 :            :     double boxContentSpace() const { return mSettings.boxContentSpace(); }
     495                 :            : 
     496                 :            :     /**
     497                 :            :      * Sets the \a space (margin) between the scalebar box and content in millimeters.
     498                 :            :      * \see boxContentSpace()
     499                 :            :      */
     500                 :            :     void setBoxContentSpace( double space );
     501                 :            : 
     502                 :            :     /**
     503                 :            :      * Returns the vertical placement of text labels.
     504                 :            :      * \see setLabelVerticalPlacement()
     505                 :            :      * \since QGIS 3.10
     506                 :            :      */
     507                 :            :     QgsScaleBarSettings::LabelVerticalPlacement labelVerticalPlacement() const { return mSettings.labelVerticalPlacement(); }
     508                 :            : 
     509                 :            :     /**
     510                 :            :      * Sets the vertical \a placement of text labels.
     511                 :            :      * \see labelVerticalPlacement()
     512                 :            :      * \since QGIS 3.10
     513                 :            :      */
     514                 :            :     void setLabelVerticalPlacement( QgsScaleBarSettings::LabelVerticalPlacement placement );
     515                 :            : 
     516                 :            :     /**
     517                 :            :      * Returns the horizontal placement of text labels.
     518                 :            :      * \see setLabelHorizontalPlacement()
     519                 :            :      * \since QGIS 3.10
     520                 :            :      */
     521                 :            :     QgsScaleBarSettings::LabelHorizontalPlacement labelHorizontalPlacement() const { return mSettings.labelHorizontalPlacement(); }
     522                 :            : 
     523                 :            :     /**
     524                 :            :      * Sets the horizontal \a placement of text labels.
     525                 :            :      * \see labelHorizontalPlacement()
     526                 :            :      * \since QGIS 3.10
     527                 :            :      */
     528                 :            :     void setLabelHorizontalPlacement( QgsScaleBarSettings::LabelHorizontalPlacement placement );
     529                 :            : 
     530                 :            :     /**
     531                 :            :      * Returns the scalebar alignment.
     532                 :            :      * \see setAlignment()
     533                 :            :      */
     534                 :            :     QgsScaleBarSettings::Alignment alignment() const { return mSettings.alignment(); }
     535                 :            : 
     536                 :            :     /**
     537                 :            :      * Sets the scalebar \a alignment.
     538                 :            :      * \see alignment()
     539                 :            :      */
     540                 :            :     void setAlignment( QgsScaleBarSettings::Alignment alignment );
     541                 :            : 
     542                 :            :     /**
     543                 :            :      * Returns the distance units used by the scalebar.
     544                 :            :      * \see setUnits()
     545                 :            :      */
     546                 :            :     QgsUnitTypes::DistanceUnit units() const { return mSettings.units(); }
     547                 :            : 
     548                 :            :     /**
     549                 :            :      * Sets the distance \a units used by the scalebar.
     550                 :            :      * \see units()
     551                 :            :      */
     552                 :            :     void setUnits( QgsUnitTypes::DistanceUnit units );
     553                 :            : 
     554                 :            :     /**
     555                 :            :      * Returns the join style used for drawing lines in the scalebar.
     556                 :            :      * \see setLineJoinStyle()
     557                 :            :      * \deprecated use lineSymbol() instead
     558                 :            :      */
     559                 :            :     Q_DECL_DEPRECATED Qt::PenJoinStyle lineJoinStyle() const SIP_DEPRECATED;
     560                 :            : 
     561                 :            :     /**
     562                 :            :      * Sets the join \a style used when drawing the lines in the scalebar
     563                 :            :      * \see lineJoinStyle()
     564                 :            :      * \deprecated use setLineSymbol() instead
     565                 :            :      */
     566                 :            :     Q_DECL_DEPRECATED void setLineJoinStyle( Qt::PenJoinStyle style ) SIP_DEPRECATED;
     567                 :            : 
     568                 :            :     /**
     569                 :            :      * Returns the cap style used for drawing lines in the scalebar.
     570                 :            :      * \see setLineCapStyle()
     571                 :            :      * \deprecated use lineSymbol() instead
     572                 :            :      */
     573                 :            :     Q_DECL_DEPRECATED Qt::PenCapStyle lineCapStyle() const SIP_DEPRECATED;
     574                 :            : 
     575                 :            :     /**
     576                 :            :      * Sets the cap \a style used when drawing the lines in the scalebar.
     577                 :            :      * \see lineCapStyle()
     578                 :            :      * \deprecated use setLineSymbol() instead
     579                 :            :      */
     580                 :            :     Q_DECL_DEPRECATED void setLineCapStyle( Qt::PenCapStyle style ) SIP_DEPRECATED;
     581                 :            : 
     582                 :            :     /**
     583                 :            :      * Applies the default scalebar settings to the scale bar.
     584                 :            :      * \see applyDefaultSize()
     585                 :            :      */
     586                 :            :     void applyDefaultSettings();
     587                 :            : 
     588                 :            :     /**
     589                 :            :      * Applies any default settings relating to the specified \a renderer to the item.
     590                 :            :      *
     591                 :            :      * Returns TRUE if settings were applied.
     592                 :            :      *
     593                 :            :      * \since QGIS 3.14
     594                 :            :      */
     595                 :            :     bool applyDefaultRendererSettings( QgsScaleBarRenderer *renderer );
     596                 :            : 
     597                 :            :     /**
     598                 :            :      * Attempts to guess the most reasonable unit choice for the scalebar, given
     599                 :            :      * the current linked map's scale.
     600                 :            :      *
     601                 :            :      * This method also considers the linked map's CRS, in order to determine if
     602                 :            :      * metric or imperial units are more appropriate.
     603                 :            :      */
     604                 :            :     QgsUnitTypes::DistanceUnit guessUnits() const;
     605                 :            : 
     606                 :            :     /**
     607                 :            :      * Applies the default size to the scale bar (scale bar 1/5 of map item width)
     608                 :            :      * \see applyDefaultSettings()
     609                 :            :      */
     610                 :            :     void applyDefaultSize( QgsUnitTypes::DistanceUnit units = QgsUnitTypes::DistanceMeters );
     611                 :            : 
     612                 :            :     /**
     613                 :            :      * Resizes the scale bar to its minimum width, without changing the height.
     614                 :            :      */
     615                 :            :     void resizeToMinimumWidth();
     616                 :            : 
     617                 :            :     /**
     618                 :            :      * Sets the scale bar style by \a name.
     619                 :            :      *
     620                 :            :      * The \a name parameter gives the (untranslated) style name.
     621                 :            :      * Possibilities are: 'Single Box', 'Double Box', 'Line Ticks Middle',
     622                 :            :      * 'Line Ticks Down', 'Line Ticks Up', 'Numeric'
     623                 :            :      *
     624                 :            :      * \see style()
     625                 :            :     */
     626                 :            :     void setStyle( const QString &name );
     627                 :            : 
     628                 :            :     /**
     629                 :            :      * Returns the scale bar style name.
     630                 :            :      * \see setStyle()
     631                 :            :      */
     632                 :            :     QString style() const;
     633                 :            : 
     634                 :            :     /**
     635                 :            :      * Returns the numeric format used for numbers in the scalebar.
     636                 :            :      *
     637                 :            :      * \see setNumericFormat()
     638                 :            :      * \since QGIS 3.12
     639                 :            :      */
     640                 :            :     const QgsNumericFormat *numericFormat() const;
     641                 :            : 
     642                 :            :     /**
     643                 :            :      * Sets the numeric \a format used for numbers in the scalebar.
     644                 :            :      *
     645                 :            :      * Ownership of \a format is transferred to the scalebar.
     646                 :            :      *
     647                 :            :      * \see numericFormat()
     648                 :            :      * \since QGIS 3.12
     649                 :            :      */
     650                 :            :     void setNumericFormat( QgsNumericFormat *format SIP_TRANSFER );
     651                 :            : 
     652                 :            :     /**
     653                 :            :      * Adjusts the scale bar box size and updates the item.
     654                 :            :      */
     655                 :            :     void update();
     656                 :            : 
     657                 :            :     void refreshDataDefinedProperty( QgsLayoutObject::DataDefinedProperty property = QgsLayoutObject::AllProperties ) override;
     658                 :            :     void finalizeRestoreFromXml() override;
     659                 :            :     bool accept( QgsStyleEntityVisitorInterface *visitor ) const override;
     660                 :            :     ExportLayerBehavior exportLayerBehavior() const override;
     661                 :            : 
     662                 :            :   protected:
     663                 :            : 
     664                 :            :     void draw( QgsLayoutItemRenderContext &context ) override;
     665                 :            :     bool writePropertiesToElement( QDomElement &element, QDomDocument &document, const QgsReadWriteContext &context ) const override;
     666                 :            :     bool readPropertiesFromElement( const QDomElement &element, const QDomDocument &document, const QgsReadWriteContext &context ) override;
     667                 :            : 
     668                 :            :   private slots:
     669                 :            :     void updateScale();
     670                 :            :     void disconnectCurrentMap();
     671                 :            : 
     672                 :            :   private:
     673                 :            : 
     674                 :            :     //! Linked map
     675                 :            :     QgsLayoutItemMap *mMap = nullptr;
     676                 :            :     QString mMapUuid;
     677                 :            : 
     678                 :            :     QgsScaleBarSettings mSettings;
     679                 :            : 
     680                 :            :     //! Scalebar style
     681                 :            :     std::unique_ptr< QgsScaleBarRenderer > mStyle;
     682                 :            : 
     683                 :            :     //! Width of a segment (in mm)
     684                 :            :     double mSegmentMillimeters = 0.0;
     685                 :            : 
     686                 :            :     //! Calculates with of a segment in mm and stores it in mSegmentMillimeters
     687                 :            :     void refreshSegmentMillimeters();
     688                 :            : 
     689                 :            :     //! Returns diagonal of layout map in selected units (map units / meters / feet / nautical miles)
     690                 :            :     double mapWidth() const;
     691                 :            : 
     692                 :            :     QgsScaleBarRenderer::ScaleBarContext createScaleContext() const;
     693                 :            : 
     694                 :            :     friend class QgsCompositionConverter;
     695                 :            : 
     696                 :            : };
     697                 :            : 
     698                 :            : #endif //QGSLAYOUTITEMSCALEBAR_H
     699                 :            : 
     700                 :            :