Utilities for layouts. More...

#include <qgslayoututils.h>

Static Public Member Functions
static double	calculatePrettySize (double minimumSize, double maximumSize)
	Calculates a "pretty" size which falls between the range [minimumSize, maximumSize]. More...

static QgsRenderContext	createRenderContextForLayout (QgsLayout layout, QPainter painter, double dpi=-1)
	Creates a render context suitable for the specified layout and painter destination. More...

static QgsRenderContext	createRenderContextForMap (QgsLayoutItemMap map, QPainter painter, double dpi=-1)
	Creates a render context suitable for the specified layout map and painter destination. More...

static QgsLayoutItemPage::Orientation	decodePaperOrientation (const QString &string, bool &ok)
	Decodes a string representing a paper orientation and returns the decoded orientation. More...

static void	drawText (QPainter *painter, const QRectF &rectangle, const QString &text, const QFont &font, const QColor &color=QColor(), Qt::AlignmentFlag halignment=Qt::AlignLeft, Qt::AlignmentFlag valignment=Qt::AlignTop, int flags=Qt::TextWordWrap)
	Draws text on a painter within a rectangle, taking care of layout specific issues (calculation to pixel, scaling of font and painter to work around Qt font bugs). More...

static void	drawText (QPainter *painter, QPointF position, const QString &text, const QFont &font, const QColor &color=QColor())
	Draws text on a painter at a specific position, taking care of layout specific issues (calculation to pixel, scaling of font and painter to work around Qt font bugs). More...

static double	fontAscentMM (const QFont &font)
	Calculates a font ascent in millimeters, including workarounds for QT font rendering issues. More...

static double	fontDescentMM (const QFont &font)
	Calculate a font descent in millimeters, including workarounds for QT font rendering issues. More...

static double	fontHeightCharacterMM (const QFont &font, QChar character)
	Calculate a font height in millimeters of a single character, including workarounds for QT font rendering issues. More...

static double	fontHeightMM (const QFont &font)
	Calculate a font height in millimeters, including workarounds for QT font rendering issues. More...

static bool	itemIsAClippingSource (const QgsLayoutItem *item)
	Returns `true` if an item is a clipping item for another layout item. More...

static QRectF	largestRotatedRectWithinBounds (const QRectF &originalRect, const QRectF &boundsRect, double rotation)
	Calculates the largest scaled version of originalRect which fits within boundsRect, when it is rotated by the a specified rotation amount. More...

static QgsMapLayer *	mapLayerFromString (const QString &string, QgsProject *project)
	Resolves a string into a map layer from a given project. More...

static double	normalizedAngle (double angle, bool allowNegative=false)
	Ensures that an angle (in degrees) is in the range 0 <= angle < 360. More...

static QVector< double >	predefinedScales (const QgsLayout *layout)
	Returns a list of predefined scales associated with a layout. More...

static double	relativePosition (double position, double beforeMin, double beforeMax, double afterMin, double afterMax)
	Returns a scaled position given a before and after range. More...

static void	relativeResizeRect (QRectF &rectToResize, const QRectF &boundsBefore, const QRectF &boundsAfter)
	Resizes a QRectF relative to a resized bounding rectangle. More...

static void	rotate (double angle, double &x, double &y)
	Rotates a point / vector around the origin. More...

static QFont	scaledFontPixelSize (const QFont &font)
	Returns a font where size is set in points and the size has been upscaled with FONT_WORKAROUND_SCALE to workaround QT font rendering bugs. More...

static Q_DECL_DEPRECATED double	scaleFactorFromItemStyle (const QStyleOptionGraphicsItem *style)
	Extracts the scale factor from an item style. More...

static double	scaleFactorFromItemStyle (const QStyleOptionGraphicsItem style, QPainter painter)
	Extracts the scale factor from an item style and painter. More...

static double	snappedAngle (double angle)
	Snaps an angle (in degrees) to its closest 45 degree angle. More...

static double	textHeightMM (const QFont &font, const QString &text, double multiLineHeight=1.0)
	Calculate a font height in millimeters for a text string, including workarounds for QT font rendering issues. More...

static double	textWidthMM (const QFont &font, const QString &text)
	Calculate a font width in millimeters for a text string, including workarounds for QT font rendering issues. More...

Friends
class	TestQgsLayoutUtils

Detailed Description

Utilities for layouts.

Since: QGIS 3.0

Definition at line 37 of file qgslayoututils.h.

Member Function Documentation

◆ calculatePrettySize()

double QgsLayoutUtils::calculatePrettySize	(	double	minimumSize,
		double	maximumSize
	)

static

Calculates a "pretty" size which falls between the range [minimumSize, maximumSize].

This method will return an optimal round number which falls within the given range, finding the largest "pretty" number possible.

Since: QGIS 3.10

Definition at line 457 of file qgslayoututils.cpp.

◆ createRenderContextForLayout()

QgsRenderContext QgsLayoutUtils::createRenderContextForLayout	(	QgsLayout *	layout,
		QPainter *	painter,
		double	dpi = `-1`
	)

static

Creates a render context suitable for the specified layout and painter destination.

This method returns a new QgsRenderContext which matches the scale and settings from the layout's QgsLayout::referenceMap(). If the dpi argument is not specified then the dpi will be taken from the destination painter device.

See also: createRenderContextForMap()

Definition at line 141 of file qgslayoututils.cpp.

◆ createRenderContextForMap()

QgsRenderContext QgsLayoutUtils::createRenderContextForMap	(	QgsLayoutItemMap *	map,
		QPainter *	painter,
		double	dpi = `-1`
	)

static

Creates a render context suitable for the specified layout map and painter destination.

This method returns a new QgsRenderContext which matches the scale and settings of the target map. If the dpi argument is not specified then the dpi will be taken from the destination painter device.

See also: createRenderContextForLayout()

Definition at line 97 of file qgslayoututils.cpp.

◆ decodePaperOrientation()

QgsLayoutItemPage::Orientation QgsLayoutUtils::decodePaperOrientation	(	const QString &	string,
		bool &	ok
	)

static

Decodes a string representing a paper orientation and returns the decoded orientation.

If the string was correctly decoded, ok will be set to true.

Definition at line 382 of file qgslayoututils.cpp.

◆ drawText() [1/2]

void QgsLayoutUtils::drawText	(	QPainter *	painter,
		const QRectF &	rectangle,
		const QString &	text,
		const QFont &	font,
		const QColor &	color = `QColor()`,
		Qt::AlignmentFlag	halignment = `Qt::AlignLeft`,
		Qt::AlignmentFlag	valignment = `Qt::AlignTop`,
		int	flags = `Qt::TextWordWrap`
	)

static

Draws text on a painter within a rectangle, taking care of layout specific issues (calculation to pixel, scaling of font and painter to work around Qt font bugs).

If color is specified, text will be rendered in that color. If not specified, the current painter pen color will be used instead.

The text alignment within rectangle can be set via the halignment and valignment arguments.

The flags parameter allows for passing Qt::TextFlags to control appearance of rendered text.

Definition at line 277 of file qgslayoututils.cpp.

◆ drawText() [2/2]

void QgsLayoutUtils::drawText	(	QPainter *	painter,
		QPointF	position,
		const QString &	text,
		const QFont &	font,
		const QColor &	color = `QColor()`
	)

static

Draws text on a painter at a specific position, taking care of layout specific issues (calculation to pixel, scaling of font and painter to work around Qt font bugs).

If color is specified, text will be rendered in that color. If not specified, the current painter pen color will be used instead.

Definition at line 255 of file qgslayoututils.cpp.

◆ fontAscentMM()

double QgsLayoutUtils::fontAscentMM ( const QFont & font )

static

Calculates a font ascent in millimeters, including workarounds for QT font rendering issues.

See also: fontDescentMM(); fontHeightMM(); fontHeightCharacterMM(); textWidthMM()

Definition at line 184 of file qgslayoututils.cpp.

◆ fontDescentMM()

double QgsLayoutUtils::fontDescentMM ( const QFont & font )

static

Calculate a font descent in millimeters, including workarounds for QT font rendering issues.

See also: fontAscentMM(); fontHeightMM(); fontHeightCharacterMM(); textWidthMM()

Definition at line 193 of file qgslayoututils.cpp.

◆ fontHeightCharacterMM()

double QgsLayoutUtils::fontHeightCharacterMM	(	const QFont &	font,
		QChar	character
	)

static

Calculate a font height in millimeters of a single character, including workarounds for QT font rendering issues.

See also: fontAscentMM(); fontDescentMM(); fontHeightMM(); textWidthMM()

Definition at line 213 of file qgslayoututils.cpp.

◆ fontHeightMM()

double QgsLayoutUtils::fontHeightMM ( const QFont & font )

static

Calculate a font height in millimeters, including workarounds for QT font rendering issues.

The font height is the font ascent + descent + 1 (for the baseline).

See also: fontAscentMM(); fontDescentMM(); fontHeightCharacterMM(); textWidthMM()

Definition at line 203 of file qgslayoututils.cpp.

◆ itemIsAClippingSource()

bool QgsLayoutUtils::itemIsAClippingSource ( const QgsLayoutItem * item )

static

Returns true if an item is a clipping item for another layout item.

Since: QGIS 3.16

Definition at line 485 of file qgslayoututils.cpp.

◆ largestRotatedRectWithinBounds()

QRectF QgsLayoutUtils::largestRotatedRectWithinBounds	(	const QRectF &	originalRect,
		const QRectF &	boundsRect,
		double	rotation
	)

static

Calculates the largest scaled version of originalRect which fits within boundsRect, when it is rotated by the a specified rotation amount.

Parameters

originalRect	QRectF to be rotated and scaled
boundsRect	QRectF specifying the bounds which the rotated and scaled rectangle must fit within
rotation	the rotation in degrees to be applied to the rectangle

Returns: largest scaled version of the rectangle possible

Definition at line 302 of file qgslayoututils.cpp.

◆ mapLayerFromString()

QgsMapLayer * QgsLayoutUtils::mapLayerFromString	(	const QString &	string,
		QgsProject *	project
	)

static

Resolves a string into a map layer from a given project.

Attempts different forms of layer matching such as matching by layer id or layer name.

Layer names are matched using a case-insensitive check, ONLY if an exact case match was not found.

Since: QGIS 3.2

Definition at line 422 of file qgslayoututils.cpp.

◆ normalizedAngle()

double QgsLayoutUtils::normalizedAngle	(	double	angle,
		bool	allowNegative = `false`
	)

static

Ensures that an angle (in degrees) is in the range 0 <= angle < 360.

If allowNegative is true then angles between (-360, 360) are allowed. If false, angles are converted to positive angles in the range [0, 360).

Definition at line 43 of file qgslayoututils.cpp.

◆ predefinedScales()

QVector< double > QgsLayoutUtils::predefinedScales ( const QgsLayout * layout )

static

Returns a list of predefined scales associated with a layout.

Since: QGIS 3.20

Definition at line 513 of file qgslayoututils.cpp.

◆ relativePosition()

double QgsLayoutUtils::relativePosition	(	double	position,
		double	beforeMin,
		double	beforeMax,
		double	afterMin,
		double	afterMax
	)

static

Returns a scaled position given a before and after range.

Parameters

position	initial position within before range to scale
beforeMin	minimum value in before range
beforeMax	maximum value in before range
afterMin	minimum value in after range
afterMax	maximum value in after range

Returns: position scaled to range specified by afterMin and afterMax

Definition at line 165 of file qgslayoututils.cpp.

◆ relativeResizeRect()

void QgsLayoutUtils::relativeResizeRect	(	QRectF &	rectToResize,
		const QRectF &	boundsBefore,
		const QRectF &	boundsAfter
	)

static

Resizes a QRectF relative to a resized bounding rectangle.

Parameters

rectToResize	QRectF to resize, contained within boundsBefore. The rectangle is linearly scaled to retain its relative position and size within boundsAfter.
boundsBefore	QRectF of bounds before resize
boundsAfter	QRectF of bounds after resize

Definition at line 154 of file qgslayoututils.cpp.

◆ rotate()

void QgsLayoutUtils::rotate	(	double	angle,
		double &	x,
		double &	y
	)

static

Rotates a point / vector around the origin.

Parameters

angle	rotation angle in degrees, counterclockwise
x	in/out: x coordinate before / after the rotation
y	in/out: y coordinate before / after the rotation

Definition at line 33 of file qgslayoututils.cpp.

◆ scaledFontPixelSize()

QFont QgsLayoutUtils::scaledFontPixelSize ( const QFont & font )

static

Returns a font where size is set in points and the size has been upscaled with FONT_WORKAROUND_SCALE to workaround QT font rendering bugs.

Returns a font with size set in pixels.

Definition at line 174 of file qgslayoututils.cpp.

◆ scaleFactorFromItemStyle() [1/2]

double QgsLayoutUtils::scaleFactorFromItemStyle ( const QStyleOptionGraphicsItem * style )

static

Extracts the scale factor from an item style.

Deprecated:: Use the variant with a QPainter argument instead

Definition at line 399 of file qgslayoututils.cpp.

◆ scaleFactorFromItemStyle() [2/2]

double QgsLayoutUtils::scaleFactorFromItemStyle	(	const QStyleOptionGraphicsItem *	style,
		QPainter *	painter
	)

static

Extracts the scale factor from an item style and painter.

Since: QGIS 3.20

Definition at line 417 of file qgslayoututils.cpp.

◆ snappedAngle()

double QgsLayoutUtils::snappedAngle ( double angle )

static

Snaps an angle (in degrees) to its closest 45 degree angle.

Returns: angle snapped to 0, 45/90/135/180/225/270 or 315 degrees

Definition at line 57 of file qgslayoututils.cpp.

◆ textHeightMM()

double QgsLayoutUtils::textHeightMM	(	const QFont &	font,
		const QString &	text,
		double	multiLineHeight = `1.0`
	)

static

Calculate a font height in millimeters for a text 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.

The multiLineHeight parameter specifies the line spacing factor.

See also: textWidthMM()

Definition at line 239 of file qgslayoututils.cpp.

◆ textWidthMM()

double QgsLayoutUtils::textWidthMM	(	const QFont &	font,
		const QString &	text
	)

static

Calculate a font width in millimeters for a text string, including workarounds for QT font rendering issues.

See also: fontAscentMM(); fontDescentMM(); fontHeightMM(); fontHeightCharacterMM(); textHeightMM()

Definition at line 222 of file qgslayoututils.cpp.

Friends And Related Function Documentation

◆ TestQgsLayoutUtils

friend class TestQgsLayoutUtils

friend

Definition at line 275 of file qgslayoututils.h.

The documentation for this class was generated from the following files:

/build/qgis-3.22.4+99unstable/src/core/layout/qgslayoututils.h
/build/qgis-3.22.4+99unstable/src/core/layout/qgslayoututils.cpp

Static Public Member Functions

Friends

Detailed Description

Member Function Documentation

◆ calculatePrettySize()

◆ createRenderContextForLayout()

◆ createRenderContextForMap()

◆ decodePaperOrientation()

◆ drawText() [1/2]

◆ drawText() [2/2]

◆ fontAscentMM()

◆ fontDescentMM()

◆ fontHeightCharacterMM()

◆ fontHeightMM()

◆ itemIsAClippingSource()

◆ largestRotatedRectWithinBounds()

◆ mapLayerFromString()

◆ normalizedAngle()

◆ predefinedScales()

◆ relativePosition()

◆ relativeResizeRect()

◆ rotate()

◆ scaledFontPixelSize()

◆ scaleFactorFromItemStyle() [1/2]

◆ scaleFactorFromItemStyle() [2/2]

◆ snappedAngle()

◆ textHeightMM()

◆ textWidthMM()

Friends And Related Function Documentation

◆ TestQgsLayoutUtils