Class: QgsLayoutSnapper¶
- class qgis.core.QgsLayoutSnapper¶
Bases:
QgsLayoutSerializableObject
Manages snapping grids and preset snap lines in a layout, and handles snapping points to the nearest grid coordinate/snap line when possible.
QgsLayoutSnapper(layout:
QgsLayout
) Constructor forQgsLayoutSnapper
, attached to the specifiedlayout
.QgsLayoutSnapper(
QgsLayoutSnapper
)Methods
- rtype:
QgsLayout
Sets the snapper's state from a DOM element.
Sets whether snapping to grid is
enabled
.Sets whether snapping to guides is
enabled
.Sets whether snapping to items is
enabled
.Sets the snap
tolerance
(in pixels) to use when snapping.Snaps a layout coordinate
point
.Snaps a layout coordinate
point
to the grid.Snaps an
original
layout coordinate to the guides.Snaps an
original
layout coordinate to the item bounds.Snaps a set of
points
to the grid.Snaps a set of
points
to the guides.Snaps a set of
points
to the item bounds.Snaps a layout coordinate
rect
.Returns
True
if snapping to grid is enabled.Returns
True
if snapping to guides is enabled.Returns
True
if snapping to items is enabled.Returns the snap tolerance (in pixels) to use when snapping.
- rtype:
str
Stores the snapper's state in a DOM element.
- readXml(self, gridElement: QDomElement, document: QDomDocument, context: QgsReadWriteContext) bool ¶
Sets the snapper’s state from a DOM element. snapperElement is the DOM node corresponding to the snapper.
See also
- Parameters:
gridElement (QDomElement) –
document (QDomDocument) –
context (QgsReadWriteContext) –
- Return type:
bool
- setSnapToGrid(self, enabled: bool)¶
Sets whether snapping to grid is
enabled
.See also
- Parameters:
enabled (bool) –
- setSnapToGuides(self, enabled: bool)¶
Sets whether snapping to guides is
enabled
.See also
- Parameters:
enabled (bool) –
- setSnapToItems(self, enabled: bool)¶
Sets whether snapping to items is
enabled
.See also
- Parameters:
enabled (bool) –
- setSnapTolerance(self, snapTolerance: int)¶
Sets the snap
tolerance
(in pixels) to use when snapping.See also
- Parameters:
snapTolerance (int) –
- snapPoint(self, point: QPointF | QPoint, scaleFactor: float, horizontalSnapLine: QGraphicsLineItem = None, verticalSnapLine: QGraphicsLineItem = None, ignoreItems: Iterable[QgsLayoutItem] = []) Tuple[QPointF, bool] ¶
Snaps a layout coordinate
point
. Ifpoint
was snapped,snapped
will be set toTrue
.The
scaleFactor
argument should be set to the transformation from scalar transform from layout coordinates to pixels, i.e. the graphics viewtransform()
.m11() value.This method considers snapping to the grid, snap lines, etc.
If the
horizontalSnapLine
andverticalSnapLine
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
- Parameters:
point (Union[QPointF) –
scaleFactor (float) –
horizontalSnapLine (QGraphicsLineItem = None) –
verticalSnapLine (QGraphicsLineItem = None) –
ignoreItems (Iterable[QgsLayoutItem] = []) –
- Return type:
Tuple[QPointF, bool]
- snapPointToGrid(self, point: QPointF | QPoint, scaleFactor: float) Tuple[QPointF, bool, bool] ¶
Snaps a layout coordinate
point
to the grid. Ifpoint
was snapped horizontally,snappedX
will be set toTrue
. Ifpoint
was snapped vertically,snappedY
will be set toTrue
.The
scaleFactor
argument should be set to the transformation from scalar transform from layout coordinates to pixels, i.e. the graphics viewtransform()
.m11() value.If
snapToGrid()
is disabled, this method will return the point unchanged.See also
- Parameters:
point (Union[QPointF) –
scaleFactor (float) –
- Return type:
Tuple[QPointF, bool, bool]
- snapPointToGuides(self, original: float, orientation: Qt.Orientation, scaleFactor: float) Tuple[float, bool] ¶
Snaps an
original
layout coordinate to the guides. If the point was snapped,snapped
will be set toTrue
.The
scaleFactor
argument should be set to the transformation from scalar transform from layout coordinates to pixels, i.e. the graphics viewtransform()
.m11() value.If
snapToGuides()
is disabled, this method will return the point unchanged.See also
- Parameters:
original (float) –
orientation (Qt.Orientation) –
scaleFactor (float) –
- Return type:
Tuple[float, bool]
- snapPointToItems(self, original: float, orientation: Qt.Orientation, scaleFactor: float, ignoreItems: Iterable[QgsLayoutItem], snapLine: QGraphicsLineItem = None) Tuple[float, bool] ¶
Snaps an
original
layout coordinate to the item bounds. If the point was snapped,snapped
will be set toTrue
.The
scaleFactor
argument should be set to the transformation from scalar transform from layout coordinates to pixels, i.e. the graphics viewtransform()
.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
- Parameters:
original (float) –
orientation (Qt.Orientation) –
scaleFactor (float) –
ignoreItems (Iterable[QgsLayoutItem]) –
snapLine (QGraphicsLineItem = None) –
- Return type:
Tuple[float, bool]
- snapPointsToGrid(self, points: Iterable[QPointF | QPoint], scaleFactor: float) Tuple[QPointF, bool, bool] ¶
Snaps a set of
points
to the grid. If the points were snapped,snapped
will be set toTrue
.The
scaleFactor
argument should be set to the transformation from scalar transform from layout coordinates to pixels, i.e. the graphics viewtransform()
.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
- Parameters:
points (Iterable[Union[QPointF) –
scaleFactor (float) –
- Return type:
Tuple[QPointF, bool, bool]
- snapPointsToGuides(self, points: Iterable[float], orientation: Qt.Orientation, scaleFactor: float) Tuple[float, bool] ¶
Snaps a set of
points
to the guides. If the points were snapped,snapped
will be set toTrue
.The
scaleFactor
argument should be set to the transformation from scalar transform from layout coordinates to pixels, i.e. the graphics viewtransform()
.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
- Parameters:
points (Iterable[float]) –
orientation (Qt.Orientation) –
scaleFactor (float) –
- Return type:
Tuple[float, bool]
- snapPointsToItems(self, points: Iterable[float], orientation: Qt.Orientation, scaleFactor: float, ignoreItems: Iterable[QgsLayoutItem], snapLine: QGraphicsLineItem = None) Tuple[float, bool] ¶
Snaps a set of
points
to the item bounds. If the points were snapped,snapped
will be set toTrue
.The
scaleFactor
argument should be set to the transformation from scalar transform from layout coordinates to pixels, i.e. the graphics viewtransform()
.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
- Parameters:
points (Iterable[float]) –
orientation (Qt.Orientation) –
scaleFactor (float) –
ignoreItems (Iterable[QgsLayoutItem]) –
snapLine (QGraphicsLineItem = None) –
- Return type:
Tuple[float, bool]
- snapRect(self, rect: QRectF, scaleFactor: float, horizontalSnapLine: QGraphicsLineItem = None, verticalSnapLine: QGraphicsLineItem = None, ignoreItems: Iterable[QgsLayoutItem] = []) Tuple[QRectF, bool] ¶
Snaps a layout coordinate
rect
. Ifrect
was snapped,snapped
will be set toTrue
.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 viewtransform()
.m11() value.This method considers snapping to the grid, snap lines, etc.
If the
horizontalSnapLine
andverticalSnapLine
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
- Parameters:
rect (QRectF) –
scaleFactor (float) –
horizontalSnapLine (QGraphicsLineItem = None) –
verticalSnapLine (QGraphicsLineItem = None) –
ignoreItems (Iterable[QgsLayoutItem] = []) –
- Return type:
Tuple[QRectF, bool]
- snapToGrid(self) bool ¶
Returns
True
if snapping to grid is enabled.See also
- Return type:
bool
- snapToGuides(self) bool ¶
Returns
True
if snapping to guides is enabled.See also
- Return type:
bool
- snapToItems(self) bool ¶
Returns
True
if snapping to items is enabled.See also
- Return type:
bool
- snapTolerance(self) int ¶
Returns the snap tolerance (in pixels) to use when snapping.
See also
- Return type:
int
- stringType(self) str ¶
- Return type:
str
- writeXml(self, parentElement: QDomElement, document: QDomDocument, context: QgsReadWriteContext) bool ¶
Stores the snapper’s state in a DOM element. The
parentElement
should refer to the parent layout’s DOM element.See also
- Parameters:
parentElement (QDomElement) –
document (QDomDocument) –
context (QgsReadWriteContext) –
- Return type:
bool