Class: QgsLayoutUtils¶

Utilities for layouts.

Static Methods

`calculatePrettySize`	Calculates a "pretty" size which falls between the range [minimumSize, maximumSize].
`createRenderContextForLayout`	Creates a render context suitable for the specified layout and painter destination.
`createRenderContextForMap`	Creates a render context suitable for the specified layout map and painter destination.
`decodePaperOrientation`	Decodes a string representing a paper orientation and returns the decoded orientation.
`drawText`	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).
`fontAscentMM`	Calculates a font ascent in millimeters, including workarounds for QT font rendering issues.
`fontDescentMM`	Calculate a font descent in millimeters, including workarounds for QT font rendering issues.
`fontHeightCharacterMM`	Calculate a font height in millimeters of a single character, including workarounds for QT font rendering issues.
`fontHeightMM`	Calculate a font height in millimeters, including workarounds for QT font rendering issues.
`itemIsAClippingSource`	Returns `True` if an item is a clipping item for another layout item.
`largestRotatedRectWithinBounds`	Calculates the largest scaled version of originalRect which fits within boundsRect, when it is rotated by the a specified rotation amount.
`mapLayerFromString`	Resolves a string into a map layer from a given project.
`normalizedAngle`	Ensures that an angle (in degrees) is in the range 0 <= angle < 360.
`predefinedScales`	Returns a list of predefined scales associated with a layout.
`relativePosition`	Returns a scaled position given a before and after range
`relativeResizeRect`	Resizes a QRectF relative to a resized bounding rectangle.
`rotate`	Rotates a point / vector around the origin.
`scaleFactorFromItemStyle`	Extracts the scale factor from an item style.
`scaledFontPixelSize`	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.
`snappedAngle`	Snaps an angle (in degrees) to its closest 45 degree angle.
`textHeightMM`	Calculate a font height in millimeters for a text string, including workarounds for QT font rendering issues.
`textWidthMM`	Calculate a font width in millimeters for a text string, including workarounds for QT font rendering issues.

class qgis.core.QgsLayoutUtils[source]¶

Bases: object

static calculatePrettySize(minimumSize: float, maximumSize: float) → float[source]¶

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.

Added in version 3.10.

Parameters:

minimumSize (float)
maximumSize (float)

Return type:

float

static createRenderContextForLayout(layout: QgsLayout | None, painter: QPainter | None, dpi: float = -1) → QgsRenderContext[source]¶

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()

Parameters:

layout (Optional[QgsLayout])
painter (Optional[QPainter])
dpi (float = -1)

Return type:

QgsRenderContext

static createRenderContextForMap(map: QgsLayoutItemMap | None, painter: QPainter | None, dpi: float = -1) → QgsRenderContext[source]¶

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()

Parameters:

map (Optional[QgsLayoutItemMap])
painter (Optional[QPainter])
dpi (float = -1)

Return type:

QgsRenderContext

static decodePaperOrientation(string: str | None)[source]¶

Decodes a string representing a paper orientation and returns the decoded orientation. If the string was correctly decoded, ok will be set to True.

Parameters:: string (Optional[str]) -> (QgsLayoutItemPage.Orientation)

static drawText(painter: QPainter | None, position: QPointF | QPoint, text: str | None, font: QFont, color: QColor | Qt.GlobalColor = QColor())[source]¶

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.

Parameters:

painter (Optional[QPainter])
position (Union[QPointF, QPoint])
text (Optional[str])
font (QFont)
color (Union[QColor, Qt.GlobalColor] = QColor())

static drawText(painter: QPainter | None, rectangle: QRectF, text: str | None, font: QFont, color: QColor | Qt.GlobalColor = QColor(), halignment: Qt.AlignmentFlag = Qt.AlignLeft, valignment: Qt.AlignmentFlag = Qt.AlignTop, flags: int = Qt.TextWordWrap)[source]

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.

Parameters:

painter (Optional[QPainter])
rectangle (QRectF)
text (Optional[str])
font (QFont)
color (Union[QColor, Qt.GlobalColor] = QColor())
halignment (Qt.AlignmentFlag = Qt.AlignLeft)
valignment (Qt.AlignmentFlag = Qt.AlignTop)
flags (int = Qt.TextWordWrap)

static fontAscentMM(font: QFont) → float[source]¶

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

See also

fontDescentMM()

See also

fontHeightMM()

See also

fontHeightCharacterMM()

See also

textWidthMM()

Parameters:: font (QFont)
Return type:: float

static fontDescentMM(font: QFont) → float[source]¶

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

See also

fontAscentMM()

See also

fontHeightMM()

See also

fontHeightCharacterMM()

See also

textWidthMM()

Parameters:: font (QFont)
Return type:: float

static fontHeightCharacterMM(font: QFont, character: str) → float[source]¶

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

See also

See also

See also

See also

Parameters:

font (QFont)
character (str)

Return type:

float

static fontHeightMM(font: QFont) → float[source]¶

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()

See also

fontDescentMM()

See also

fontHeightCharacterMM()

See also

textWidthMM()

Parameters:: font (QFont)
Return type:: float

static itemIsAClippingSource(item: QgsLayoutItem | None) → bool[source]¶

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

Added in version 3.16.

Parameters:: item (Optional[QgsLayoutItem])
Return type:: bool

static largestRotatedRectWithinBounds(originalRect: QRectF, boundsRect: QRectF, rotation: float) → QRectF[source]¶

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

Parameters:

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

Return type:

QRectF

Returns:

largest scaled version of the rectangle possible

static mapLayerFromString(string: str | None, project: QgsProject | None) → QgsMapLayer | None[source]¶

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.

Added in version 3.2.

Parameters:

string (Optional[str])
project (Optional[QgsProject])

Return type:

Optional[QgsMapLayer]

static normalizedAngle(angle: float, allowNegative: bool = False) → float[source]¶

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).

Parameters:

angle (float)
allowNegative (bool = False)

Return type:

float

static predefinedScales(layout: QgsLayout | None) → List[float]¶

Returns a list of predefined scales associated with a layout.

Added in version 3.20.

Parameters:: layout (Optional[QgsLayout])
Return type:: List[float]

static relativePosition(position: float, beforeMin: float, beforeMax: float, afterMin: float, afterMax: float) → float[source]¶

Returns a scaled position given a before and after range

Parameters:

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

Return type:

float

Returns:

position scaled to range specified by afterMin and afterMax

static relativeResizeRect(rectToResize: QRectF, boundsBefore: QRectF, boundsAfter: QRectF)[source]¶

Resizes a QRectF relative to a resized bounding rectangle.

Parameters:

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

static rotate(angle: float)[source]¶

Rotates a point / vector around the origin.

Parameters:

angle (float) -> (float) – rotation angle in degrees, counterclockwise
x – in/out: x coordinate before / after the rotation
y – in/out: y coordinate before / after the rotation

static scaleFactorFromItemStyle(style: QStyleOptionGraphicsItem | None) → float[source]¶

Extracts the scale factor from an item style.

Deprecated since version 3.40: Use the variant with a QPainter argument instead.

Parameters:: style (Optional[QStyleOptionGraphicsItem])
Return type:: float

static scaleFactorFromItemStyle(style: QStyleOptionGraphicsItem | None, painter: QPainter | None) → float[source]

Extracts the scale factor from an item style and painter.

Added in version 3.20.

Parameters:

style (Optional[QStyleOptionGraphicsItem])
painter (Optional[QPainter])

Return type:

float

static scaledFontPixelSize(font: QFont) → QFont[source]¶

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.

Parameters:: font (QFont)
Return type:: QFont

static snappedAngle(angle: float) → float[source]¶

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

Return type:: float
Returns:: angle snapped to 0, 45/90/135/180/225/270 or 315 degrees
Parameters:: angle (float)

static textHeightMM(font: QFont, text: str | None, multiLineHeight: float = 1) → float[source]¶

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()

Parameters: