Subgroup: Layout

Class: QgsLayoutUtils

class qgis.core.QgsLayoutUtils

Bases: sip.wrapper

Utilities for layouts.

New in version 3.0: Methods

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

Signals

Attributes

createRenderContextForLayout(layout: QgsLayout, painter: QPainter, dpi: float = -1) → QgsRenderContext

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.

createRenderContextForMap(map: QgsLayoutItemMap, painter: QPainter, dpi: float = -1) → QgsRenderContext

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.

decodePaperOrientation(string: str) → Tuple[QgsLayoutItemPage.Orientation, bool]

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

drawText(painter: QPainter, position: Union[QPointF, QPoint], text: str, font: QFont, color: Union[QColor, Qt.GlobalColor, QGradient] = 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).

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

drawText(painter: QPainter, rectangle: QRectF, text: str, font: QFont, color: Union[QColor, Qt.GlobalColor, QGradient] = QColor(), halignment: Qt.AlignmentFlag = Qt.AlignLeft, valignment: Qt.AlignmentFlag = Qt.AlignTop, flags: int = 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).

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.

fontAscentMM(font: QFont) → float

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

See also

fontDescentMM()

See also

fontHeightMM()

See also

textWidthMM()

fontDescentMM(font: QFont) → float

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

See also

fontAscentMM()

See also

fontHeightMM()

See also

textWidthMM()

fontHeightCharacterMM(font: QFont, character: str) → float

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

See also

fontAscentMM()

See also

fontDescentMM()

See also

fontHeightMM()

See also

textWidthMM()

fontHeightMM(font: QFont) → float

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

textWidthMM()

largestRotatedRectWithinBounds(originalRect: QRectF, boundsRect: QRectF, rotation: float) → QRectF

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

mapLayerFromString(string: str, project: QgsProject) → QgsMapLayer

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.

New in version 3.2.

normalizedAngle(angle: float, allowNegative: bool = False) → float

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

relativePosition(position: float, beforeMin: float, beforeMax: float, afterMin: float, afterMax: float) → float

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

relativeResizeRect(rectToResize: QRectF, boundsBefore: QRectF, boundsAfter: QRectF)

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. :param boundsBefore: QRectF of bounds before resize :param boundsAfter: QRectF of bounds after resize

rotate(angle: float) → Tuple[float, float]

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
scaleFactorFromItemStyle(style: QStyleOptionGraphicsItem) → float

Extracts the scale factor from an item style.

scaledFontPixelSize(font: QFont) → QFont

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.

snappedAngle(angle: float) → float

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
textHeightMM(font: QFont, text: str, multiLineHeight: float = 1) → float

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

textWidthMM(font: QFont, text: str) → float

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

See also

fontAscentMM()

See also

fontDescentMM()

See also

fontHeightMM()

See also

textHeightMM()