QgsLayoutSnapper class

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

Contents

Base classes

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

Constructors, destructors, conversion operators

QgsLayoutSnapper(QgsLayout* layout)
Constructor for QgsLayoutSnapper, attached to the specified layout.

Public functions

auto layout() -> QgsLayout* override
Returns the layout the object belongs to.
auto readXml(const QDomElement& gridElement, const QDomDocument& document, const QgsReadWriteContext& context) -> bool override
Sets the snapper's state from a DOM element.
void setSnapToGrid(bool enabled)
Sets whether snapping to grid is enabled.
void setSnapToGuides(bool enabled)
Sets whether snapping to guides is enabled.
void setSnapToItems(bool enabled)
Sets whether snapping to items is enabled.
void setSnapTolerance(int snapTolerance)
Sets the snap tolerance (in pixels) to use when snapping.
auto snapPoint(QPointF point, double scaleFactor, bool& snapped, QGraphicsLineItem* horizontalSnapLine = nullptr, QGraphicsLineItem* verticalSnapLine = nullptr, const QList<QgsLayoutItem*>* ignoreItems = nullptr) const -> QPointF
Snaps a layout coordinate point.
auto snapPointsToGrid(const QList<QPointF>& points, double scaleFactor, bool& snappedX, bool& snappedY) const -> QPointF
Snaps a set of points to the grid.
auto snapPointsToGuides(const QList<double>& points, Qt::Orientation orientation, double scaleFactor, bool& snapped) const -> double
Snaps a set of points to the guides.
auto snapPointsToItems(const QList<double>& points, Qt::Orientation orientation, double scaleFactor, const QList<QgsLayoutItem*>& ignoreItems, bool& snapped, QGraphicsLineItem* snapLine = nullptr) const -> double
Snaps a set of points to the item bounds.
auto snapPointToGrid(QPointF point, double scaleFactor, bool& snappedX, bool& snappedY) const -> QPointF
Snaps a layout coordinate point to the grid.
auto snapPointToGuides(double original, Qt::Orientation orientation, double scaleFactor, bool& snapped) const -> double
Snaps an original layout coordinate to the guides.
auto snapPointToItems(double original, Qt::Orientation orientation, double scaleFactor, const QList<QgsLayoutItem*>& ignoreItems, bool& snapped, QGraphicsLineItem* snapLine = nullptr) const -> double
Snaps an original layout coordinate to the item bounds.
auto snapRect(const QRectF& rect, double scaleFactor, bool& snapped, QGraphicsLineItem* horizontalSnapLine = nullptr, QGraphicsLineItem* verticalSnapLine = nullptr, const QList<QgsLayoutItem*>* ignoreItems = nullptr) const -> QRectF
Snaps a layout coordinate rect.
auto snapToGrid() const -> bool
Returns true if snapping to grid is enabled.
auto snapToGuides() const -> bool
Returns true if snapping to guides is enabled.
auto snapToItems() const -> bool
Returns true if snapping to items is enabled.
auto snapTolerance() const -> int
Returns the snap tolerance (in pixels) to use when snapping.
auto stringType() const -> QString override
Returns the object type as a string.
auto writeXml(QDomElement& parentElement, QDomDocument& document, const QgsReadWriteContext& context) const -> bool override
Stores the snapper's state in a DOM element.

Function documentation

bool QgsLayoutSnapper::readXml(const QDomElement& gridElement, const QDomDocument& document, const QgsReadWriteContext& context) override

Sets the snapper's state from a DOM element.

snapperElement is the DOM node corresponding to the snapper.

void QgsLayoutSnapper::setSnapToGrid(bool enabled)

Sets whether snapping to grid is enabled.

void QgsLayoutSnapper::setSnapToGuides(bool enabled)

Sets whether snapping to guides is enabled.

void QgsLayoutSnapper::setSnapToItems(bool enabled)

Sets whether snapping to items is enabled.

void QgsLayoutSnapper::setSnapTolerance(int snapTolerance)

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

QPointF QgsLayoutSnapper::snapPoint(QPointF point, double scaleFactor, bool& snapped, QGraphicsLineItem* horizontalSnapLine = nullptr, QGraphicsLineItem* verticalSnapLine = nullptr, const QList<QgsLayoutItem*>* ignoreItems = nullptr) const

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.

QPointF QgsLayoutSnapper::snapPointsToGrid(const QList<QPointF>& points, double scaleFactor, bool& snappedX, bool& snappedY) const

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.

double QgsLayoutSnapper::snapPointsToGuides(const QList<double>& points, Qt::Orientation orientation, double scaleFactor, bool& snapped) const

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.

double QgsLayoutSnapper::snapPointsToItems(const QList<double>& points, Qt::Orientation orientation, double scaleFactor, const QList<QgsLayoutItem*>& ignoreItems, bool& snapped, QGraphicsLineItem* snapLine = nullptr) const

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.

QPointF QgsLayoutSnapper::snapPointToGrid(QPointF point, double scaleFactor, bool& snappedX, bool& snappedY) const

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.

double QgsLayoutSnapper::snapPointToGuides(double original, Qt::Orientation orientation, double scaleFactor, bool& snapped) const

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.

double QgsLayoutSnapper::snapPointToItems(double original, Qt::Orientation orientation, double scaleFactor, const QList<QgsLayoutItem*>& ignoreItems, bool& snapped, QGraphicsLineItem* snapLine = nullptr) const

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.

QRectF QgsLayoutSnapper::snapRect(const QRectF& rect, double scaleFactor, bool& snapped, QGraphicsLineItem* horizontalSnapLine = nullptr, QGraphicsLineItem* verticalSnapLine = nullptr, const QList<QgsLayoutItem*>* ignoreItems = nullptr) const

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.

bool QgsLayoutSnapper::snapToGrid() const

Returns true if snapping to grid is enabled.

bool QgsLayoutSnapper::snapToGuides() const

Returns true if snapping to guides is enabled.

bool QgsLayoutSnapper::snapToItems() const

Returns true if snapping to items is enabled.

int QgsLayoutSnapper::snapTolerance() const

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

QString QgsLayoutSnapper::stringType() const override

Returns the object type as a string.

This string must be a unique, single word, character only representation of the item type, eg "LayoutScaleBar"

bool QgsLayoutSnapper::writeXml(QDomElement& parentElement, QDomDocument& document, const QgsReadWriteContext& context) const override

Stores the snapper's state in a DOM element.

The parentElement should refer to the parent layout's DOM element.