1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
|
/** \ingroup core
* Utilities for compositions.
*/
class QgsComposerUtils
{
%TypeHeaderCode
#include <qgscomposerutils.h>
%End
public:
/** Draws an arrow head on to a QPainter.
* @param p destination painter
* @param x x-coordinate of arrow center
* @param y y-coordinate of arrow center
* @param angle angle in degrees which arrow should point toward, measured
* clockwise from pointing vertical upward
* @param arrowHeadWidth size of arrow head
*/
static void drawArrowHead( QPainter* p, const double x, const double y, const double angle, const double arrowHeadWidth );
/** Calculates the angle of the line from p1 to p2 (counter clockwise,
* starting from a line from north to south)
* @param p1 start point of line
* @param p2 end point of line
* @returns angle in degrees, clockwise from south
*/
static double angle( QPointF p1, QPointF p2 );
/** Rotates a point / vector around the origin.
* @param angle rotation angle in degrees, counterclockwise
* @param x in/out: x coordinate before / after the rotation
* @param y in/out: y cooreinate before / after the rotation
*/
static void rotate( const double angle, double& x, double& y );
/** Ensures that an angle is in the range 0 <= angle < 360
* @param angle angle in degrees
* @returns equivalent angle within the range [0, 360)
* @see snappedAngle
*/
static double normalizedAngle( const double angle );
/** Snaps an angle to its closest 45 degree angle
* @param angle angle in degrees
* @returns angle snapped to 0, 45/90/135/180/225/270 or 315 degrees
*/
static double snappedAngle( const double angle );
/** Calculates the largest scaled version of originalRect which fits within boundsRect, when it is rotated by
* a specified amount.
* @param originalRect QRectF to be rotated and scaled
* @param boundsRect QRectF specifying the bounds which the rotated and scaled rectangle must fit within
* @param rotation the rotation in degrees to be applied to the rectangle
* @returns largest scaled version of the rectangle possible
*/
static QRectF largestRotatedRectWithinBounds( const QRectF originalRect, const QRectF boundsRect, const double rotation );
/** Returns the size in mm corresponding to a font point size
* @param pointSize font size in points
* @see mmToPoints
*/
static double pointsToMM( const double pointSize );
/** Returns the size in mm corresponding to a font point size
* @param mmSize font size in mm
* @see pointsToMM
*/
static double mmToPoints( const double mmSize );
/** Resizes a QRectF relative to a resized bounding rectangle.
* @param rectToResize QRectF to resize, contained within boundsBefore. The
* rectangle is linearly scaled to retain its relative position and size within
* boundsAfter.
* @param boundsBefore QRectF of bounds before resize
* @param boundsAfter QRectF of bounds after resize
*/
static void relativeResizeRect( QRectF &rectToResize, const QRectF &boundsBefore, const QRectF &boundsAfter );
/** Returns a scaled position given a before and after range
* @param position initial position within before range to scale
* @param beforeMin minimum value in before range
* @param beforeMax maximum value in before range
* @param afterMin minimum value in after range
* @param afterMax maximum value in after range
* @returns position scaled to range specified by afterMin and afterMax
*/
static double relativePosition( const double position, const double beforeMin, const double beforeMax, const double afterMin, const double afterMax );
/** Decodes a string representing a paper orientation
* @param orientationString string to decode
* @param ok will be true if string could be decoded
* @returns decoded paper orientation
*/
static QgsComposition::PaperOrientation decodePaperOrientation( const QString& orientationString, bool &ok );
/** Decodes a string representing a preset page size
* @param presetString string to decode
* @param width double for decoded paper width
* @param height double for decoded paper height
* @returns true if string could be decoded successfully
*/
static bool decodePresetPaperSize( const QString& presetString, double &width, double &height );
/** Reads all data defined properties from xml
* @param itemElem dom element containing data defined properties
* @param dataDefinedNames map of data defined property to name used within xml
* @param dataDefinedProperties map of data defined properties to QgsDataDefined in which to store properties from xml
* @note this method was added in version 2.5
* @see readDataDefinedProperty
* @see writeDataDefinedPropertyMap
*/
static void readDataDefinedPropertyMap( const QDomElement &itemElem,
QMap< QgsComposerObject::DataDefinedProperty, QString >* dataDefinedNames,
QMap< QgsComposerObject::DataDefinedProperty, QgsDataDefined* >* dataDefinedProperties
);
/** Reads a single data defined property from xml DOM element
* @param property data defined property to read
* @param ddElem dom element containing settings for data defined property
* @param dataDefinedProperties map of data defined properties to QgsDataDefined in which to store properties from xml
* @note this method was added in version 2.5
* @see readDataDefinedPropertyMap
*/
static void readDataDefinedProperty( const QgsComposerObject::DataDefinedProperty property, const QDomElement &ddElem,
QMap< QgsComposerObject::DataDefinedProperty, QgsDataDefined* >* dataDefinedProperties );
/** Writes data defined properties to xml
* @param itemElem DOM element in which to store data defined properties
* @param doc DOM document
* @param dataDefinedNames map of data defined property to name used within xml
* @param dataDefinedProperties map of data defined properties to QgsDataDefined for storing in xml
* @note this method was added in version 2.5
* @see readDataDefinedPropertyMap
*/
static void writeDataDefinedPropertyMap( QDomElement &itemElem, QDomDocument &doc,
const QMap< QgsComposerObject::DataDefinedProperty, QString >* dataDefinedNames,
const QMap< QgsComposerObject::DataDefinedProperty, QgsDataDefined* >* dataDefinedProperties );
/** Returns a font where size is set in pixels and the size has been upscaled with FONT_WORKAROUND_SCALE
* to workaround QT font rendering bugs
* @param font source font with size set in points
* @returns font with size set in pixels
* @note added in version 2.5
*/
static QFont scaledFontPixelSize( const QFont& font );
/** Calculate font ascent in millimeters, including workarounds for QT font rendering issues
* @param font input font
* @returns font ascent in millimeters
* @note added in version 2.5
* @see fontDescentMM
* @see fontHeightMM
* @see fontHeightCharacterMM
* @see textWidthMM
*/
static double fontAscentMM( const QFont& font );
/** Calculate font descent in millimeters, including workarounds for QT font rendering issues
* @param font input font
* @returns font descent in millimeters
* @note added in version 2.5
* @see fontAscentMM
* @see fontHeightMM
* @see fontHeightCharacterMM
* @see textWidthMM
*/
static double fontDescentMM( const QFont& font );
/** Calculate font height in millimeters, including workarounds for QT font rendering issues
* The font height is the font ascent + descent + 1 (for the baseline).
* @param font input font
* @returns font height in millimeters
* @note added in version 2.5
* @see fontAscentMM
* @see fontDescentMM
* @see fontHeightCharacterMM
* @see textWidthMM
*/
static double fontHeightMM( const QFont& font );
/** Calculate font height in millimeters of a single character, including workarounds for QT font
* rendering issues
* @param font input font
* @param character character to calculate height for
* @returns character height in millimeters
* @note added in version 2.5
* @see fontAscentMM
* @see fontDescentMM
* @see fontHeightMM
* @see textWidthMM
*/
static double fontHeightCharacterMM( const QFont& font, QChar character );
/** Calculate font width in millimeters for a string, including workarounds for QT font
* rendering issues
* @param font input font
* @param text string to calculate width of
* @returns string width in millimeters
* @note added in version 2.5
* @see fontAscentMM
* @see fontDescentMM
* @see fontHeightMM
* @see fontHeightCharacterMM
* @see textHeightMM
*/
static double textWidthMM( const QFont& font, const QString& text );
/** Calculate font height in millimeters for a string, including workarounds for QT font
* rendering issues. Note that this method uses a non-standard measure of text height,
* where only the font ascent is considered for the first line of text.
* @param font input font
* @param text string to calculate height of
* @param multiLineHeight line spacing factor
* @returns string height in millimeters
* @note added in version 2.12
* @see textWidthMM
*/
static double textHeightMM( const QFont& font, const QString& text, double multiLineHeight = 1.0 );
/** Draws text on a painter at a specific position, taking care of composer specific issues (calculation to pixel,
* scaling of font and painter to work around Qt font bugs)
* @param painter destination QPainter
* @param pos position to draw text
* @param text string to draw
* @param font font to use for drawing text
* @param color color to draw text
* @note added in version 2.5
*/
static void drawText( QPainter* painter, QPointF pos, const QString& text, const QFont& font, const QColor& color = QColor() );
/** Draws text on a painter within a rectangle, taking care of composer specific issues (calculation to pixel,
* scaling of font and painter to work around Qt font bugs)
* @param painter destination QPainter
* @param rect rectangle to draw into
* @param text string to draw
* @param font font to use for drawing text
* @param color color to draw text
* @param halignment optional horizontal alignment
* @param valignment optional vertical alignment
* @param flags allows for passing Qt::TextFlags to control appearance of rendered text
* @note added in version 2.5
*/
static void drawText( QPainter* painter, const QRectF& rect, const QString& text, const QFont& font, const QColor& color = QColor(), const Qt::AlignmentFlag halignment = Qt::AlignLeft, const Qt::AlignmentFlag valignment = Qt::AlignTop, const int flags = Qt::TextWordWrap );
};
|
