QGIS/python/core/composer/qgscomposerutils.sip
Nyall Dawson 8a9cee0fb6 [composer] Use reference map when creating render context for
draw shape/arrow/nodes/paper symbols

This commit removes some more instances where changes in the
canvas affect compositions. Previously the symbols drawn
in shape/arrow/etc items were using the scale from the canvas.
This meant that the appearance of these items in composer
would change depending on canvas zoom if they used symbols
with map unit sizes.

Now they take their map scale from the composition's reference
map. While this has the nice side effect that now map units
can be used in the appearance of these items and they're
guaranteed to match up with the reference map item, the main
intention here is to remove more of the forced links between
compositions (core) and the main canvas (app).
2017-01-16 15:52:19 +10:00

254 lines
11 KiB
Plaintext

/** \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 );
/**
* Creates a render context suitable for the specified composition and QPainter destination.
* This method returns a new QgsRenderContext which matches the scale and settings from the composition's
* QgsComposition::referenceMap().
* @note added in QGIS 3.0
*/
static QgsRenderContext createRenderContext( QgsComposition* composition, QPainter& painter );
};