/** \ingroup core * Utilities for compositions. */ class QgsComposerUtils { %TypeHeaderCode #include %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 ); };