1 /***************************************************************************
2   qgstextbuffersettings.h
3   -----------------
4    begin                : May 2020
5    copyright            : (C) 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 
17 #ifndef QGSTEXTBUFFERSETTINGS_H
18 #define QGSTEXTBUFFERSETTINGS_H
19 
20 #include "qgis_sip.h"
21 #include "qgis_core.h"
22 #include "qgsmapunitscale.h"
23 #include "qgsunittypes.h"
24 
25 #include <QSharedData>
26 #include <QPainter>
27 #include <QDomElement>
28 
29 class QgsReadWriteContext;
30 class QgsTextBufferSettingsPrivate;
31 class QgsVectorLayer;
32 class QgsPaintEffect;
33 class QgsPropertyCollection;
34 
35 /**
36  * \class QgsTextBufferSettings
37   * \ingroup core
38   * \brief Container for settings relating to a text buffer.
39   * \note QgsTextBufferSettings objects are implicitly shared.
40   * \since QGIS 3.0
41  */
42 class CORE_EXPORT QgsTextBufferSettings
43 {
44   public:
45 
46     QgsTextBufferSettings();
47 
48     /**
49      * Copy constructor.
50      * \param other source settings
51      */
52     QgsTextBufferSettings( const QgsTextBufferSettings &other );
53 
54     /**
55      * Copy constructor.
56      * \param other source QgsTextBufferSettings
57      */
58     QgsTextBufferSettings &operator=( const QgsTextBufferSettings &other );
59 
60     ~QgsTextBufferSettings();
61 
62     bool operator==( const QgsTextBufferSettings &other ) const;
63     bool operator!=( const QgsTextBufferSettings &other ) const;
64 
65     /**
66      * Returns whether the buffer is enabled.
67      * \see setEnabled()
68      */
69     bool enabled() const;
70 
71     /**
72      * Sets whether the text buffer will be drawn.
73      * \param enabled set to TRUE to draw buffer
74      * \see enabled()
75      */
76     void setEnabled( bool enabled );
77 
78     /**
79      * Returns the size of the buffer.
80      * \see sizeUnit()
81      * \see setSize()
82      */
83     double size() const;
84 
85     /**
86      * Sets the size of the buffer. The size units are specified using setSizeUnit().
87      * \param size buffer size
88      * \see size()
89      * \see setSizeUnit()
90      */
91     void setSize( double size );
92 
93     /**
94      * Returns the units for the buffer size.
95      * \see size()
96      * \see setSizeUnit()
97      */
98     QgsUnitTypes::RenderUnit sizeUnit() const;
99 
100     /**
101      * Sets the units used for the buffer size.
102      * \param unit size unit
103      * \see setSize()
104      * \see sizeUnit()
105      */
106     void setSizeUnit( QgsUnitTypes::RenderUnit unit );
107 
108     /**
109      * Returns the map unit scale object for the buffer size. This is only used if the
110      * buffer size is set to QgsUnitTypes::RenderMapUnit.
111      * \see setSizeMapUnitScale()
112      * \see sizeUnit()
113      */
114     QgsMapUnitScale sizeMapUnitScale() const;
115 
116     /**
117      * Sets the map unit scale object for the buffer size. This is only used if the
118      * buffer size is set to QgsUnitTypes::RenderMapUnit.
119      * \param scale scale for buffer size
120      * \see sizeMapUnitScale()
121      * \see setSizeUnit()
122      */
123     void setSizeMapUnitScale( const QgsMapUnitScale &scale );
124 
125     /**
126      * Returns the color of the buffer.
127      * \see setColor()
128      */
129     QColor color() const;
130 
131     /**
132      * Sets the color for the buffer.
133      * \param color buffer color
134      * \see color()
135      */
136     void setColor( const QColor &color );
137 
138     /**
139      * Returns whether the interior of the buffer will be filled in. If FALSE, only the stroke
140      * of the text will be drawn as the buffer. The effect of this setting is only visible for
141      * semi-transparent text.
142      * \see setFillBufferInterior()
143      */
144     bool fillBufferInterior() const;
145 
146     /**
147      * Sets whether the interior of the buffer will be filled in.
148      * \param fill set to FALSE to drawn only the stroke of the text as the buffer, or TRUE to also
149      * shade the area inside the text. The effect of this setting is only visible for semi-transparent text.
150      * \see fillBufferInterior()
151      */
152     void setFillBufferInterior( bool fill );
153 
154     /**
155      * Returns the buffer opacity. The opacity is a double value between 0 (fully transparent) and 1 (totally
156      * opaque).
157      * \see setOpacity()
158      */
159     double opacity() const;
160 
161     /**
162      * Sets the buffer opacity.
163      * \param opacity opacity as a double value between 0 (fully transparent) and 1 (totally
164      * opaque)
165      * \see opacity()
166      */
167     void setOpacity( double opacity );
168 
169     /**
170      * Returns the buffer join style.
171      * \see setJoinStyle
172      */
173     Qt::PenJoinStyle joinStyle() const;
174 
175     /**
176      * Sets the join style used for drawing the buffer.
177      * \param style join style
178      * \see joinStyle()
179      */
180     void setJoinStyle( Qt::PenJoinStyle style );
181 
182     /**
183      * Returns the blending mode used for drawing the buffer.
184      * \see setBlendMode()
185      */
186     QPainter::CompositionMode blendMode() const;
187 
188     /**
189      * Sets the blending mode used for drawing the buffer.
190      * \param mode blending mode
191      * \see blendMode()
192      */
193     void setBlendMode( QPainter::CompositionMode mode );
194 
195     /**
196      * Reads settings from a layer's custom properties (for QGIS 2.x projects).
197      * \param layer source vector layer
198      */
199     void readFromLayer( QgsVectorLayer *layer );
200 
201     /**
202      * Read settings from a DOM element.
203      * \see writeXml()
204      */
205     void readXml( const QDomElement &elem );
206 
207     /**
208      * Write settings into a DOM element.
209      * \see readXml()
210      */
211     QDomElement writeXml( QDomDocument &doc ) const;
212 
213     /**
214      * Returns the current paint effect for the buffer.
215      * \returns paint effect
216      * \see setPaintEffect()
217      */
218     const QgsPaintEffect *paintEffect() const;
219 
220     /**
221      * Sets the current paint \a effect for the buffer.
222      * \param effect paint effect. Ownership is transferred to the buffer settings.
223      * \see paintEffect()
224      */
225     void setPaintEffect( QgsPaintEffect *effect SIP_TRANSFER );
226 
227     /**
228      * Updates the format by evaluating current values of data defined properties.
229      * \since QGIS 3.10
230      */
231     void updateDataDefinedProperties( QgsRenderContext &context, const QgsPropertyCollection &properties );
232 
233     /**
234      * Returns all field names referenced by the configuration (e.g. from data defined properties).
235      * \since QGIS 3.14
236      */
237     QSet<QString> referencedFields( const QgsRenderContext &context ) const;
238 
239   private:
240 
241     QSharedDataPointer<QgsTextBufferSettingsPrivate> d;
242 
243 };
244 
245 #endif // QGSTEXTBUFFERSETTINGS_H
246