ItemSpace Class Reference

ItemSpace class Implements "push and pull" dynamics of rectangular items in 2D space. More...

#include <itemspace.h>

List of all members.

Classes
class	ItemGroup
	Represents a group of overlapping items. More...
class	ItemSpaceItem
Public Types
enum	DirectionFlag { DirLeft = 1, DirRight = 2, DirUp = 4, DirDown = 8 }
enum	PushPowerFlag { NoPower = 0, PushAwayFromPreferred = 1, PushOverBorder = 2 }
Public Member Functions
	ItemSpace ()
void	addItem (ItemSpaceItem newItem)
bool	locateItemByPosition (int pos, int *groupIndex, int *itemInGroup) const
bool	locateItemByUser (QVariant user, int *groupIndex, int *itemInGroup) const
void	moveItem (int groupIndex, int itemInGroup, QRectF newGeom)
void	offsetPositions (const QPointF &offset)
qreal	performPush (int groupId, Direction direction, qreal amount, PushPower power)
bool	positionedProperly (QRectF itemGeom)
QList< QPointF >	positionVertically (const QSizeF &itemSize, Qt::Alignment align, bool limitedSpace, bool findAll) const
qreal	positionVisibility (QRectF geom)
void	removeItem (int groupIndex, int itemInGroup)
void	resizeItem (int groupId, int itemInGroup, QSizeF newSize)
void	setWorkingArea (QSizeF area)
Public Attributes
QList< ItemGroup >	m_groups
qreal	placementSpacing
qreal	screenSpacing
qreal	shiftingSpacing
Qt::Alignment	spaceAlignment
QSizeF	workingGeom

---

Detailed Description

ItemSpace class Implements "push and pull" dynamics of rectangular items in 2D space.

All isolated motion folows these rules:

• overlapping items stay at the same positions relative to each other
• non-overlapping items stay such and do not jump one over another

There are two types of motion:

• forced motion: an item moves all items on its way, even if any of them would intersect the border of the working area
• non-forced motion: an item moves items on its way only as much as the border of the working area

Items are pushed to fit inside the working area: if an item is in the way of one of the borders of alignment, the move is forced; if an item is in the way of one of the opposite borders, the move is non-forced.

An item can have a "preferred position". Such item is moved non-forced in the direction towards the preferred position.

Definition at line 38 of file itemspace.h.

---

Member Enumeration Documentation

enum ItemSpace::DirectionFlag

Enumerator:

DirLeft
DirRight
DirUp
DirDown

Definition at line 61 of file itemspace.h.

enum ItemSpace::PushPowerFlag

Enumerator:

NoPower
PushAwayFromPreferred
PushOverBorder

Definition at line 69 of file itemspace.h.

---

Constructor & Destructor Documentation

ItemSpace::ItemSpace

(

)

Definition at line 30 of file itemspace.cpp.

---

Member Function Documentation

void ItemSpace::addItem

(

ItemSpaceItem

newItem

)

Add a new item.

Groups will be updated to reflect the change.

Parameters:

newItem

the item to add; must be initialized

Definition at line 688 of file itemspace.cpp.

bool ItemSpace::locateItemByPosition	(	int	pos,
		int *	groupIndex,
		int *	itemInGroup
	)			const

Find an item by its number as if we iterated over all groups and over all items in each group.

Definition at line 877 of file itemspace.cpp.

bool ItemSpace::locateItemByUser	(	QVariant	user,
		int *	groupIndex,
		int *	itemInGroup
	)			const

Find an item by its 'user' parameter.

Definition at line 892 of file itemspace.cpp.

void ItemSpace::moveItem	(	int	groupIndex,
		int	itemInGroup,
		QRectF	newGeom
	)

Move the item to a new position.

Parameters:

	groupIndex	the index of the item's group
	itemInGroup	the index of the item in its group
	newGeom	the new geometry of the item

Definition at line 701 of file itemspace.cpp.

void ItemSpace::offsetPositions

(

const QPointF &

offset

)

Offset the positions of all items.

Definition at line 172 of file itemspace.cpp.

qreal ItemSpace::performPush	(	int	groupId,
		Direction	direction,
		qreal	amount,
		PushPower	power
	)

Push an item group.

Requires no initialization.

Parameters:

	groupId	the index of the group
	direction	in which direction pushing will be done
	amount	how much to push
	power	how 'powerful' the push is; what types of obstacles can be pushed or ignored

Returns:

how much the item group was really pushed

Definition at line 186 of file itemspace.cpp.

bool ItemSpace::positionedProperly

(

QRectF

itemGeom

)

Definition at line 196 of file itemspace.cpp.

QList< QPointF > ItemSpace::positionVertically	(	const QSizeF &	itemSize,
		Qt::Alignment	align,
		bool	limitedSpace,
		bool	findAll
	)			const

Finds an empty place for an item.

Tries to stack the item vertically, starting in the corner of alignment, and advances horizontally once no more positions are valid.

Parameters:

	itemSize	the size of the item; placementSpacing is already considered
	align	the corner of the screen where position testing will begin (and in what directions it will advance) must be an OR of Qt::AlignLeft or Qt::AlignRight and Qt::AlignTop or Qt::AlignBottom
	limitedSpace	if true, positions outside the working area will not be considered; otherwise, positions will only be limited by the borders at the alignment corner.
	findAll	if false, searching will stop after the first valid position

Returns:

all positions found

Definition at line 202 of file itemspace.cpp.

qreal ItemSpace::positionVisibility

(

QRectF

geom

)

Returns the visibility of an item at a given position.

This is the part of the item inside the working area.

Definition at line 163 of file itemspace.cpp.

void ItemSpace::removeItem	(	int	groupIndex,
		int	itemInGroup
	)

Removes an item by its location.

Parameters:

	groupIndex	the index of the item's group
	itemInGroup	the index of the item in its group

Definition at line 694 of file itemspace.cpp.

void ItemSpace::resizeItem	(	int	groupId,
		int	itemInGroup,
		QSizeF	newSize
	)

Resize an item.

The item's alignment corner will be the center of resizing.

Parameters:

	groupId	the index of the group
	direction	in which direction pushing will be done
	newSize	the item's new size

Definition at line 715 of file itemspace.cpp.

void ItemSpace::setWorkingArea

(

QSizeF

area

)

Definition at line 39 of file itemspace.cpp.

---

Member Data Documentation

QList<ItemGroup> ItemSpace::m_groups

All item groups.

Definition at line 271 of file itemspace.h.

qreal ItemSpace::placementSpacing

Definition at line 276 of file itemspace.h.

qreal ItemSpace::screenSpacing

Definition at line 277 of file itemspace.h.

qreal ItemSpace::shiftingSpacing

Definition at line 278 of file itemspace.h.

Qt::Alignment ItemSpace::spaceAlignment

Definition at line 273 of file itemspace.h.

QSizeF ItemSpace::workingGeom

Definition at line 274 of file itemspace.h.

---

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

• itemspace.h
• itemspace.cpp