KoSnapGuide Class Reference

#include <KoSnapGuide.h>

Inheritance diagram for KoSnapGuide:

Public Types
typedef QSharedPointer< KoSnapStrategy >	KoSnapStrategySP
typedef QList< KoSnapStrategySP >	StrategiesList
enum	Strategy {   OrthogonalSnapping = 1 , NodeSnapping = 2 , ExtensionSnapping = 4 , IntersectionSnapping = 8 ,   GridSnapping = 0x10 , BoundingBoxSnapping = 0x20 , GuideLineSnapping = 0x40 , DocumentBoundsSnapping = 0x80 ,   DocumentCenterSnapping = 0x100 , CustomSnapping = 0x200 , PixelSnapping = 0x400 }
	the different possible snap Strategies More...

Public Member Functions
bool	addCustomSnapStrategy (KoSnapStrategy *customStrategy)
KoShape *	additionalEditedShape () const
	returns the extra shapes to use
QRectF	boundingRect ()
	returns the bounding rect of the guide
KoCanvasBase *	canvas () const
	returns the canvas the snap guide is working on
KoSnapGuide::Strategies	enabledSnapStrategies () const
	returns the enabled snap strategies
void	enableSnapping (bool on)
	enables the snapping guides
void	enableSnapStrategies (Strategies strategies)
	enables the strategies used for snapping
void	enableSnapStrategy (Strategy type, bool value)
QList< KoPathPoint * >	ignoredPathPoints () const
	Returns list of ignored points.
QList< KoShape * >	ignoredShapes () const
	Returns list of ignored shapes.
bool	isSnapping () const
	returns if snapping is enabled
bool	isStrategyEnabled (Strategy type) const
	KoSnapGuide (KoCanvasBase *canvas)
	Creates the snap guide to work on the given canvas.
void	overrideSnapStrategy (Strategy type, KoSnapStrategy *strategy)
void	paint (QPainter &painter, const KoViewConverter &converter, const KoColorDisplayRendererInterface *displayRenderer)
	paints the guide
	Private (KoCanvasBase *parentCanvas)
void	reset ()
	Resets the snap guide.
void	setAdditionalEditedShape (KoShape *shape)
	Adds an additional shape to snap to (useful when creating a path)
void	setIgnoredPathPoints (const QList< KoPathPoint * > &ignoredPoints)
	Sets a list of path points to ignore.
void	setIgnoredShapes (const QList< KoShape * > &ignoredShapes)
	Sets list of ignored shapes.
void	setSnapDistance (int distance)
	sets the snap distances in pixels
QPointF	snap (const QPointF &mousePosition, const QPointF &dragOffset, Qt::KeyboardModifiers modifiers)
QPointF	snap (const QPointF &mousePosition, Qt::KeyboardModifiers modifiers)
	snaps the mouse position, returns if mouse was snapped
int	snapDistance () const
	returns the snap distance in pixels
virtual	~KoSnapGuide ()
	~Private ()

Public Attributes
bool	active
KoShape *	additionalEditedShape
KoCanvasBase *	canvas
KoSnapStrategySP	currentStrategy
QList< KoPathPoint * >	ignoredPoints
QList< KoShape * >	ignoredShapes
int	snapDistance
StrategiesList	strategies
KoSnapGuide::Strategies	usedStrategies

Private Attributes
const QScopedPointer< Private >	d
Private Attributes inherited from Private
KisCanvas2 *	canvas
int	displayedFrame
int	intendedFrame

Additional Inherited Members
Private Member Functions inherited from Private
	Private (KisCanvas2 *c)

Detailed Description

This class is the place where all the snapping (i.e. snap to grid) is handled.

What this class does is snapping a given position (i.e. mouse position) to various snapping targets like grid, boundbox etc. The snap guide does not know anything about the specific snapping target. This is handled by the different snapping strategies which are derived from KoSnapStrategy. Snapping strategies can be enabled/disabled by passing a mask of corresponding snapping ids to KoSnapGuide::enableSnapStrategies. There can be one or more snapping strategies enabled at the same time. The best result (with the nearest distance to the original position) is then returned to the caller of KoSnapGuide::snap.

The snap guide is part of the KoCanvasBase class and thus can be accessed by any tool or application via the canvas pointer. For letting the user manage which snap strategies to enable, there is a snap guide config widget in guiutils.

Definition at line 24 of file KoSnapGuide.cpp.

Member Typedef Documentation

KoSnapStrategySP

typedef QSharedPointer<KoSnapStrategy> KoSnapGuide::KoSnapStrategySP

Definition at line 42 of file KoSnapGuide.cpp.

StrategiesList

typedef QList<KoSnapStrategySP> KoSnapGuide::StrategiesList

Definition at line 43 of file KoSnapGuide.cpp.

Member Enumeration Documentation

Strategy

enum KoSnapGuide::Strategy

the different possible snap Strategies

Enumerator
OrthogonalSnapping
NodeSnapping
ExtensionSnapping
IntersectionSnapping
GridSnapping
BoundingBoxSnapping
GuideLineSnapping
DocumentBoundsSnapping
DocumentCenterSnapping
CustomSnapping
PixelSnapping

Definition at line 49 of file KoSnapGuide.h.

    {
        OrthogonalSnapping = 1,
        NodeSnapping = 2,
        ExtensionSnapping = 4,
        IntersectionSnapping = 8,
        GridSnapping = 0x10,
        BoundingBoxSnapping = 0x20,
        GuideLineSnapping = 0x40,
        DocumentBoundsSnapping = 0x80,
        DocumentCenterSnapping = 0x100,
        CustomSnapping = 0x200,
        PixelSnapping = 0x400
    };

Constructor & Destructor Documentation

~Private()

KoSnapGuide::~Private ( )

inline

Definition at line 34 of file KoSnapGuide.cpp.

    {
        strategies.clear();
    }

KoSnapGuide()

KoSnapGuide::KoSnapGuide ( KoCanvasBase * canvas )

explicit

Creates the snap guide to work on the given canvas.

Definition at line 54 of file KoSnapGuide.cpp.

    : d(new Private(canvas))
{
    d->strategies.append(toQShared(new GridSnapStrategy()));
    d->strategies.append(toQShared(new NodeSnapStrategy()));
    d->strategies.append(toQShared(new OrthogonalSnapStrategy()));
    d->strategies.append(toQShared(new ExtensionSnapStrategy()));
    d->strategies.append(toQShared(new IntersectionSnapStrategy()));
    d->strategies.append(toQShared(new BoundingBoxSnapStrategy()));
}

References d, and toQShared().

~KoSnapGuide()

KoSnapGuide::~KoSnapGuide ( )

virtual

Definition at line 65 of file KoSnapGuide.cpp.

{
}

Member Function Documentation

addCustomSnapStrategy()

bool KoSnapGuide::addCustomSnapStrategy

(

KoSnapStrategy *

customStrategy

)

Adds a custom snap strategy

The snap guide take ownership of the strategy. All custom strategies are destroyed when calling reset().

Definition at line 103 of file KoSnapGuide.cpp.

{
    if (!customStrategy || customStrategy->type() != CustomSnapping)
        return false;
 
    d->strategies.append(toQShared(customStrategy));
    return true;
}

References CustomSnapping, d, toQShared(), and KoSnapStrategy::type().

additionalEditedShape()

KoShape * KoSnapGuide::additionalEditedShape

(

)

const

returns the extra shapes to use

boundingRect()

QRectF KoSnapGuide::boundingRect

(

)

returns the bounding rect of the guide

Definition at line 200 of file KoSnapGuide.cpp.

{
    QRectF rect;
 
    if (d->currentStrategy) {
        rect = d->currentStrategy->decoration(*d->canvas->viewConverter()).boundingRect();
        return rect.adjusted(-2, -2, 2, 2);
    } else {
        return rect;
    }
}

References d.

canvas()

KoCanvasBase * KoSnapGuide::canvas

(

)

const

returns the canvas the snap guide is working on

enabledSnapStrategies()

KoSnapGuide::Strategies KoSnapGuide::enabledSnapStrategies

(

)

const

returns the enabled snap strategies

Definition at line 98 of file KoSnapGuide.cpp.

{
    return d->usedStrategies;
}

References d.

enableSnapping()

void KoSnapGuide::enableSnapping

(

bool

on

)

enables the snapping guides

Definition at line 132 of file KoSnapGuide.cpp.

{
    d->active = on;
}

References d.

enableSnapStrategies()

void KoSnapGuide::enableSnapStrategies

(

Strategies

strategies

)

enables the strategies used for snapping

Definition at line 93 of file KoSnapGuide.cpp.

{
    d->usedStrategies = strategies;
}

References d, and strategies.

enableSnapStrategy()

void KoSnapGuide::enableSnapStrategy	(	Strategy	type,
		bool	value )

Definition at line 79 of file KoSnapGuide.cpp.

{
    if (value) {
        d->usedStrategies |= type;
    } else {
        d->usedStrategies &= ~type;
    }
}

References d, and value().

ignoredPathPoints()

QList< KoPathPoint * > KoSnapGuide::ignoredPathPoints

(

)

const

Returns list of ignored points.

Definition at line 250 of file KoSnapGuide.cpp.

{
    return d->ignoredPoints;
}

References d.

ignoredShapes()

QList< KoShape * > KoSnapGuide::ignoredShapes

(

)

const

Returns list of ignored shapes.

isSnapping()

bool KoSnapGuide::isSnapping

(

)

const

returns if snapping is enabled

Definition at line 137 of file KoSnapGuide.cpp.

{
    return d->active;
}

References d.

isStrategyEnabled()

bool KoSnapGuide::isStrategyEnabled

(

Strategy

type

)

const

Definition at line 88 of file KoSnapGuide.cpp.

{
    return d->usedStrategies & type;
}

References d.

overrideSnapStrategy()

void KoSnapGuide::overrideSnapStrategy	(	Strategy	type,
		KoSnapStrategy *	strategy )

Overrides the first entry of a strategy type with a strategy strategy. Note that basically strategy->type() may not be equal to type and that is ok. strategy may also be null.

Definition at line 112 of file KoSnapGuide.cpp.

{
    for (auto it = d->strategies.begin(); it != d->strategies.end(); /*noop*/) {
        if ((*it)->type() == type) {
            if (strategy) {
                *it = toQShared(strategy);
            } else {
                it = d->strategies.erase(it);
            }
            return;
        } else {
            ++it;
        }
    }
 
    if (strategy) {
        d->strategies.append(toQShared(strategy));
    }
}

References d, and toQShared().

paint()

void KoSnapGuide::paint	(	QPainter &	painter,
		const KoViewConverter &	converter,
		const KoColorDisplayRendererInterface *	displayRenderer )

paints the guide

Definition at line 212 of file KoSnapGuide.cpp.

{
    if (! d->currentStrategy || ! d->active)
        return;
 
    QPainterPath decoration = d->currentStrategy->decoration(converter);
 
    int thickness = d->canvas->resourceManager()? d->canvas->resourceManager()->decorationThickness(): 1;
 
    painter.setBrush(Qt::NoBrush);
 
    KoColor c;
    c.fromQColor(Qt::white);
 
    QPen whitePen(displayRenderer->convertColorToDisplayColorSpace(c), thickness);
    whitePen.setCosmetic(true);
    whitePen.setStyle(Qt::SolidLine);
    painter.setPen(whitePen);
    painter.drawPath(decoration);
 
    c.fromQColor(Qt::red);
    QPen redPen(displayRenderer->convertColorToDisplayColorSpace(c), thickness);
    redPen.setCosmetic(true);
    redPen.setStyle(Qt::DotLine);
    painter.setPen(redPen);
    painter.drawPath(decoration);
}

References KoColorDisplayRendererInterface::convertColorToDisplayColorSpace(), d, and KoColor::fromQColor().

Private()

KoSnapGuide::Private ( KoCanvasBase * parentCanvas )

inline

Definition at line 27 of file KoSnapGuide.cpp.

        : canvas(parentCanvas), additionalEditedShape(0), currentStrategy(0),
        active(true),
        snapDistance(10)
    {
    }

reset()

void KoSnapGuide::reset

(

)

Resets the snap guide.

Definition at line 265 of file KoSnapGuide.cpp.

{
    d->currentStrategy.clear();
    d->additionalEditedShape = 0;
    d->ignoredPoints.clear();
    d->ignoredShapes.clear();
    // remove all custom strategies
    int strategyCount = d->strategies.count();
    for (int i = strategyCount-1; i >= 0; --i) {
        if (d->strategies[i]->type() == CustomSnapping) {
            d->strategies.removeAt(i);
        }
    }
}

References CustomSnapping, and d.

setAdditionalEditedShape()

void KoSnapGuide::setAdditionalEditedShape

(

KoShape *

shape

)

Adds an additional shape to snap to (useful when creating a path)

Definition at line 69 of file KoSnapGuide.cpp.

{
    d->additionalEditedShape = shape;
}

References d.

setIgnoredPathPoints()

void KoSnapGuide::setIgnoredPathPoints

(

const QList< KoPathPoint * > &

ignoredPoints

)

Sets a list of path points to ignore.

Definition at line 245 of file KoSnapGuide.cpp.

{
    d->ignoredPoints = ignoredPoints;
}

References d, and ignoredPoints.

setIgnoredShapes()

void KoSnapGuide::setIgnoredShapes

(

const QList< KoShape * > &

ignoredShapes

)

Sets list of ignored shapes.

Definition at line 255 of file KoSnapGuide.cpp.

{
    d->ignoredShapes = ignoredShapes;
}

References d, and ignoredShapes.

setSnapDistance()

void KoSnapGuide::setSnapDistance

(

int

distance

)

sets the snap distances in pixels

Definition at line 142 of file KoSnapGuide.cpp.

{
    d->snapDistance = qAbs(distance);
}

References d, and distance().

snap() [1/2]

QPointF KoSnapGuide::snap	(	const QPointF &	mousePosition,
		const QPointF &	dragOffset,
		Qt::KeyboardModifiers	modifiers )

Definition at line 152 of file KoSnapGuide.cpp.

{
    QPointF pos = mousePosition + dragOffset;
    pos = snap(pos, modifiers);
    return pos - dragOffset;
}

References snap().

snap() [2/2]

QPointF KoSnapGuide::snap	(	const QPointF &	mousePosition,
		Qt::KeyboardModifiers	modifiers )

snaps the mouse position, returns if mouse was snapped

Definition at line 159 of file KoSnapGuide.cpp.

{
    d->currentStrategy.clear();
 
    if (! d->active || (modifiers & Qt::ShiftModifier))
        return mousePosition;
 
    KoSnapProxy proxy(this);
 
    using PriorityTuple = std::tuple<KoSnapStrategy::SnapType, qreal>;
    PriorityTuple minPriority(KoSnapStrategy::ToLine, HUGE_VAL);
 
    const qreal maxSnapDistance = d->canvas->viewConverter()->
            viewToDocument(QSizeF(d->snapDistance,
                                  d->snapDistance)).width();
 
    foreach (Private::KoSnapStrategySP strategy, d->strategies) {
        if (d->usedStrategies & strategy->type() ||
            strategy->type() == GridSnapping ||
            strategy->type() == CustomSnapping) {
 
            if (! strategy->snap(mousePosition, &proxy, maxSnapDistance))
                continue;
 
            QPointF snapCandidate = strategy->snappedPosition();
            qreal distance = KoSnapStrategy::squareDistance(snapCandidate, mousePosition);
 
            const PriorityTuple priority(strategy->snappedType(), distance);
            if (priority < minPriority) {
                d->currentStrategy = strategy;
                minPriority = priority;
            }
        }
    }
 
    if (! d->currentStrategy)
        return mousePosition;
 
    return d->currentStrategy->snappedPosition();
}

References CustomSnapping, d, distance(), GridSnapping, KoSnapStrategy::squareDistance(), and KoSnapStrategy::ToLine.

snapDistance()

int KoSnapGuide::snapDistance

(

)

const

returns the snap distance in pixels

Member Data Documentation

active

bool KoSnapGuide::active

Definition at line 48 of file KoSnapGuide.cpp.

additionalEditedShape

KoShape * KoSnapGuide::additionalEditedShape

Definition at line 40 of file KoSnapGuide.cpp.

canvas

KoCanvasBase * KoSnapGuide::canvas

Definition at line 39 of file KoSnapGuide.cpp.

currentStrategy

KoSnapStrategySP KoSnapGuide::currentStrategy

Definition at line 45 of file KoSnapGuide.cpp.

d

const QScopedPointer<Private> KoSnapGuide::d

private

Definition at line 143 of file KoSnapGuide.h.

ignoredPoints

QList<KoPathPoint*> KoSnapGuide::ignoredPoints

Definition at line 50 of file KoSnapGuide.cpp.

ignoredShapes

QList< KoShape * > KoSnapGuide::ignoredShapes

Definition at line 51 of file KoSnapGuide.cpp.

snapDistance

int KoSnapGuide::snapDistance

Definition at line 49 of file KoSnapGuide.cpp.

strategies

StrategiesList KoSnapGuide::strategies

Definition at line 44 of file KoSnapGuide.cpp.

usedStrategies

KoSnapGuide::Strategies KoSnapGuide::usedStrategies

Definition at line 47 of file KoSnapGuide.cpp.

---

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

• libs/flake/KoSnapGuide.cpp
• libs/flake/KoSnapGuide.h