Qtilities::CoreGui::TreeNode Class Reference

The TreeNode class is a node in a tree which can have items attached to it and can also be attached to other nodes. More...

#include <TreeNode.h>

Inheritance diagram for Qtilities::CoreGui::TreeNode:

List of all members.

Public Member Functions
ActivityPolicyFilter *	activityPolicyFilter () const
	Function which returns a reference to the activity control filter used by this node, if any.
TreeItem *	addItem (const QString &name, const QtilitiesCategory &category=QtilitiesCategory())
	Creates a new tree item and then add it as a tree item under this node.
bool	addItem (TreeItemBase *item, const QtilitiesCategory &category=QtilitiesCategory())
	Adds a tree item under this node.
void	addItems (const QStringList &items, const QtilitiesCategory &category=QtilitiesCategory())
	Creates new tree items and then add them under this node.
TreeNode *	addNode (const QString &name, const QtilitiesCategory &category=QtilitiesCategory())
	Creates a new tree node and then add it as a tree item under this node.
bool	addNode (TreeNode *node, const QtilitiesCategory &category=QtilitiesCategory())
	Adds a tree mode under this node.
bool	addNodeFromFile (QString file_name, const QtilitiesCategory &category=QtilitiesCategory(), QString *errorMsg=0)
	Adds a tree mode under this from a file.
void	clearChildType ()
	Disables naming control in this node.
void	disableActivityControl ()
	Disables actvity control in this node.
void	disableCategorizedDisplay ()
	Disables categorized display on this node.
void	disableNamingControl ()
	Disables naming control in this node.
ActivityPolicyFilter *	enableActivityControl (ObserverHints::ActivityDisplay activity_display, ObserverHints::ActivityControl activity_control=ObserverHints::NoActivityControlHint, ActivityPolicyFilter::ActivityPolicy activity_policy=ActivityPolicyFilter::MultipleActivity, ActivityPolicyFilter::ParentTrackingPolicy parent_tracking_policy=ActivityPolicyFilter::ParentIgnoreActivity, ActivityPolicyFilter::MinimumActivityPolicy minimum_activity_policy=ActivityPolicyFilter::AllowNoneActive, ActivityPolicyFilter::NewSubjectActivityPolicy new_subject_activity_policy=ActivityPolicyFilter::SetNewInactive, bool monitor_modification_state=true)
	Convenience function to set up activity control on this tree node.
void	enableCategorizedDisplay (ObserverHints::CategoryEditingFlags category_editing_flags=ObserverHints::CategoriesNoEditingFlags)
	Enables categorized display on this node.
NamingPolicyFilter *	enableNamingControl (ObserverHints::NamingControl naming_control, NamingPolicyFilter::UniquenessPolicy uniqueness_policy, NamingPolicyFilter::ResolutionPolicy uniqueness_resolution_policy=NamingPolicyFilter::PromptUser, NamingPolicyFilter::ResolutionPolicy validity_resolution_policy=NamingPolicyFilter::PromptUser)
	Convenience function to set up naming control on this tree node.
void	endProcessingCycle (bool broadcast=true)
void	endTreeProcessingCycle (bool broadcast=true)
IExportable::ExportResultFlags	exportFormattingXML (QDomDocument *doc, QDomElement *object_node, Qtilities::ExportVersion version) const
	Allows exporting of formatting information to a XML document. A reference to the QDomElement to which the object's information must be added is provided, along with a reference to the QDomDocument.
bool	getCategorizedDisplayEnabled () const
	Function indicating if categorized display is used on this tree node.
QObject *	getTreeItemObjectBase ()
IExportable::ExportResultFlags	importFormattingXML (QDomDocument *doc, QDomElement *object_node, Qtilities::ExportVersion version)
	Allows importing of formatting information from a XML document. A reference to the QDomElement which contains the object's information is provided, along with a reference to the QDomDocument.
IExportable::ExportResultFlags	loadFromFile (const QString &file_name, QString *errorMsg=0, bool clear_first=true)
	Loads the tree under this tree node from an XML file.
NamingPolicyFilter *	namingPolicyFilter () const
	Function which returns a reference to the naming control filter used by this node, if any.
bool	removeItem (const QString &name)
	Removes the tree item or tree node specified by name from this tree node.
bool	removeItem (TreeItemBase *item)
	Removes the specified tree item from this node.
bool	removeNode (TreeItemBase *node)
	Creates a new tree node and then add it as a tree item under this node.
IExportable::ExportResultFlags	saveToFile (const QString &file_name, QString *errorMsg=0, ObserverData::ExportItemFlags export_flags=ObserverData::ExportData) const
	Saves the tree under this tree node to an XML file.
bool	setCategory (const QtilitiesCategory &category, TreeNode *tree_node)
	Sets the category of the tree item in the specified tree node.
bool	setCategory (const QtilitiesCategory &category, int observer_id=-1)
	Sets the category of the tree item in the context specified by the given observer ID.
SubjectTypeFilter *	setChildType (const QString &child_group_name)
	Convenience function to set up subject type on this tree node.
void	startProcessingCycle ()
void	startTreeProcessingCycle ()
SubjectTypeFilter *	subjectTypeFilter () const
	Function which returns a reference to the naming control filter used by this node, if any.
Public Member Functions inherited from Qtilities::Core::Observer
AccessMode	accessMode (QtilitiesCategory category=QtilitiesCategory()) const
	Function to get the observer's access mode.
AccessModeScope	accessModeScope () const
	Function to return the access mode scope of the observer.
virtual bool	attachSubject (QObject *obj, Observer::ObjectOwnership ownership=Observer::ManualOwnership, QString *rejectMsg=0, bool import_cycle=false)
	Will attempt to attach the specified object to the observer. The success of this operation depends on the installed subject filters, as well as the dynamic properties defined for the object to be attached.
virtual QList< QPointer < QObject > >	attachSubjects (QList< QObject * > objects, Observer::ObjectOwnership ownership=Observer::ManualOwnership, QString *rejectMsg=0, bool import_cycle=false)
	Will attempt to attach the specified objects to the observer.
virtual QList< QPointer < QObject > >	attachSubjects (ObserverMimeData *mime_data_object, Observer::ObjectOwnership ownership=Observer::ManualOwnership, QString *rejectMsg=0, bool import_cycle=false)
	Will attempt to attach the specified objects in a ObserverMimeData object.
bool	broadcastModificationStateChangesEnabled () const
	Indicates if broadcasting of modification state changes are enabled.
Observer::EvaluationResult	canAttach (QObject *obj, Observer::ObjectOwnership ownership=Observer::ManualOwnership, QString *rejectMsg=0, bool silent=false) const
	A function which checks if the new object can be attached to the observer. This function also validates the attachment operation inside all installed subject filters. Note that this function does not attach it.
Observer::EvaluationResult	canAttach (ObserverMimeData *mime_data_object, QString *rejectMsg=0, bool silent=false) const
	A function which checks if the objects in the ObserverMimeData object can be attached to the observer. This function also validates the attachment operation inside all installed subject filters. Note that this function does not attach it.
Observer::EvaluationResult	canDetach (QObject *obj, QString *rejectMsg=0) const
	A function which checks if the object can be detached from the observer. This function also validates the detachment operation inside all installed subject filters. Note that this function does not detach it.
AccessMode	categoryAccessMode (const QtilitiesCategory &category) const
	Returns the access mode for a specific category.
virtual void	clearExportTask ()
	Clears the export task.
bool	contains (const QObject *object) const
	Returns true if a given subject is currently observed by the observer.
bool	containsSubjectWithName (const QString &subject_name, Qt::CaseSensitivity cs=Qt::CaseSensitive) const
	Returns true if a subject with the specified name is currently observed by the observer.
bool	copyHints (ObserverHints *display_hints)
	Function to let this observer copy a set of display hints.
ObserverHints *	displayHints () const
	Function which returns a pointer to the ObserverHints used by this observer.
bool	eventFilter (QObject *object, QEvent *event)
	Event filter filters property change events on all subjects.
virtual IExportable::ExportResultFlags	exportBinary (QDataStream &stream) const
	Allows exporting to a QDataStream.
virtual IExportable::ExportResultFlags	exportXml (QDomDocument *doc, QDomElement *object_node) const
	Allows exporting to an XML document. A reference to the QDomElement to which the object's information must be added is provided, along with a reference to the QDomDocument.
QVariant	getMultiContextPropertyValue (const QObject *obj, const char *property_name) const
	Convenience function which will get the value of a MultiContextProperty based dynamic property, and not the observer property itself.
bool	hasCategory (const QtilitiesCategory &category) const
	Checks if the specified category exists in this observer context.
bool	hasSubjectFilter (const QString &filter_name) const
	Function to check if a subject filter with the specified name already exists in this context.
virtual IExportable::ExportResultFlags	importBinary (QDataStream &stream, QList< QPointer< QObject > > &import_list)
virtual IExportable::ExportResultFlags	importXml (QDomDocument *doc, QDomElement *object_node, QList< QPointer< QObject > > &import_list)
bool	installSubjectFilter (AbstractSubjectFilter *subject_filter)
	Installs a new subject filter.
InstanceFactoryInfo	instanceFactoryInfo () const
	The instance factory information which must be used when the exported object is reconstructed during an import.
bool	isConst (const QtilitiesCategory &access_mode=QtilitiesCategory()) const
	This function will validate changes to the observer, or to a specific observer category if specified.
bool	isModified () const
	Indicates the modification state of the object.
bool	isProcessingCycleActive () const
	Indicates if a processing cycle is active.
QStringList	monitoredProperties () const
	This function returns a QStringList with the names of all the properties which are monitored by this observer.
bool	monitorSubjectModificationState (QObject *obj)
	Gets if a subject's modification state must be monitored.
QObject *	objectBase ()
	Returns the QObject* base of the interface.
const QObject *	objectBase () const
	Returns a const QObject* base of the interface.
ObjectDeletionPolicy	objectDeletionPolicy () const
	Function to get the observer's object deletion policy.
	Observer (const QString &observer_name=QString(), const QString &observer_description=QString(), QObject *parent=0)
	Default constructor.
	Observer (const Observer &other)
	Copy constructor.
QString	observerDescription () const
	Returns the observer's description. For example, a variable workspace, or a logger engine manager etc.
int	observerID () const
	Returns the uqniue ID assigned to this observer by the ObjectManager.
QString	observerName (int parent_id=-1) const
	Returns the observer's name within a context. If a context is not specified, the objectName() of the observer is returned.
Observer &	operator<< (QObject *subject)
	Overload << operator so that we can attach subjects using the operator.
int	processingCycleCount () const
	Function which returns the number of times processing cycles has been started.
bool	qtilitiesPropertyChangeEventsEnabled () const
	Indicates if QtilitiesPropertyChangeEvents are enabled.
void	refreshViewsData (bool force=false)
	Function to refresh the data views showing this observer.
void	refreshViewsLayout (QList< QPointer< QObject > > new_selection=QList< QPointer< QObject > >(), bool force=false)
	Function to refresh the layout views showing this observer.
QList< QPointer< QObject > >	renameCategory (const QtilitiesCategory &old_category, const QtilitiesCategory &new_category, bool match_exactly=true)
	Renames old_category to new_category in this observer context.
QStringList	reservedProperties () const
	This function returns a QStringList with the names of all the reserved properties inside this observer context.
void	resetProcessingCycleCount (bool broadcast=true)
	Function which resets the processing cycle count on the observer.
void	setAccessMode (AccessMode mode, QtilitiesCategory category=QtilitiesCategory())
	Function to set the observer's access mode. Set the access mode after construction. When subclassing Observer, set it in your constructor.
void	setAccessModeScope (AccessModeScope access_mode_scope)
	Function to set the observer's access mode scope.
virtual void	setApplicationExportVersion (quint32 version)
	Sets the application export version currently used by all your application's classes.
virtual void	setExportTask (ITask *task)
	Sets the task which must be used to log import/export information to.
virtual void	setExportVersion (Qtilities::ExportVersion version)
	Returns the export version currently used by all Qtilities classes.
bool	setMonitorSubjectModificationState (QObject *obj, bool monitor)
	Sets if a subject's modification state must be monitored.
bool	setMultiContextPropertyValue (QObject *obj, const char *property_name, const QVariant &new_value) const
	Convenience function which will set the value of a MultiContextProperty based dynamic property, and not the observer property itself.
void	setObjectDeletionPolicy (ObjectDeletionPolicy object_deletion_policy)
	Function to set the observer's object deletion policy.
void	setObserverDescription (const QString &description)
	Returns the observer's description. For example, a variable workspace, or a logger engine manager etc.
bool	setSubjectLimit (int subject_limit)
	Function to set the subject limit of this observer.
QObject *	subjectAt (int i) const
	Returns the subject reference at a given position.
QList< QtilitiesCategory >	subjectCategories () const
	Returns a QStringList with all the categories found in the qti_prop_CATEGORY_MAP properties of all attached subjects.
QtilitiesCategory	subjectCategoryInContext (const QObject *obj) const
	Returns the category used for the specified object in this context. QtilitiesCategory() is returned if the object is not valid, not attached to this observer or does not have a category.
int	subjectCount (const QString &base_class_name=QString()) const
	Returns the number of subjects currently observed by the observer.
QString	subjectDisplayedNameInContext (const QObject *obj, bool check_displayed_name_property=true, bool validate_object=false) const
	Returns the displayed name used for the specified object in this context. QString() is returned if the object is not valid or not attached to this observer.
QStringList	subjectDisplayedNames (const QString &base_class_name="QObject") const
	Returns a list with the displayed names of all the current observed subjects which inherits a specific base class. By default all subjects' displayed names are returned.
bool	subjectEventFilteringEnabled () const
	Indicates if subject event filtering is enabled.
QList< AbstractSubjectFilter * >	subjectFilters () const
	Provides a list of all installed subject filters.
int	subjectID (int i) const
	Returns the ID of the object at the specified position of the Observer's pointer list, returns -1 if the object was not found.
int	subjectID (const QString &subject_name, Qt::CaseSensitivity cs=Qt::CaseSensitive) const
	Returns the ID associated with a specific subject.
QList< int >	subjectIDs () const
	Returns the IDs for all the attached subjects.
int	subjectLimit () const
	Returns the observer's subject limit.
QMap< QPointer< QObject > , QString >	subjectMap ()
	Return a QMap with references to all subjects as keys with the names used for the subjects in this context as values.
QString	subjectNameInContext (const QObject *obj) const
	Returns the name used for the specified object in this context. QString() is returned if the object is not valid or not attached to this observer.
QStringList	subjectNames (const QString &base_class_name="QObject") const
	Returns a list with the names of all the current observed subjects which inherits a specific base class. By default all subjects' names are returned.
QStringList	subjectNamesByCategory (const QtilitiesCategory &category) const
	Returns a list with the names of all the current observed subjects which belongs to a specific category.
QList< QPointer< Observer > >	subjectObserverReferences () const
	Returns a list of observers under this observer.
ObjectOwnership	subjectOwnershipInContext (const QObject *obj) const
	Returns the ownership used for the specified object in this context.
QObject *	subjectReference (int ID) const
	Gets the subject reference for a specific, unique subject ID.
QObject *	subjectReference (const QString &subject_name, Qt::CaseSensitivity cs=Qt::CaseSensitive) const
	Gets the subject reference for a specific object name.
QMap< QPointer< QObject > , QString >	subjectReferenceCategoryMap () const
	Returns a QMap with each object in this observer mapped to its category's string representation (using toString("::") function on QtilitiesCategory).
QList< QObject * >	subjectReferences (const QString &base_class_name=QString()) const
	Returns a list with the subject references of all the observed subjects which inherits a specific base class. If you don't specify an interface, all QObjects in the observer are returned.
QList< QObject * >	subjectReferencesByCategory (const QtilitiesCategory &category) const
	Returns a list with the subject references of all the observed subjects which has the specified category set as an qti_prop_CATEGORY_MAP shared observer property.
ExportModeFlags	supportedFormats () const
	Provides information about the export format(s) supported by your implementation of IExportable.
void	toggleBroadcastModificationStateChanges (bool toggle)
	This function enables/disables broadcasting of modification state changes Observer.
void	toggleQtilitiesPropertyChangeEvents (bool toggle)
	This function enables/disables delivery of QtilitiesPropertyChangeEvents on objects when property changes occurs.
void	toggleSubjectEventFiltering (bool toggle)
	This function toggles event filtering on objects.
QObject *	treeAt (int i) const
	Function to get a QObject reference at a specific location in the tree underneath this observer.
QList< QObject * >	treeChildren (const QString &base_class_name="QObject", int limit=-1, int iterator_id=-1) const
	Function to get the QObject references of all items in the tree underneath this observer.
bool	treeContains (QObject *tree_item) const
	Function to check if a specific AbstractTreeItem is contained in the tree underneath this node.
int	treeCount (const QString &base_class_name=QString())
	Function to get the number of children under the specified observer.
bool	uninstallSubjectFilter (AbstractSubjectFilter *subject_filter)
	Uninstalls a subject filter.
ObserverHints *	useDisplayHints ()
	Function which constructs hints for this observer.
virtual	~Observer ()
	Observer destructor.
Public Member Functions inherited from Qtilities::Core::Interfaces::IExportable
quint32	applicationExportVersion () const
	Returns the application export version currently used by all your application's classes.
IExportable *	duplicate (QString *error_msg=0, int properties_to_copy=0, ExportResultFlags *result_flags=0) const
	Function which will create a duplicate (copy) of this object.
virtual ITask *	exportTask () const
	Gets the task which must be used to log import/export information to.
Qtilities::ExportVersion	exportVersion () const
	Returns the export version currently used by all Qtilities classes.
bool	isExportable () const
	Gets if this object must be part of it's parents' exports.
virtual void	setIsExportable (bool new_is_exportable)
	Sets if this object must be part of it's parents' exports.
Public Member Functions inherited from Qtilities::Core::Interfaces::IObjectBase
QString	objectOriginID () const
	Allows interfaces to provide some sort of source identification.
void	setObjectOriginID (const QString &object_origin_id)
	Allows setting of the object source ID of this interface implementation.
Public Member Functions inherited from Qtilities::Core::Interfaces::IModificationNotifier
virtual void	setModificationState (bool new_state, NotificationTargets notification_targets=NotifyListeners, bool force_notifications=false)=0
	Sets the modification state of the object. Returns true if it was successfull.
Public Member Functions inherited from Qtilities::CoreGui::AbstractTreeItem
Qt::AlignmentFlag	getAlignment () const
	Gets the alignement of the tree item.
QColor	getBackgroundColor () const
	Gets the background color of the tree item.
QBrush	getBackgroundRole () const
	Gets the background role of the tree item.
virtual QtilitiesCategory	getCategory (TreeNode *tree_node) const
	Gets the category of the tree item in the specified tree node.
virtual QtilitiesCategory	getCategory (int observer_id=-1) const
	Gets the category of the tree item in the context specified by the given observer ID.
virtual QString	getCategoryString (const QString &sep="::", int observer_id=-1) const
	Gets the category in a string format where different hierarchies of the category is split using sep.
QFont	getFont () const
	Gets the font of the tree item.
QColor	getForegroundColor () const
	Gets the foreground color of the tree item.
QBrush	getForegroundRole () const
	Gets the foreground role of the tree item.
QIcon	getIcon () const
	Gets the icon of the tree item.
QString	getName (TreeNode *parent=0) const
	Function to get the name of this tree item.
QSize	getSizeHint () const
	Gets the size hint of the tree item.
QString	getStatusTip () const
	Gets the status tip of the tree item.
QString	getToolTip () const
	Gets the tool tip of the tree item.
QString	getWhatsThis () const
	Gets the what's this text of the tree item.
bool	hasAlignment () const
	Checks if the item has a font.
bool	hasBackgroundRole () const
	Checks if the item has a background role.
virtual bool	hasCategory () const
	Checks if the item has a category.
bool	hasFont () const
	Checks if the item has a font.
bool	hasForegroundRole () const
	Checks if the item has a foreground role.
bool	hasIcon () const
	Checks if the item has an icon.
bool	hasSizeHint () const
	Checks if the item has a size hint.
bool	hasStatusTip () const
	Checks if the item has status tip text.
bool	hasToolTip () const
	Checks if the item has a tool tip.
bool	hasWhatsThis () const
	Checks if the item has what's this text.
virtual bool	removeCategory (int observer_id=-1)
	Removes the current category of this tree item for the specified observer context.
void	setAlignment (const Qt::AlignmentFlag &alignment)
	Sets the alignment of the tree item.
void	setBackgroundColor (const QColor &color)
	Sets the background color of the tree item.
void	setBackgroundRole (const QBrush &background_role)
	Sets the background role of the tree item.
virtual bool	setCategoryString (const QString &category_string, const QString &sep="::")
	Sets the category in a string format where different hierarchies of the category is split using sep.
void	setFont (const QFont &font)
	Sets the font of the tree item.
void	setForegroundColor (const QColor &color)
	Sets the foreground color of the tree item.
void	setForegroundRole (const QBrush &foreground_role)
	Sets the foreground role of the tree item.
void	setIcon (const QIcon &icon)
	Sets the icon of the tree item.
bool	setName (const QString &new_name, Observer *parent=0)
	Function to set the name of this tree item.
void	setSizeHint (const QSize &size)
	Sets the size hint of the tree item.
void	setStatusTip (const QString &status_tip)
	Sets the status tip of the tree item.
void	setToolTip (const QString &tooltip)
	Sets the tool tip of the tree item.
void	setWhatsThis (const QString &whats_this)
	Sets the what's this text of the tree item.

Additional Inherited Members
Public Types inherited from Qtilities::Core::Observer
enum	AccessMode { FullAccess = 0, ReadOnlyAccess = 1, LockedAccess = 2, InvalidAccess = 3 }
	The possible access modes of the observer. More...
enum	AccessModeScope { GlobalScope = 0, CategorizedScope = 1 }
	The access mode scope of the observer. More...
enum	EvaluationResult {   Allowed, Conditional, Rejected, IsParentObserver,   LastScopedObserver }
	This enumeration is used to return results when validating attachment and detachment of subjects. More...
enum	ObjectDeletionPolicy { DeleteImmediately = 0, DeleteLater = 1 }
	The possible deletion methods that Observer can use when deleting objects attached to it. More...
enum	ObjectOwnership {   ManualOwnership, AutoOwnership, SpecificObserverOwnership, ObserverScopeOwnership,   OwnedBySubjectOwnership }
	The possible ownerships with which subjects can be attached to an observer. More...
enum	SubjectChangeIndication { SubjectAdded, SubjectRemoved, CyclicProcess }
	The possible indications that can be returned when the number of subjects in the observer changes. More...
Public Types inherited from Qtilities::Core::Interfaces::IExportable
enum	ExportMode { None = 0, Binary = 1, XML = 2 }
	Possible export modes that an implementation of IExportable can support. More...
enum	Result {   Complete = 0, Incomplete = 1, Failed = 2, FailedContinue = 4,   VersionTooNew = 8, VersionTooOld = 16, VersionSupported = 32, SuccessResult = Complete | Incomplete | VersionSupported,   FailedResult = Failed | FailedContinue | VersionTooNew | VersionTooOld }
	The possible results of an export/import operation. More...
Public Types inherited from Qtilities::Core::Interfaces::IModificationNotifier
enum	NotificationTarget { NotifyNone = 0, NotifyListeners = 1, NotifySubjects = 2 }
	The targets which should be notified when the state of the object implementing this interface changes. More...
Public Slots inherited from Qtilities::Core::Observer
virtual void	deleteAll (const QString &base_class_name="QObject", bool refresh_views=true)
	Function to delete all currenlty observed subjects.
virtual void	detachAll ()
	Function to detach all currently observed subjects.
virtual bool	detachSubject (QObject *obj, QString *rejectMsg=0)
	Will attempt to detach the specified object from the observer.
virtual QList< QPointer < QObject > >	detachSubjects (QList< QObject * > objects, QString *rejectMsg=0)
	Will attempt to detach the specified object objects in the list from the observer.
void	setModificationState (bool new_state, IModificationNotifier::NotificationTargets notification_targets=IModificationNotifier::NotifyListeners, bool force_notifications=false)
Signals inherited from Qtilities::Core::Observer
void	aboutToBeDeleted ()
	This signal is emitted when an observer is about to be deleted, thus its emitted in the beginning of the observer's destructor.
void	allSubjectsAboutToBeDeleted ()
	This signal is emitted just before all subjects are about to be deleted.
void	allSubjectsAboutToBeDetached ()
	This signal is emitted just before all subjects are about to be detached.
void	allSubjectsDeleted ()
	This signal is emitted after all subjects were deleted.
void	allSubjectsDetached ()
	This signal is emitted after all subjects were to be detached.
void	dataChanged (Observer *observer=0)
	A signal which is emitted when the data in the observer or the tree underneath it changes.
void	layoutChanged (QList< QPointer< QObject > > new_selection=QList< QPointer< QObject > >())
	A signal which is emitted when the layout of the observer or the tree underneath it changes.
void	modificationStateChanged (bool is_modified) const
	Implement this function as a signal when implementing the object.
void	monitoredPropertyChanged (const char *property_name, QList< QObject * > objects=QList< QObject * >())
	A signal which is emitted as soon as a monitored property of the observer or any of the installed subject filters changed.
void	numberOfSubjectsChanged (Observer::SubjectChangeIndication change_indication, QList< QPointer< QObject > > objects=QList< QPointer< QObject > >())
	A signal which is emitted when the number of subjects change in this observer context.
void	processingCycleEnded ()
	Signal which is emitted when this observer exists a processing cycle.
void	processingCycleStarted ()
	Signal which is emitted when this observer enters a processing cycle.
void	propertyChangeFiltered (const char *property_name, QList< QObject * > objects=QList< QObject * >())
	A signal which is emitted as soon as an property change event is filtered.
void	subjectDeleted (QObject *obj)
	Will be emitted when a subject is deleted.
Static Public Member Functions inherited from Qtilities::Core::Observer
static QString	accessModeScopeToString (AccessModeScope access_mode_scope)
	Function which returns a string associated with a specific AccessModeScope.
static QString	accessModeToString (AccessMode access_mode)
	Function which returns a string associated with a specific AccessMode.
static bool	isParentInHierarchy (const Observer *obj_to_check, const Observer *observer)
	This function will check if obj_to_check is a parent of observer in the parent hierarchy of observer. Use this function to avoid circular dependencies.
static bool	isSupportedType (const QString &meta_type, Observer *observer)
	Function to check if a meta_type is supported by an observer. Note that an observer must have a subject type filter which knows about the type in order for the function to return true.
static QString	objectDeletionPolicyToString (ObjectDeletionPolicy object_deletion_policy)
	Function which returns a string associated with a specific ObjectDeletionPolicy.
static QString	objectOwnershipToString (ObjectOwnership ownership)
	Function which returns a string associated with a specific ObjectOwnership.
static QList< Observer * >	observerList (QList< QPointer< QObject > > &object_list)
	Function which returns all the observers in a QList<QObject*> input list.
static int	parentCount (const QObject *obj)
	Convenience function to get the number of observers observing the specified object. Thus the number of parents of this object.
static QList< Observer * >	parentReferences (const QObject *obj)
	Convenience function to get the a list of parent observers for this object.
static AccessMode	stringToAccessMode (const QString &access_mode_string)
	Function which returns the AccessMode associated with a string.
static AccessModeScope	stringToAccessModeScope (const QString &access_mode_scope_string)
	Function which returns the AccessModeScope associated with a string.
static ObjectDeletionPolicy	stringToObjectDeletionPolicy (const QString &object_deletion_policy_string)
	Function which returns the ObjectDeletionPolicy associated with a string.
static ObjectOwnership	stringToObjectOwnership (const QString &ownership_string)
	Function which returns the ObjectOwnership associated with a string.
Static Public Member Functions inherited from Qtilities::Core::Interfaces::IExportable
template<typename T >
static T *	duplicateInstance (IExportable *obj, QString *error_msg=0, int properties_to_copy=0, ExportResultFlags *result_flags=0)
	Provides an easy to use template based implementation of IExportable::duplicate().
static QString	exportModeToString (ExportMode export_mode)
	Function which returns a string associated with a specific ExportMode.
static ExportMode	stringToExportMode (const QString &export_mode_string)
	Function which returns the ExportMode associated with a string.
static Result	validateQtilitiesExportVersion (Qtilities::ExportVersion export_version, ITask *task=0)
	Checks the exportVersion() against the supported Qtilities export versions for the current Qtilities version.
static Result	validateQtilitiesImportVersion (Qtilities::ExportVersion import_version, ITask *task=0)
	Checks the exportVersion() against the supported Qtilities import versions for the current Qtilities version.
Protected Member Functions inherited from Qtilities::Core::Observer
void	setFactoryData (InstanceFactoryInfo factory_data)
	Sets the factory data which is necessary to reconstruct this observer.
Protected Member Functions inherited from Qtilities::CoreGui::AbstractTreeItem
IExportable::ExportResultFlags	saveFormattingToXML (QDomDocument *doc, QDomElement *object_node, Qtilities::ExportVersion version) const

---

Detailed Description

The TreeNode class is a node in a tree which can have items attached to it and can also be attached to other nodes.

The TreeNode class represents a node in a tree. That is, it is an item in the tree to which other items or other nodes can be attached/added. The node inherits Observer and therefore provides all the functionality of the Observer class such as installation of subject filters etc.

All items in a TreeNode is attached to the Qtilities::Core::Observer subclass using Qtilities::Core::Observer::ObserverScopeOwnership. Thus when an item appears once in a tree it will be deleted when removed from the TreeNode. However if an item appears multiple times, it will not be deleted when removed from a single TreeNode. This way trees build using TreeNode and TreeItemBase based objects manages the lifetimes of all items in the tree automatically and cleans up after the developer automatically.

Building trees using TreeNode and TreeItem

The advantage of using the TreeNode class over a normal Qtilities::Core::Observer is that it provides convenience functions to easily manipulate the tree. For example, new tree items or nodes can be added to the tree simply by providing the name of the item to be created. Lets look at an example:

// Create the tree nodes:
TreeNode* nodeA = new TreeNode("Node A");
TreeNode* nodeB = nodeA->addNode("Node B");
TreeNode* nodeC = nodeA->addNode("Node C");

// Create the tree items:
nodeA->addItem("Item 1");
nodeB->addItem("Item 2");
nodeB->addItem("Item 3");
nodeB->addItem("Item 4");
nodeC->addItem("Item 5");
nodeC->addItem("Item 6");
nodeC->addItem("Item 7");

// Create an observer widget showing the tree:
TreeWidget* tree_widget = new TreeWidget(nodeA);
tree_widget->show();

The above example will show the following widget:

Simple Tree Example

Formatting items in the tree

The second advantage is that TreeNode inherits AbstractTreeItem, thus we can easily provide role hints for the node, in the same whay that we can add role hints for TreeItem instances. Because the TreeNode class is intended to build trees very quickly mostly for display purposes, it automatically calls Observer::useDisplayHints() in the constructor.

Lets look at an example where we set some hints on the items in the tree. The example above can be modified to look like this:

// Create the tree nodes:
TreeNode* nodeA = new TreeNode("Node A");
TreeNode* nodeB = nodeA->addNode("Node B");
TreeNode* nodeC = nodeA->addNode("Node C");
nodeC->displayHints()->setHierarchicalDisplayHint(ObserverHints::CategorizedHierarchy);

// Add some formatting to the nodes:
nodeA->setForegroundRole(QBrush(Qt::darkRed));
nodeA->setFont(QFont("Helvetica [Cronyx]",20));
nodeA->setAlignment(Qt::AlignCenter);
nodeA->setBackgroundRole(QBrush(Qt::gray));
nodeB->setForegroundRole(QBrush(Qt::darkGreen));
nodeB->setFont(QFont("Helvetica [Cronyx]",20));
nodeB->setAlignment(Qt::AlignCenter);
nodeB->setBackgroundRole(QBrush(Qt::gray));
nodeC->setForegroundRole(QBrush(Qt::darkYellow));
nodeC->setFont(QFont("Helvetica [Cronyx]",20));
nodeC->setAlignment(Qt::AlignCenter);
nodeC->setBackgroundRole(QBrush(Qt::gray));

// Create the tree items:
// Be carefull to use it like this. If the addItem() call fails it returns 0.
nodeA->addItem("Item 1")->setStatusTip("Hello, I'm a status tip.");
nodeB->addItem("Item 2")->setIcon(QIcon(qti_icon_EDIT_COPY_16x16));
nodeB->addItem("Item 3")->setIcon(QIcon(qti_icon_EDIT_CLEAR_16x16));
nodeB->addItem("Item 4")->setIcon(QIcon(qti_icon_EDIT_CUT_16x16));
nodeC->addItem("Item 5")->setWhatsThis("Hello, I'm a What's This message.");
nodeC->addItem("Item 6")->setToolTip("Hello, I'm a ToolTip text");
nodeC->addItem("Item 7")->setCategory(QtilitiesCategory("Category 1"),nodeC);

// Create an observer widget showing the tree:
TreeWidget* tree_widget = new TreeWidget;
QtilitiesApplication::setMainWindow(tree_widget);
tree_widget->setObserverContext(nodeA);
tree_widget->initialize();
tree_widget->show();

The above example will show a formatted tree as shown below:

Simple Tree Example With Formatting

Other features.

The TreeNode class provides the enableNamingControl() and enableActivityControl() functions which allows control over names and activity without having to create, set up and install subject filters manually. Even if you did not call enableNamingControl() or enableActivityControl() and you installed such filters manually on the Observer base class, you can access these filters using namingPolicyFilter() or activityPolicyFilter().

To get the number of tree items in the complete tree under this node, use treeCount(). The treeChildren() function returns a list of all the tree items under this node and we can look for a specific child using treeContains() function. A specific child can be accessed from the treeChildren() list using treeAt().

It is possible to iterate through the items in a tree using Qtilities::Core::TreeIterator.

This class was added in Qtilities v0.2.

---

Member Function Documentation

Qtilities::CoreGui::TreeItem * Qtilities::CoreGui::TreeNode::addItem	(	const QString &	name,
		const QtilitiesCategory &	category = QtilitiesCategory()
	)

Creates a new tree item and then add it as a tree item under this node.

Parameters:

name	The name of the item.
category	The category of the item. By default QtilitiesCategory(), thus it does not specify a category.

Returns:

The reference to the TreeItem created.

Note:

This tree node will manage the lifetime of the item and this node can be obtained through the normal QObject parent() function.

bool Qtilities::CoreGui::TreeNode::addItem	(	TreeItemBase *	item,
		const QtilitiesCategory &	category = QtilitiesCategory()
	)

Adds a tree item under this node.

Parameters:

item	The reference to the item to be added to this tree.
category	The category of the item. By default QtilitiesCategory(), thus it does not specify a category.

Returns:

True if the item was attached successfully, false otherwise.

Note:

This tree node will manage the lifetime of the tree item.

void Qtilities::CoreGui::TreeNode::addItems	(	const QStringList &	items,
		const QtilitiesCategory &	category = QtilitiesCategory()
	)

Creates new tree items and then add them under this node.

Parameters:

names	The names of the items to add.
category	The category of the items. By default QtilitiesCategory(), thus it does not specify a category.

Note:

This tree node will manage the lifetime of the items and this node can be obtained through the normal QObject parent() function.

Qtilities::CoreGui::TreeNode * Qtilities::CoreGui::TreeNode::addNode	(	const QString &	name,
		const QtilitiesCategory &	category = QtilitiesCategory()
	)

Creates a new tree node and then add it as a tree item under this node.

Parameters:

name	The name of the node.
category	The category of the item. By default QtilitiesCategory(), thus it does not specify a category.

Returns:

The reference to the TreeNode created.

Note:

This tree node will manage the lifetime of the item and this node can be obtained through the normal QObject parent() function.

bool Qtilities::CoreGui::TreeNode::addNode	(	TreeNode *	node,
		const QtilitiesCategory &	category = QtilitiesCategory()
	)

Adds a tree mode under this node.

Parameters:

node	The reference to the node to be added to this tree.
category	The category of the item. By default QtilitiesCategory(), thus it does not specify a category.

Returns:

True if the node was attached successfully, false otherwise.

Note:

This tree node will manage the lifetime of the tree item.

bool Qtilities::CoreGui::TreeNode::addNodeFromFile	(	QString	file_name,
		const QtilitiesCategory &	category = QtilitiesCategory(),
		QString *	errorMsg = 0
	)

Adds a tree mode under this from a file.

Parameters:

file_name	The file name to be parsed.
category	The category of the item. By default QtilitiesCategory(), thus it does not specify a category.
errorMessage	If this function returns false the reason why it failed is available through this parameter if a valid QString reference is provided.

Returns:

True if the node was attached successfully, false otherwise.

Note:

This tree node will manage the lifetime of the node item.

void Qtilities::CoreGui::TreeNode::disableCategorizedDisplay

(

)

Disables categorized display on this node.

See also:

getCategorizedDisplayEnabled(), enableCategorizedDisplay();

Qtilities::Core::ActivityPolicyFilter * Qtilities::CoreGui::TreeNode::enableActivityControl	(	ObserverHints::ActivityDisplay	activity_display,
		ObserverHints::ActivityControl	activity_control = ObserverHints::NoActivityControlHint,
		ActivityPolicyFilter::ActivityPolicy	activity_policy = ActivityPolicyFilter::MultipleActivity,
		ActivityPolicyFilter::ParentTrackingPolicy	parent_tracking_policy = ActivityPolicyFilter::ParentIgnoreActivity,
		ActivityPolicyFilter::MinimumActivityPolicy	minimum_activity_policy = ActivityPolicyFilter::AllowNoneActive,
		ActivityPolicyFilter::NewSubjectActivityPolicy	new_subject_activity_policy = ActivityPolicyFilter::SetNewInactive,
		bool	monitor_modification_state = true
	)

Convenience function to set up activity control on this tree node.

This function will create a Qtilities::Core::ActivityPolicyFilter with the specified parameters and install it on the tree node. It will also set the correct parameters on the Observer base class's observer hints.

This function must be called only once, after the construction of your tree node before any tree items have been attached to the node. Calling it a second time will just return the already constructed filter.

Parameters:

activity_display	The ObserverHints::ActivityDisplay hint to use in this tree node.
activity_control	The ObserverHints::ActivityControl hint to use in this tree node.
activity_policy	The ActivityPolicyFilter::ActivityPolicy hint to use in this tree node.
parent_tracking_policy	The ActivityPolicyFilter::ParentTrackingPolicy hint to use in this tree node.
minimum_activity_policy	The ActivityPolicyFilter::MinimumActivityPolicy hint to use in this tree node.
new_subject_activity_policy	The ActivityPolicyFilter::NewSubjectActivityPolicy hint to use in this tree node.
monitor_modification_state	When true the modification state of the activity filter will be monitored by the node. Thus if the active subjects changes the TreeNode will indicate that it changed.

Returns:

The activity policy filter used in this node. If the filter could not be constructed, null is returned.

void Qtilities::CoreGui::TreeNode::enableCategorizedDisplay

(

ObserverHints::CategoryEditingFlags

category_editing_flags = ObserverHints::CategoriesNoEditingFlags

)

Enables categorized display on this node.

This is a convenience function which sets the Qtilities::Core::ObserverHints::CategorizedHierarchy hint on this node's observer base class.

Parameters:

category_editing_flags

The Qtilities::Core::ObserverHints::CategoryEditingFlags that must be used on category nodes. By default ObserverHints::CategoriesNoEditingFlags which will respect the current editing flags set on the displayHints() of the tree node.

Note:

This function does not refresh the view and it sets the modification state of the node to modified.

See also:

getCategorizedDisplayEnabled(), disableCategorizedDisplay()

Qtilities::CoreGui::NamingPolicyFilter * Qtilities::CoreGui::TreeNode::enableNamingControl	(	ObserverHints::NamingControl	naming_control,
		NamingPolicyFilter::UniquenessPolicy	uniqueness_policy,
		NamingPolicyFilter::ResolutionPolicy	uniqueness_resolution_policy = NamingPolicyFilter::PromptUser,
		NamingPolicyFilter::ResolutionPolicy	validity_resolution_policy = NamingPolicyFilter::PromptUser
	)

Convenience function to set up naming control on this tree node.

This function will create a Qtilities::CoreGui::NamingPolicyFilter with the specified parameters and install it on the tree node. It will also set the correct parameters on the Observer base class's observer hints.

This function must be called only once, after the construction of your tree node before any tree items have been attached to the node. Calling it a second time will just return the already constructed filter.

Parameters:

naming_control	The ObserverHints::NamingControl hint to use in this tree node.
uniqueness_policy	The NamingPolicyFilter::UniquenessPolicy to use in this tree node.
uniqueness_resolution_policy	The NamingPolicyFilter::ResolutionPolicy to use in for duplicate items under this tree node.
validity_resolution_policy	The NamingPolicyFilter::ResolutionPolicy to use in for invalid items under this tree node.

Returns:

The naming policy filter used in this node. If the filter could not be constructed, null is returned.

void Qtilities::CoreGui::TreeNode::endProcessingCycle ( bool  broadcast = true )

virtual

This overloaded function will also end a naming validation cycle on the naming policy filter if this node has one.

Reimplemented from Qtilities::Core::Observer.

void Qtilities::CoreGui::TreeNode::endTreeProcessingCycle ( bool  broadcast = true )

virtual

This overloaded function will also end a naming validation cycle on the naming policy filter for tree nodes which has ones.

Reimplemented from Qtilities::Core::Observer.

bool Qtilities::CoreGui::TreeNode::getCategorizedDisplayEnabled

(

)

const

Function indicating if categorized display is used on this tree node.

See also:

enableCategorizedDisplay();, enableCategorizedDisplay();

QObject* Qtilities::CoreGui::TreeNode::getTreeItemObjectBase ( )

inlinevirtual

Parameters:

file_name	The file name from to which the file must be saved.
errorMessage	If this function returns IExportable::Failed the reason why it failed is available through this parameter if a valid QString reference is provided.

Returns:

Result of the operation.

See also:

loadFromString()

Parameters:

file_name	The file name from which the tree must be loaded.
clear_first	When true, all items under this tree is deleted first. When false, the items in the input file will be added to the current set of items under this tree node.
errorMessage	If this function returns IExportable::Failed the reason why it failed is available through this parameter if a valid QString reference is provided.

Returns:

Result of the operation.

See also:

saveToString()

Implements Qtilities::CoreGui::AbstractTreeItem.

Qtilities::Core::Interfaces::IExportable::ExportResultFlags Qtilities::CoreGui::TreeNode::loadFromFile	(	const QString &	file_name,
		QString *	errorMsg = 0,
		bool	clear_first = true
	)

Loads the tree under this tree node from an XML file.

Parameters:

file_name	The file name from which the tree must be loaded.
clear_first	When true, all items under this tree is deleted first. When false, the items in the input file will be added to the current set of items under this tree node.
errorMessage	If this function returns IExportable::Failed the reason why it failed is available through this parameter if a valid QString reference is provided.

Returns:

Result of the operation.

See also:

saveToFile()

bool Qtilities::CoreGui::TreeNode::removeItem

(

const QString &

name

)

Removes the tree item or tree node specified by name from this tree node.

Parameters:

item	The name of the tree item or tree node to be removed.

Returns:

True if the item was removed successfully, false otherwise.

Note:

Only use the name of the item directly if you are sure that items in your tree node has unique names. This can be enforced by installing a NamingPolicyFilter on the tree node. If you use this function on a TreeNode which does have multiple items with the same name, the first item found with the specified name will be removed.

bool Qtilities::CoreGui::TreeNode::removeItem

(

TreeItemBase *

item

)

Removes the specified tree item from this node.

Parameters:

item	The reference to the item to be removed from this tree.

Returns:

True if the item was removed successfully, false otherwise.

bool Qtilities::CoreGui::TreeNode::removeNode

(

TreeItemBase *

node

)

Creates a new tree node and then add it as a tree item under this node.

Parameters:

item	The reference to the node to be removed from this tree.

Returns:

True if the node was removed successfully, false otherwise.

Qtilities::Core::Interfaces::IExportable::ExportResultFlags Qtilities::CoreGui::TreeNode::saveToFile	(	const QString &	file_name,
		QString *	errorMsg = 0,
		ObserverData::ExportItemFlags	export_flags = ObserverData::ExportData
	)		const

Saves the tree under this tree node to an XML file.

Parameters:

file_name	The file name from to which the file must be saved.
errorMessage	If this function returns IExportable::Failed the reason why it failed is available through this parameter if a valid QString reference is provided.

Returns:

Result of the operation.

See also:

loadFromFile()

bool Qtilities::CoreGui::TreeNode::setCategory ( const QtilitiesCategory &  category, TreeNode *  tree_node  )

virtual

Sets the category of the tree item in the specified tree node.

Returns:

True if the category was successfully set. False otherwise. Note that false will be returned when the category is the same as the current category and therefore will not be changed.

Reimplemented from Qtilities::CoreGui::AbstractTreeItem.

bool Qtilities::CoreGui::TreeNode::setCategory ( const QtilitiesCategory &  category, int  observer_id = -1  )

virtual

Sets the category of the tree item in the context specified by the given observer ID.

Parameters:

observer_id

The observer ID of the context for which the category must be obtained for. When -1, the function will find the parent in the following way: It will check if the item has only one parent. If that is the case, the category in this parent will be used. that the item only has 1 parent and it will check if it has only one parent and if so, return the category for that parent. If the item has more than one parent, the function will check if the item has a specific parent (thus it was attached using Observer::SpecificObserverOwnership). If it does have a specific parent, the category in this parent will be used.

If none of the above conditions were met the function will print an error message in release mode and assert in debug mode.

Returns:

True if the category was successfully set. False otherwise. Note that true will be returned when the category is the same as the current category and therefore will not be changed.

Note:

If this tree item is not attached to any tree node, this function does nothing and returns false.

See also:

removeCategory(), getCategory()

Reimplemented from Qtilities::CoreGui::AbstractTreeItem.

Qtilities::Core::SubjectTypeFilter * Qtilities::CoreGui::TreeNode::setChildType

(

const QString &

child_group_name

)

Convenience function to set up subject type on this tree node.

This function will create a Qtilities::Core::SubjectTypeFilter with the specified parameters and install it on the tree node. It is usefull to use when you want to give a name for items under a context. Observer widgets use this name in it's header for the name column.

This function must be called only once, after the construction of your tree node before any tree items have been attached to the node. Calling it a second time will just return the already constructed filter.

Note:

This function will enable inversed filtering on the subject type filter.

void Qtilities::CoreGui::TreeNode::startProcessingCycle ( )

virtual

This overloaded function will also start a naming validation cycle on the naming policy filter if this node has one.

Reimplemented from Qtilities::Core::Observer.

void Qtilities::CoreGui::TreeNode::startTreeProcessingCycle ( )

virtual

This overloaded function will also start a naming validation cycle on the naming policy filter for tree nodes which has ones.

Reimplemented from Qtilities::Core::Observer.