QGIS API Documentation  3.18.1-Zürich (202f1bf7e5)
Public Member Functions | Friends | List of all members
QgsLayoutSnapper Class Reference

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

#include <qgslayoutsnapper.h>

Inheritance diagram for QgsLayoutSnapper:
Inheritance graph
[legend]

Public Member Functions

 QgsLayoutSnapper (QgsLayout *layout)
 Constructor for QgsLayoutSnapper, attached to the specified layout. More...
 
QgsLayoutlayout () override
 Returns the layout the object belongs to. More...
 
bool readXml (const QDomElement &gridElement, const QDomDocument &document, const QgsReadWriteContext &context) override
 Sets the snapper's state from a DOM element. More...
 
void setSnapToGrid (bool enabled)
 Sets whether snapping to grid is enabled. More...
 
void setSnapToGuides (bool enabled)
 Sets whether snapping to guides is enabled. More...
 
void setSnapToItems (bool enabled)
 Sets whether snapping to items is enabled. More...
 
void setSnapTolerance (int snapTolerance)
 Sets the snap tolerance (in pixels) to use when snapping. More...
 
QPointF snapPoint (QPointF point, double scaleFactor, bool &snapped, QGraphicsLineItem *horizontalSnapLine=nullptr, QGraphicsLineItem *verticalSnapLine=nullptr, const QList< QgsLayoutItem * > *ignoreItems=nullptr) const
 Snaps a layout coordinate point. More...
 
QPointF snapPointsToGrid (const QList< QPointF > &points, double scaleFactor, bool &snappedX, bool &snappedY) const
 Snaps a set of points to the grid. More...
 
double snapPointsToGuides (const QList< double > &points, Qt::Orientation orientation, double scaleFactor, bool &snapped) const
 Snaps a set of points to the guides. More...
 
double 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. More...
 
QPointF snapPointToGrid (QPointF point, double scaleFactor, bool &snappedX, bool &snappedY) const
 Snaps a layout coordinate point to the grid. More...
 
double snapPointToGuides (double original, Qt::Orientation orientation, double scaleFactor, bool &snapped) const
 Snaps an original layout coordinate to the guides. More...
 
double 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. More...
 
QRectF 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. More...
 
bool snapToGrid () const
 Returns true if snapping to grid is enabled. More...
 
bool snapToGuides () const
 Returns true if snapping to guides is enabled. More...
 
bool snapToItems () const
 Returns true if snapping to items is enabled. More...
 
int snapTolerance () const
 Returns the snap tolerance (in pixels) to use when snapping. More...
 
QString stringType () const override
 Returns the object type as a string. More...
 
bool writeXml (QDomElement &parentElement, QDomDocument &document, const QgsReadWriteContext &context) const override
 Stores the snapper's state in a DOM element. More...
 
- Public Member Functions inherited from QgsLayoutSerializableObject
QgsAbstractLayoutUndoCommandcreateCommand (const QString &text, int id, QUndoCommand *parent=nullptr) override
 Creates a new layout undo command with the specified text and parent. More...
 
- Public Member Functions inherited from QgsLayoutUndoObjectInterface
virtual ~QgsLayoutUndoObjectInterface ()=default
 Destructor for QgsLayoutUndoObjectInterface. More...
 

Friends

class QgsLayoutSnapperUndoCommand
 

Detailed Description

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

Since
QGIS 3.0

Definition at line 36 of file qgslayoutsnapper.h.

Constructor & Destructor Documentation

◆ QgsLayoutSnapper()

QgsLayoutSnapper::QgsLayoutSnapper ( QgsLayout layout)

Constructor for QgsLayoutSnapper, attached to the specified layout.

Definition at line 24 of file qgslayoutsnapper.cpp.

Member Function Documentation

◆ layout()

QgsLayout * QgsLayoutSnapper::layout ( )
overridevirtual

Returns the layout the object belongs to.

Implements QgsLayoutSerializableObject.

Definition at line 31 of file qgslayoutsnapper.cpp.

◆ readXml()

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

Sets the snapper's state from a DOM element.

snapperElement is the DOM node corresponding to the snapper.

See also
writeXml()

Implements QgsLayoutSerializableObject.

Definition at line 434 of file qgslayoutsnapper.cpp.

◆ setSnapToGrid()

void QgsLayoutSnapper::setSnapToGrid ( bool  enabled)

Sets whether snapping to grid is enabled.

See also
snapToGrid()

Definition at line 41 of file qgslayoutsnapper.cpp.

◆ setSnapToGuides()

void QgsLayoutSnapper::setSnapToGuides ( bool  enabled)

Sets whether snapping to guides is enabled.

See also
snapToGuides()

Definition at line 46 of file qgslayoutsnapper.cpp.

◆ setSnapToItems()

void QgsLayoutSnapper::setSnapToItems ( bool  enabled)

Sets whether snapping to items is enabled.

See also
snapToItems()

Definition at line 51 of file qgslayoutsnapper.cpp.

◆ setSnapTolerance()

void QgsLayoutSnapper::setSnapTolerance ( int  snapTolerance)

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

See also
snapTolerance()

Definition at line 36 of file qgslayoutsnapper.cpp.

◆ snapPoint()

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.

See also
snapRect()

Definition at line 56 of file qgslayoutsnapper.cpp.

◆ snapPointsToGrid()

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.

See also
snapPointToGrid()

Definition at line 195 of file qgslayoutsnapper.cpp.

◆ snapPointsToGuides()

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.

See also
snapPointToGuides()

Definition at line 269 of file qgslayoutsnapper.cpp.

◆ snapPointsToItems()

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.

See also
snapPointToItems()

Definition at line 316 of file qgslayoutsnapper.cpp.

◆ snapPointToGrid()

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.

See also
snapPointsToGrid()

Definition at line 189 of file qgslayoutsnapper.cpp.

◆ snapPointToGuides()

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.

See also
snapPointsToGuides()

Definition at line 263 of file qgslayoutsnapper.cpp.

◆ snapPointToItems()

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.

See also
snapPointsToItems()

Definition at line 309 of file qgslayoutsnapper.cpp.

◆ snapRect()

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.

See also
snapPoint()

Definition at line 119 of file qgslayoutsnapper.cpp.

◆ snapToGrid()

bool QgsLayoutSnapper::snapToGrid ( ) const
inline

Returns true if snapping to grid is enabled.

See also
setSnapToGrid()

Definition at line 65 of file qgslayoutsnapper.h.

◆ snapToGuides()

bool QgsLayoutSnapper::snapToGuides ( ) const
inline

Returns true if snapping to guides is enabled.

See also
setSnapToGuides()

Definition at line 77 of file qgslayoutsnapper.h.

◆ snapToItems()

bool QgsLayoutSnapper::snapToItems ( ) const
inline

Returns true if snapping to items is enabled.

See also
setSnapToItems()

Definition at line 89 of file qgslayoutsnapper.h.

◆ snapTolerance()

int QgsLayoutSnapper::snapTolerance ( ) const
inline

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

See also
setSnapTolerance()

Definition at line 59 of file qgslayoutsnapper.h.

◆ stringType()

QString QgsLayoutSnapper::stringType ( ) const
inlineoverridevirtual

Returns the object type as a string.

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

Implements QgsLayoutSerializableObject.

Definition at line 46 of file qgslayoutsnapper.h.

◆ writeXml()

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

Stores the snapper's state in a DOM element.

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

See also
readXml()

Implements QgsLayoutSerializableObject.

Definition at line 421 of file qgslayoutsnapper.cpp.

Friends And Related Function Documentation

◆ QgsLayoutSnapperUndoCommand

friend class QgsLayoutSnapperUndoCommand
friend

Definition at line 273 of file qgslayoutsnapper.h.


The documentation for this class was generated from the following files: