Qtilities::Core::SubjectIterator< T > Class Template Reference

An non-const iterator which iterates throught the subjects of an Observer. More...

#include <SubjectIterator.h>

Inheritance diagram for Qtilities::Core::SubjectIterator< T >:

List of all members.

Public Types
enum	ObserverIterationLevel { IterateChildren, IterateSiblings }
	The level to use when passing only an observer in your constructor. More...

Public Member Functions
T *	current () const
	Gets the current item in the context iterated through.
T *	first ()
	The first item in the context iterated through.
T *	last ()
	The last item in the context iterated through.
T *	next ()
	The next item in the context iterated through.
T *	previous ()
	The previous item in the context iterated through.
void	setCurrent (const T *current)
	Sets the current item in the context iterated through.
	SubjectIterator (const T *subject, const Observer *observer=0, int iterator_id=-1)
	Default constructor.
	SubjectIterator (const Observer *observer, ObserverIterationLevel iteration_level, const Observer *sibling_iteration_parent_observer=0, int iterator_id=-1)
	Observer based constructor.
Public Member Functions inherited from Qtilities::Core::Interfaces::IIterator< T >
virtual bool	hasNext ()
	Indicates if a next item exists.
virtual bool	hasPrevious ()
	Indicates if a previous item exists.
virtual T *	operator++ ()
	Prefix increment.
virtual T *	operator++ (int x)
	Postfix increment.
virtual T *	operator-- ()
	Prefix decrement.
virtual T *	operator-- (int x)
	Postfix decrement.

---

Detailed Description

template<class T>
class Qtilities::Core::SubjectIterator< T >

An non-const iterator which iterates throught the subjects of an Observer.

The SubjectIterator allows you to easily iterate over the subjects in an observer in the order shown below:

Subject Iteration Order

Lets build this example tree:

TreeNode node;
TreeItem* item1 = node.addItem("1");
TreeItem* item2 = node.addItem("2");
node.addItem("3");
node.addItem("4");

SubjectIterator<Qtilities::CoreGui::TreeItem> itr(item1);

qDebug() << itr.current()->objectName();
while (itr.hasNext()) {
    qDebug() << itr.next()->objectName();
}

// In this case the result would be:
// >> 1
// >> 2
// >> 3
// >> 4

It is also possible to specify the current location of your iterator:

SubjectIterator<Qtilities::CoreGui::TreeItem> itr(item2);

// In this case item1 will be skipped:
qDebug() << itr.current()->objectName();
while (itr.hasNext()) {
    qDebug() << itr.next()->objectName();
}

// In this case the result would be:
// >> 2
// >> 3
// >> 4

In the simple examples above we didn't need to worry about cases where tree items can have multiple parents. If they do have multiple parents, we must specify the Observer that we are interested in:

TreeNode node;
TreeNode* nodeA = node.addNode("A");
TreeNode* nodeB = node.addNode("B");
nodeA->addItem("1");
TreeItem* shared_item = nodeA->addItem("2");
nodeA->addItem("3");
nodeB->addItem("4");
nodeB->addItem("5");
nodeB->attachSubject(shared_item);
nodeB->addItem("6");

// If we want to iterate through the subjects in nodeA:
SubjectIterator<QObject> itrA(nodeA,SubjectIterator<QObject>::IterateChildren);

// In this case item1 will not be skipped (approach 1):
while (itrA.hasNext()) {
    qDebug() << itrA.current()->objectName();
    itrA.next();
}

// In this case the result would be:
// >> 1
// >> 2
// >> 3

// If we want to iterate through the subjects in nodeB:
SubjectIterator<QObject> itrB(nodeB,SubjectIterator<QObject>::IterateChildren);

// In this case item1 will be skipped (approach 2):
qDebug() << itrB.current()->objectName();
while (itrB.hasNext()) {
    qDebug() << itrB.next()->objectName();
}

// In this case the result would be:
// >> 4
// >> 5
// >> 2
// >> 6

See also:

ConstSubjectIterator, TreeIterator

This class was added in Qtilities v1.0.

---

Member Enumeration Documentation

template<class T >

enum Qtilities::Core::SubjectIterator::ObserverIterationLevel

The level to use when passing only an observer in your constructor.

Enumerator:

IterateChildren	Iterate on the observer's children.
IterateSiblings	Iterate on the observer's siblings. In this case T must be a subclass of Observer.

---

Constructor & Destructor Documentation

template<class T >

Qtilities::Core::SubjectIterator< T >::SubjectIterator ( const T *  subject, const Observer *  observer = 0, int  iterator_id = -1  )

inline

Default constructor.

Parameters:

subject	The current subject where your iterator must start.
observer	This is an optional parameter which is needed when your subject is observed in multiple contexts. In that case, the observer must be specified in order to know which observer parent to use.
iterator_id	Internal iterator ID. You should never use this directly.

template<class T >

Qtilities::Core::SubjectIterator< T >::SubjectIterator ( const Observer *  observer, ObserverIterationLevel  iteration_level, const Observer *  sibling_iteration_parent_observer = 0, int  iterator_id = -1  )

inline

Observer based constructor.

Parameters:

observer	The observer that must be used in cases where multiple subjects have multiple parents.
iteration_level	Indicates on which level the observer must be interated.
sibling_iteration_parent_observer	When interating over siblings of an obsever (iteration_level = IterateSiblings), *it is necessary to specify the parent of the siblings you are iterating when any of the siblings has multiple parents.
iterator_id	Internal iterator ID. You should never use this directly.