ElementDoc Class Reference

The ElementDoc class extends Doc to provide functionality to allow abstract "elements" to be used in a document. More...

#include <elementdoc.h>

Inheritance diagram for ElementDoc:

AttributeDoc Doc AbstractModel DomAccessibleState MvcBase Diagram List of all members.

Public Member Functions

 ElementDoc (QObject *parent)
 ElementDoc (const QString &name, QObject *parent)
ElementDocControllerelementDocController () const
QList< AbstractElement * > elements () const
QList< AbstractElement * > elements (int type) const
template<class T>
QList< T * > elements () const
QHash< quint32, AbstractElement * > idToElement () const
virtual QDomElement domElement (QDomDocument &doc) const
virtual void initFromDomElement (const QDomElement &e, InitModeFlags modeFlags)
virtual quint32 genElementInstanceId ()

Protected Member Functions

virtual void dispatchEvent (MEvent *)
virtual void changeControllerEvent (MChangeControllerEvent *event)
virtual void elementAddPtrEvent (MElementEvent *)
virtual void elementRemovePtrEvent (MElementEvent *)
virtual void elementSetChangeOrderEvent (MElementSetChangeOrderEvent *)
void elementAddPtr (AbstractElement *element)
void elementRemovePtr (AbstractElement *element)
virtual AbstractElementcreateElement (const QByteArray &key, quint32 instanceId)=0

Detailed Description

The ElementDoc class extends Doc to provide functionality to allow abstract "elements" to be used in a document.

Warning: The controller must be set in order for instances of this class or any of its model class (such as AbstractElement) to send messages back to it.


Constructor & Destructor Documentation

ElementDoc::ElementDoc ( QObject *  parent  ) 

Default constructor.

ElementDoc::ElementDoc ( const QString &  name,
QObject *  parent 
)


Member Function Documentation

ElementDocController * ElementDoc::elementDocController (  )  const

Convenience method.

Returns a cached guarded pointer that has been dynamically cast to ElementDocController* from AbstractController*.

See also AbstractModel::controller().

QList< T * > ElementDoc::elements (  )  const [inline]

Returns the ordered list of elements.

Note: We use a list as the primary means of managing the elements, as to allow for ordering of the elements. This is usually required in diagrams, where the order in which elements are drawn is important.

Note: This intentionally does not return a const ref, as to ensure thread safety. However, Qt's implicit sharing should help to maintain performance.

QList< AbstractElement * > ElementDoc::elements ( int  type  )  const

Returns an un-ordered list of elements of a given type.

This method is very useful for when a set of operations needs to be performed on one exact type of element

Warning: As stated above, unlike elements(), this returns an un-ordered list.

Note: This uses pre-cached data, hence, this method is very cheap.

Note: This intentionally does not return a const ref, as to ensure thread safety. However, Qt's implicit sharing should help to maintain performance.

template<class T>
QList<T*> ElementDoc::elements (  )  const [inline]

QHash< quint32, AbstractElement * > ElementDoc::idToElement (  )  const

Returns a hash of elements, where for each entry, the key is the element instance id and the value is a pointer to the corresponding element object.

Using a hash instead of a list helps us to quickly find an instance of a given element, such as by the XML DOM methods for save/load and copy/paste, etc.

Note: This intentionally does not return a const ref, as to ensure thread safety. However, Qt's implicit sharing should help to maintain performance.

QDomElement ElementDoc::domElement ( QDomDocument &  doc  )  const [virtual]

Creates an XML QDomElement that represents the ElementDoc.

Use initFromDOMElement() to restore the ElementDoc state from the resulting QDomElement.

Reimplemented from Doc.

void ElementDoc::initFromDomElement ( const QDomElement &  e,
InitModeFlags  modeFlags 
) [virtual]

Restore the ElementDoc state from a QDomElement created by domElement().

This will remove any existing elements first if modeFlags has its InitStructure bit set.

Please see DomAccessibleState::initFromDomElement() for more information.

Note: Returns immediately if e.tagName() != key().

Reimplemented from Doc.

quint32 ElementDoc::genElementInstanceId (  )  [virtual]

Generates a unique element instance ID and reserves a place for it.

The IDs will be practically random, which helps generation speed, as it reduces clustering.

Note: Reservation is very important. For example, if there was no reservation and this method were to be called twice in a row without actually inserting a new element immediately after the first call, then this method could return the same ID both times. However, reservation is not persistent, which will prevent code that does not follow through on a reservation from eventually rendering the document incapable of holding new elements.

Note: Even though it is slower, gap-filling is used. This is because elements may be randomly added and deleted, while the IDs remain persistent across save & load (which allows elements to refer to one another). This allows the document to (theoretically) contain up to 4,294,967,296 elements at any given time.

void ElementDoc::dispatchEvent ( MEvent event  )  [protected, virtual]

The model's event dispatcher.

Asserts that the event is non-null.

Warning! It is assumed that the events have their correct type set (as it uses static casts).

Reimplemented from AttributeDoc.

void ElementDoc::changeControllerEvent ( MChangeControllerEvent event  )  [protected, virtual]

Re-implemented, as to also have the pointer returned by elementDocController() updated.

Asserts that the event is non-null.

Reimplemented from AttributeDoc.

Reimplemented in Diagram.

void ElementDoc::elementAddPtrEvent ( MElementEvent event  )  [protected, virtual]

Appends the given event->element() pointer to the front of the document's list of elements().

Asserts that both event and event->element() are non-null.

void ElementDoc::elementRemovePtrEvent ( MElementEvent event  )  [protected, virtual]

Removes the given event->element() pointer from the document's list of elements().

This will not delete the element (as in won't free its memory). All memory de-allocation is to be handled by the document's controller (e.g. ElementDocController). This is so that the controller can remove the pointer from the document (by calling this method) and THEN update the views (which may still refer to element), followed by calling deleteLater() on the element.

Asserts that both event and event->element() are non-null.

void ElementDoc::elementSetChangeOrderEvent ( MElementSetChangeOrderEvent event  )  [protected, virtual]

Changes the (Z) order of the given event->elements() in respect to elements() as specified by the given event->action().

Supported actions are: BringToFront, SendToBack, BringForward, and SendBackward.

Assumes that elements() contains no duplicates. Any duplicates will be removed and only the first occurrence will ever be used.

Asserts that the event is non-null.

void ElementDoc::elementAddPtr ( AbstractElement element  )  [protected]

void ElementDoc::elementRemovePtr ( AbstractElement element  )  [protected]

virtual AbstractElement* ElementDoc::createElement ( const QByteArray &  key,
quint32  instanceId 
) [protected, pure virtual]

Implemented in Diagram.


The documentation for this class was generated from the following files:
Generated on Mon Jul 30 09:46:52 2007 for Digest by  doxygen 1.5.2