Class: QgsLayoutSnapper

Manages snapping grids and preset snap lines in a layout, and handles snapping points to the nearest grid coordinate/snap line when possible.

Class Hierarchy

Inheritance diagram of qgis.core.QgsLayoutSnapper

Base classes

QgsLayoutSerializableObject

An interface for layout objects which can be stored and read from DOM elements.

QgsLayoutUndoObjectInterface

Interface for layout objects which support undo/redo commands.

Abstract Methods

readXml

Sets the snapper's state from a DOM element.

writeXml

Stores the snapper's state in a DOM element.

Methods

setSnapToGrid

Sets whether snapping to grid is enabled.

setSnapToGuides

Sets whether snapping to guides is enabled.

setSnapToItems

Sets whether snapping to items is enabled.

setSnapTolerance

Sets the snap tolerance (in pixels) to use when snapping.

snapPoint

Snaps a layout coordinate point.

snapPointToGrid

Snaps a layout coordinate point to the grid.

snapPointToGuides

Snaps an original layout coordinate to the guides.

snapPointToItems

Snaps an original layout coordinate to the item bounds.

snapPointsToGrid

Snaps a set of points to the grid.

snapPointsToGuides

Snaps a set of points to the guides.

snapPointsToItems

Snaps a set of points to the item bounds.

snapRect

Snaps a layout coordinate rect.

snapToGrid

Returns True if snapping to grid is enabled.

snapToGuides

Returns True if snapping to guides is enabled.

snapToItems

Returns True if snapping to items is enabled.

snapTolerance

Returns the snap tolerance (in pixels) to use when snapping.
class qgis.core.QgsLayoutSnapper[source]

Bases: QgsLayoutSerializableObject

__init__(layout: QgsLayout | None)

Constructor for QgsLayoutSnapper, attached to the specified layout.

Parameters:

layout (Optional[QgsLayout])

__init__(a0: QgsLayoutSnapper)
Parameters:

a0 (QgsLayoutSnapper)

abstract readXml(self, gridElement: QDomElement, document: QDomDocument, context: QgsReadWriteContext) → bool[source]

Sets the snapper’s state from a DOM element. snapperElement is the DOM node corresponding to the snapper.

See also

writeXml()

Parameters:
Return type:

bool

setSnapToGrid(self, enabled: bool)[source]

Sets whether snapping to grid is enabled.

See also

snapToGrid()

Parameters:

enabled (bool)

setSnapToGuides(self, enabled: bool)[source]

Sets whether snapping to guides is enabled.

See also

snapToGuides()

Parameters:

enabled (bool)

setSnapToItems(self, enabled: bool)[source]

Sets whether snapping to items is enabled.

See also

snapToItems()

Parameters:

enabled (bool)

setSnapTolerance(self, snapTolerance: int)[source]

Sets the snap tolerance (in pixels) to use when snapping.

See also

snapTolerance()

Parameters:

snapTolerance (int)

snapPoint(self, point: QPointF | QPoint, scaleFactor: float, horizontalSnapLine: QGraphicsLineItem | None = None, verticalSnapLine: QGraphicsLineItem | None = None, ignoreItems: Iterable[QgsLayoutItem] | None = [])[source]

Snaps a layout coordinate point. If point was snapped, snapped will be set to True.

The scaleFactor argument should be set to the transformation from scalar transform from layout coordinates to pixels, i.e. the graphics view transform().m11() value.

This method considers snapping to the grid, snap lines, etc.

If the horizontalSnapLine and verticalSnapLine arguments are specified, then the snapper will automatically display and position these lines to indicate snapping positions to item bounds.

A list of items to ignore during the snapping can be specified via the ignoreItems list.

See also

snapRect()

Parameters:

  • point (Union[QPointF, QPoint])

  • scaleFactor (float)

  • horizontalSnapLine (Optional[QGraphicsLineItem] = None)

  • verticalSnapLine (Optional[QGraphicsLineItem] = None)

  • ignoreItems (Optional[Iterable[QgsLayoutItem]] = []) -> (QPointF)

snapPointToGrid(self, point: QPointF | QPoint, scaleFactor: float)[source]

Snaps a layout coordinate point to the grid. If point was snapped horizontally, snappedX will be set to True. If point was snapped vertically, snappedY will be set to True.

The scaleFactor argument should be set to the transformation from scalar transform from layout coordinates to pixels, i.e. the graphics view transform().m11() value.

If snapToGrid() is disabled, this method will return the point unchanged.

See also

snapPointsToGrid()

Parameters:

  • point (Union[QPointF, QPoint])

  • scaleFactor (float) -> (QPointF)

snapPointToGuides(self, original: float, orientation: Qt.Orientation, scaleFactor: float)[source]

Snaps an original layout coordinate to the guides. If the point was snapped, snapped will be set to True.

The scaleFactor argument should be set to the transformation from scalar transform from layout coordinates to pixels, i.e. the graphics view transform().m11() value.

If snapToGuides() is disabled, this method will return the point unchanged.

See also

snapPointsToGuides()

Parameters:

  • original (float)

  • orientation (Qt.Orientation)

  • scaleFactor (float) -> (float)

snapPointToItems(self, original: float, orientation: Qt.Orientation, scaleFactor: float, ignoreItems: Iterable[QgsLayoutItem], snapLine: QGraphicsLineItem | None = None)[source]

Snaps an original layout coordinate to the item bounds. If the point was snapped, snapped will be set to True.

The scaleFactor argument should be set to the transformation from scalar transform from layout coordinates to pixels, i.e. the graphics view transform().m11() value.

If snapToItems() is disabled, this method will return the point unchanged.

A list of items to ignore during the snapping can be specified via the ignoreItems list.

If snapLine is specified, the snapper will automatically show (or hide) the snap line based on the result of the snap, and position it at the correct location for the snap.

See also

snapPointsToItems()

Parameters:

  • original (float)

  • orientation (Qt.Orientation)

  • scaleFactor (float)

  • ignoreItems (Iterable[QgsLayoutItem])

  • snapLine (Optional[QGraphicsLineItem] = None) -> (float)

snapPointsToGrid(self, points: Iterable[QPointF | QPoint], scaleFactor: float)[source]

Snaps a set of points to the grid. If the points were snapped, snapped will be set to True.

The scaleFactor argument should be set to the transformation from scalar transform from layout coordinates to pixels, i.e. the graphics view transform().m11() value.

If snapToGrid() is disabled, this method will not attempt to snap the points.

The returned value is the smallest delta which the points need to be shifted by in order to align one of the points to the grid.

See also

snapPointToGrid()

Parameters:

  • points (Iterable[Union[QPointF, QPoint]])

  • scaleFactor (float) -> (QPointF)

snapPointsToGuides(self, points: Iterable[float], orientation: Qt.Orientation, scaleFactor: float)[source]

Snaps a set of points to the guides. If the points were snapped, snapped will be set to True.

The scaleFactor argument should be set to the transformation from scalar transform from layout coordinates to pixels, i.e. the graphics view transform().m11() value.

If snapToGuides() is disabled, this method will not attempt to snap the points.

The returned value is the smallest delta which the points need to be shifted by in order to align one of the points to a guide.

See also

snapPointToGuides()

Parameters:

  • points (Iterable[float])

  • orientation (Qt.Orientation)

  • scaleFactor (float) -> (float)

snapPointsToItems(self, points: Iterable[float], orientation: Qt.Orientation, scaleFactor: float, ignoreItems: Iterable[QgsLayoutItem], snapLine: QGraphicsLineItem | None = None)[source]

Snaps a set of points to the item bounds. If the points were snapped, snapped will be set to True.

The scaleFactor argument should be set to the transformation from scalar transform from layout coordinates to pixels, i.e. the graphics view transform().m11() value.

If snapToItems() is disabled, this method will not attempt to snap the points.

The returned value is the smallest delta which the points need to be shifted by in order to align one of the points to an item bound.

See also

snapPointToItems()

Parameters:

  • points (Iterable[float])

  • orientation (Qt.Orientation)

  • scaleFactor (float)

  • ignoreItems (Iterable[QgsLayoutItem])

  • snapLine (Optional[QGraphicsLineItem] = None) -> (float)

snapRect(self, rect: QRectF, scaleFactor: float, horizontalSnapLine: QGraphicsLineItem | None = None, verticalSnapLine: QGraphicsLineItem | None = None, ignoreItems: Iterable[QgsLayoutItem] | None = [])[source]

Snaps a layout coordinate rect. If rect was snapped, snapped will be set to True.

Snapping occurs by moving the rectangle alone. The rectangle will not be resized as a result of the snap operation.

The scaleFactor argument should be set to the transformation from scalar transform from layout coordinates to pixels, i.e. the graphics view transform().m11() value.

This method considers snapping to the grid, snap lines, etc.

If the horizontalSnapLine and verticalSnapLine arguments are specified, then the snapper will automatically display and position these lines to indicate snapping positions to item bounds.

A list of items to ignore during the snapping can be specified via the ignoreItems list.

See also

snapPoint()

Parameters:

  • rect (QRectF)

  • scaleFactor (float)

  • horizontalSnapLine (Optional[QGraphicsLineItem] = None)

  • verticalSnapLine (Optional[QGraphicsLineItem] = None)

  • ignoreItems (Optional[Iterable[QgsLayoutItem]] = []) -> (QRectF)

snapToGrid(self) → bool[source]

Returns True if snapping to grid is enabled.

See also

setSnapToGrid()

Return type:

bool

snapToGuides(self) → bool[source]

Returns True if snapping to guides is enabled.

See also

setSnapToGuides()

Return type:

bool

snapToItems(self) → bool[source]

Returns True if snapping to items is enabled.

See also

setSnapToItems()

Return type:

bool

snapTolerance(self) → int[source]

Returns the snap tolerance (in pixels) to use when snapping.

See also

setSnapTolerance()

Return type:

int

abstract writeXml(self, parentElement: QDomElement, document: QDomDocument, context: QgsReadWriteContext) → bool[source]

Stores the snapper’s state in a DOM element. The parentElement should refer to the parent layout’s DOM element.

See also

readXml()

Parameters:
Return type:

bool