The observer class is an extended implementation of an observer in the subject-observer pattern. More...

#include <Observer.h>

Inheritance diagram for Qtilities::Core::Observer:

[legend]

Public Types
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
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
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.

Public Member Functions
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.
virtual void	endProcessingCycle (bool broadcast=true)
	Ends a processing cycle.
virtual void	endTreeProcessingCycle (bool broadcast=true)
	Starts a processing cycle.
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.
virtual void	startProcessingCycle ()
	Starts a processing cycle.
virtual void	startTreeProcessingCycle ()
	Starts a processing cycle.
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.

Static Public Member Functions
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
void	setFactoryData (InstanceFactoryInfo factory_data)
	Sets the factory data which is necessary to reconstruct this observer.

Detailed Description

The observer class is an extended implementation of an observer in the subject-observer pattern.

The observer class provides a powerful implementation of the subject - observer programming pattern. The observer class is the observer in this implementation (as the name suggests) and any QObject based class can be a subject. One way to think about an observer is to think of it as a context in your application to which certain subjects can be attached or detached. An example of such a context is the observer which manages plugins in the Qtilities extension system. When plugins are loaded they are attached to this context and become visible in the list of loaded plugins. Another example would be different instances of a scripting engine. When new objects are created inside the scripting engine they exist in that context. It can then for example be possible to have multiple scripting engines within the same application, where different objects belongs to different script engines or are shared between the engines using Observers.

The example below shows how to create your first observer class and attach objects to it.

// Create the observer:
Observer* observerA = new Observer;
// Create the objects:
QPointer<QObject> object1 = new QObject();
QPointer<QObject> object2 = new QObject();
// Attach objects to observers:
observerA->attachSubject(object1);
observerA->attachSubject(object2);

Displaying the context of an Observer

One of the original goals of the observer implementation was to make it easy, in fact very easy to display the contents of any Observer context. For this purpose the Qtilities::CoreGui::ObserverWidget class was created which allows you to display the contents of an observer context using only a couple lines of code.

For example:

// Create the observer:
Observer* observerA = new Observer;
// Create the objects:
QPointer<QObject> object1 = new QObject();
QPointer<QObject> object2 = new QObject();
// Attach objects to observers:
observerA->attachSubject(object1);
observerA->attachSubject(object2);
// Display the observer context:
ObserverWidget observerWidget(observerA);
observerWidget.show();

Observer widgets are very powerful and observers can specify display hints to views that display their contents using the Qtilities::Core::ObserverHints class. This interaction is a topic on its own and the Observer Widgets page discusses this in detail. Observer widgets supports both Table and Tree views and the Qtilities::CoreGui::TreeNode class is a subclass of observer that makes building of trees using observer easier. The next section describes such trees in more detail.

Observer Trees

Since an observer is able to manage any QObject based class, it is also capable of observing other observers. This feature allows us to build complex hierarchical tree data structures very easily with the only requirements that leaf nodes in our trees must inherit QObject. Using observer widgets you can easily display and tree data structure that you have created and you can even make dot graphs of your tree structures using ObserverDotWriter.

Lets look at a simple observer tree structure and the functions provided by observer:

Observer Trees

In the above tree Root, A and B are all observers with 1-4 being any QObject based classes. On the Root observer it is possible to access its subjects using functions on observer that start with subject. For example: subjectCount(), subjectLimit(), subjectAt() etc. Thus these functions allow you to access the objects directly underneath an observer. On the other hand, function starting with tree allow you to operate on the complete tree underneath an observer. For example: treeCount(), treeAt() etc.

Qtilities provides the SubjectIterator and TreeIterator iterators which allows you to iterate over different parts of the tree structure underneath an observer.

A common request by Qt developers is the ability to easily create and display data based on arbitrary tree structures to users, and to easily interact with users through these trees. It is of course doable using Qt's QAbstractItemModel but its not a trivial tasks and can take time to get right. Qtilities attempts to provide an easy solution to this request in the form of ready to use classes which allows you to build trees easily. The Building Trees page provides a detailed overview of this solution.

Subject filters

Subject filters are a feature of the observer architecture which allows control over object attachment and detachment, as well as monitoring of properties introduced by the subject filter. For more information on this see the Subject filters section of the Observers page.

Observers and threads

Since observers manage objects which can live in different threads it is important to take care when using observers outside of the GUI thread. The following considerations must be taken into account when using observers in threads outside of the GUI thread and attaching objects to observers that live in different threads:

Observers monitor QDynamicPropertyChange events on objects that it manages, and send QtilitiesPropertyChangeEvent events on specific internal Qtilities properties to objects that it manages. Since properties cannot be posted to objects living in other threads, and events cannot be filtered on objects in a different thread, this functionality of observers cannot be used when using threads as specified above. Event filtering is enabled by default, thus if you intend to use observers which manage objects in different threads, disable this using toggleSubjectEventFiltering().
When using observer's with naming policy filters installed outside of the GUI thread, make sure you don't use the Qtilities::CoreGui::NamingPolicyFilter::PromptUser resolution policy since it will attempt to construct a QWidget under specific circumstances and you application will crash.

Observer by itself is not thread-safe.

Under The Hood: How observers work behind the scenes.

From a user perspective the observer API attempts to hide the complexities of how object management is done. Behind the scenes there is a lot that is happening and lots of complex features that allows you to customize the way you use observers. The Observers article is a good place to start exploring these details.

Member Enumeration Documentation

enum Qtilities::Core::Observer::AccessMode

The possible access modes of the observer.

See also:: setAccessMode(), accessMode()

Enumerator:

FullAccess	All observer operations are available to the user (Attachment, Detachment etc.).
ReadOnlyAccess	The observer is read only to the user.
LockedAccess	The observer is read only and locked. Item views presenting this observer to the user will respect the LockedAccess mode and will not display the contents of the observer to the user.
InvalidAccess	An invalid access mode. This access mode is returned in functions where the access mode is requested for a category that does not exist, for example categoryAccessMode().

enum Qtilities::Core::Observer::AccessModeScope

The access mode scope of the observer.

When using categories in an observer, access modes can be set for each individual category. Categories which does not have access modes set will use the global access mode.

See also:: setAccessMode(), setAccessModeScope(), accessModeScope()

Enumerator:

GlobalScope	The global access mode is used for all categories when categories are used.
CategorizedScope	Access modes are category specific.

enum Qtilities::Core::Observer::EvaluationResult

This enumeration is used to return results when validating attachment and detachment of subjects.

See also:: canAttach(), canDetach()

Enumerator:

Allowed	Indicates that the attachment/detachment operation will be valid.
Conditional	Indicates that the attachment/detachment operation's validity will be dependent on the user input. An example of this is when the object's name is not valid in the context and the naming policy filter is set to prompt the user for the action to take (Reject, Rename etc.).
Rejected	Indicates that the attachment/detachment operation will be invalid.
IsParentObserver	Only used during detachment. Indicates that the observer is the parent of the object. This result takes priority over the other possible results. The use case is where the Object Manager attempts to move objects between observers. When attempting to move objects between two observers it will not move subjects which returns this during their detachment validation.
LastScopedObserver	Only used during detachment. Indicates that the observer is the last scoped parent of the object. This result takes priority over the other possible results except IsParentObserver. The use case is where the Object Manager attempts to move objects between observers. When attempting to move objects between two observers it will not move subjects which returns this during their detachment validation.

enum Qtilities::Core::Observer::ObjectDeletionPolicy

The possible deletion methods that Observer can use when deleting objects attached to it.

By default DeleteLater is used, thus it is safe when deleting objects living in threads other than the observer itself. One drawback of using DeleteLater is that the ObserverWidgets viewing your Observer will only be updated when your object is actually deleted. This can cause your views to take a while to be updated. If you are sure that your objects live in the same thread as the observer you should use DeleteImmediately to avoid this behaviour.

See also:: setObjectDeletionPolicy(), objectDeletionPolicy()

Enumerator:

DeleteImmediately	When subjects are deleted by this observer, the normal `delete` operator is used.
DeleteLater	When subjects are deleted by this observer, deleteLater() are called on them.

enum Qtilities::Core::Observer::ObjectOwnership

The possible ownerships with which subjects can be attached to an observer.

See the Object lifetimes: Managing object lifetimes using observers section of the Observers article for a detailed discussion.

Enumerator:

ManualOwnership	Manual ownership means that the object won't be managed by the observer, thus the ownership will be managed the normal Qt way. If `parent()` = 0, it will not be managed, if `parent()` is an QObject, the subject will be deleted when its parent is deleted. // Create the observer Observer* observerA = new Observer("Observer A","My first observer"); // Create the objects QPointer<QObject> object1 = new QObject(); object1->setObjectName("Object 1"); QPointer<QObject> object2 = new QObject(); object2->setObjectName("Object 2"); // Attach objects to observers observerA->attachSubject(object1,Observer::ManualOwnership); observerA->attachSubject(object2,Observer::ManualOwnership); // Now delete observers delete observerA; // Check the validity of the objects if (object1) { // We get here in this example. } else { } if (object2) { // We get here in this example. } else { } After deleting the two observers in the example above, `object1` and `object2` will still be valid, thus they will not be deleted. Note that subjects are attached to observers using manual ownership by default.
AutoOwnership	Auto ownership means that the observer will automatically decide how to manage the subject. The observer checks if the object already has a parent(), if so `ManualOwnership` is used. If no `parent()` is specified yet, the observer will attach the subject using `ObserverScopeOwnership`. // Create the observer Observer* observerA = new Observer("Observer A","My first observer"); // Create the objects QPointer<QObject> object1 = new QObject(); object1->setObjectName("Object 1"); QPointer<QObject> object2 = new QObject(); object2->setObjectName("Object 2"); QPointer<QObject> parentObject = new QObject(); object2->setParent(parentObject); // Attach objects to observers observerA->attachSubject(object1,Observer::AutoOwnership); observerA->attachSubject(object2,Observer::AutoOwnership); // Now delete observers delete observerA; // Check the validity of the objects if (object1) { } else { // We get here in this example. } if (object2) { // We get here in this example. } else { } Since `object2` has a parent, it will be attached using `ManualOwnership` and `ObserverScopeOwnership` will be used for `object1`. Therefore after deleting the observers, `object1` will be null (see observer_scope_ownership) and `object2` will still be valid.
SpecificObserverOwnership	The observer becomes the parent of the subject (by calling setParent() on the object). That is, when the observer is deleted, the subject is also deleted. // Create the observer Observer* observerA = new Observer("Observer A","My first observer"); // Create the objects QPointer<QObject> object1 = new QObject(); object1->setObjectName("Object 1"); QPointer<QObject> object2 = new QObject(); object2->setObjectName("Object 2"); // Attach objects to observers observerA->attachSubject(object1,Observer::SpecificObserverOwnership); observerA->attachSubject(object2,Observer::SpecificObserverOwnership); // Now delete observer delete observerA; // Check the validity of the objects if (object1) { } else { // We get here in this example. } if (object2) { } else { // We get here in this example. } Both objects will become null after the observers are deleted since `observerA` becomes the specific parent of both objects. Note: QWidget's parent must be another QWidget, thus these rules don't apply to QWidgets.
ObserverScopeOwnership	The object must have at least one Observer parent at any time. That is, when the object is attached to multiple observers, it will stay valid until it goes out of scope. This can happen because all its observer parents gets deleted, or it is detached from all contexts. // Create the observer Observer* observerA = new Observer("Observer A","My first observer"); Observer* observerB = new Observer("Observer B","My second observer"); // Create the objects QPointer<QObject> object1 = new QObject(); object1->setObjectName("Object 1"); QPointer<QObject> object2 = new QObject(); object2->setObjectName("Object 2"); // Attach objects to observers observerA->attachSubject(object1,Observer::ObserverScopeOwnership); observerA->attachSubject(object2,Observer::ObserverScopeOwnership); observerB->attachSubject(object1,Observer::ObserverScopeOwnership); observerB->attachSubject(object2,Observer::ObserverScopeOwnership); // Now delete observer A delete observerA; // Check the validity of the objects if (object1) { // We get here in this example. } else { } if (object2) { // We get here in this example. } else { } // Now delete observer B delete observerB; // Check the validity of the objects if (object1) { } else { // We get here in this example. } if (object2) { } else { // We get here in this example. } Both objects will still be valid after deleting `observerA` since it they are still visible in the scope of `observerB`. After `observerB` is deleted both objects will be null. Note: QWidget's parent must be another QWidget, thus these rules don't apply to QWidgets.
OwnedBySubjectOwnership	The observer is dependent on the subject, thus the subject effectively owns the observer. When the subject is deleted, the observer is also deleted. When the observer is deleted it checks if the subject is attached to any other observers and if not it deletes the subject as well. If the subject is attached to any other observers, the subject is not deleted. When the current ownership of a subject is `OwnedBySubjectOwnership` and it is attached to more contexts, the new ownership is ignored during attachment to the new contexts. Thus when a subject was attached to a context using `OwnedBySubjectOwnership` it is attached to all other contexts after that using `OwnedBySubjectOwnership` as well. On the other hand, when a subject is already attached to one or more observer contexts and it is attached to a new observer using `OwnedBySubjectOwnership`, the old ownership is kept and the observer only connects the destroyed() signal on the object to its own deleteLater() signal. // Create the observer QPointer<Observer> observerA = new Observer("Observer A","My first observer"); // Create the objects QPointer<QObject> object1 = new QObject(); object1->setObjectName("Object 1"); // Attach objects to observers observerA->attachSubject(object1,Observer::OwnedBySubjectOwnership); // Now delete the object delete object1; // Check the validity of the observer if (observerA) { } else { // We get here in this example. } In this example `observerA` will be deleted as soon as `object1` is deleted. Note: QWidget's parent must be another QWidget, thus these rules don't apply to QWidgets.

enum Qtilities::Core::Observer::SubjectChangeIndication

The possible indications that can be returned when the number of subjects in the observer changes.

See also:: numberOfSubjectsChanged()

Enumerator:

SubjectAdded

Indicates that subjects were added.

SubjectRemoved

Indicates that subjects were removed.

CyclicProcess

Indicates that the number of subjects changed during a cyclic process. The subject count can either be less or more than before the cyclic operation.

See also:: startProcessingCycle(), endProcessingCycle()

Constructor & Destructor Documentation

Qtilities::Core::Observer::~Observer ( )

virtual

Observer destructor.

The destructor will delete necesarry objects, thus it will check the ownership of each subject and delete it when it has SpecificObserverOwnership set to this Observer, or when it has ObserverScopeOwnership and this is the last observer that it is attached to. Note that the deletion method used depends on the objectDeletionPolicy() of this observer.

Member Function Documentation

Qtilities::Core::Observer::AccessMode Qtilities::Core::Observer::accessMode ( QtilitiesCategory category = QtilitiesCategory() ) const

Function to get the observer's access mode.

Returns:: The global access mode when category an empty category is used for category. Otherwise the access mode for a specific category. The global access mode is FullAccess by default. When an invalid category (does not exist in this context) is sent Observer::InvalidAccess is returned and an error message is printed.

AccessModeScope Qtilities::Core::Observer::accessModeScope ( ) const

inline

Function to return the access mode scope of the observer.

Returns:: The access mode scope. Global by default.

bool Qtilities::Core::Observer::attachSubject	(	QObject *	obj,
		Observer::ObjectOwnership	ownership = `Observer::ManualOwnership`,
		QString *	rejectMsg = `0`,
		bool	import_cycle = `false`
	)

virtual

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.

When Successful obj will be part of this observer context until it is detached again or deleted.

Parameters:

obj	The object to be attached.
ownership	The ownership that the observer should use to manage the object. The default is Observer::ManualOwnership.
rejectMsg	When this function fails and rejectMsg will be populated with an rejection message when valid.
import_cycle	Indicates if the attachment call was made during an observer import cycle. In such cases the subject filter must not add exportable properties to the object since these properties will be added from the import source. Also, it is not necessary to validate the context in such cases. False by default.

Returns:: True is succesful, false otherwise.

Note:: When subjectEventFilteringEnabled() is true, the observer will be installed as an event filter on obj. If you do not want this to happen you can turn it off using toggleSubjectEventFiltering(). See the toggleSubjectEventFiltering() function documentation for more information on this.; When obj lives in a different thread than this observer an attempt won't be made to install this observer as an event filter.; When obj->objectName() is empty, this function will set the object name to the className() of the object.

See also:: attachSubjects(), startProcessingCycle(), endProcessingCycle()

QList< QPointer< QObject > > Qtilities::Core::Observer::attachSubjects	(	QList< QObject * >	objects,
		Observer::ObjectOwnership	ownership = `Observer::ManualOwnership`,
		QString *	rejectMsg = `0`,
		bool	import_cycle = `false`
	)

virtual

Will attempt to attach the specified objects to the observer.

This function will call startProcessingCycle() when it starts and endProcessingCycle() when it is done.

Parameters:

objects	A list of objects which must be attached.
ownership	The ownership that the observer should use to manage the object. The default is Observer::ManualOwnership.
import_cycle	Indicates if the attachment call was made during an observer import cycle. In such cases the subject filter must not add exportable properties to the object since these properties will be added from the import source. Also, it is not necessary to validate the context in such cases. False by default.
rejectMsg	When this function fails and rejectMsg will be populated with an rejection message when valid.

Returns:: A list of objects that was successfully added. Thus if the list has the same amount of items in objects, the operation was succesful on all objects.

See also:: attachSubject(), startProcessingCycle(), endProcessingCycle()

QList< QPointer< QObject > > Qtilities::Core::Observer::attachSubjects	(	ObserverMimeData *	mime_data_object,
		Observer::ObjectOwnership	ownership = `Observer::ManualOwnership`,
		QString *	rejectMsg = `0`,
		bool	import_cycle = `false`
	)

virtual

Will attempt to attach the specified objects in a ObserverMimeData object.

This function will call startProcessingCycle() when it starts and endProcessingCycle() when it is done.

Parameters:

obj	The object to be attached.
ownership	The ownership that the observer should use to manage the object. The default is Observer::ManualOwnership.
rejectMsg	When this function fails and rejectMsg will be populated with an rejection message when valid.
import_cycle	Indicates if the attachment call was made during an observer import cycle. In such cases the subject filter must not add exportable properties to the object since these properties will be added from the import source. Also, it is not necessary to validate the context in such cases. False by default.

Returns:: A list of objects which was successfully added. Thus if the list has the same amount of items in objects, the operation was succesful on all objects.

See also:: attachSubject(), startProcessingCycle(), endProcessingCycle()

bool Qtilities::Core::Observer::broadcastModificationStateChangesEnabled ( ) const

Indicates if broadcasting of modification state changes are enabled.

See also:: toggleBroadcastModificationStateChanges()

Qtilities::Core::Observer::EvaluationResult Qtilities::Core::Observer::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.

Parameters:

obj	The object to test attachment of.
rejectMsg	Rejection message. If the attachment cannot be done, thus it returns Observer::Rejected, you can get the reason through this error message.
ownership	This parameter allows you to specify the ownership to use during attachment. By default Observer::ManualOwnership.
silent	When true the function checks if the attachment can be done without using any dialog boxes. This is usefull when you need to attach subjects in an event filter where showing a dialog is a problem. An example of this is drag/drop operations in ObserverWidgets.

Qtilities::Core::Observer::EvaluationResult Qtilities::Core::Observer::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.

Parameters:

mime_data_object	The mime data object to test attachment of.
rejectMsg	Rejection message. If the attachment cannot be done, thus it returns Observer::Rejected, you can get the reason through this error message.
silent	When true the function checks if the attachment can be done without using any dialog boxes. This is useful when you need to attach subjects in an event filter where showing a dialog is a problem. An example of this is drag/drop operations in ObserverWidgets.

Qtilities::Core::Observer::EvaluationResult Qtilities::Core::Observer::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.

Parameters:

obj	The object to test detachment of.
rejectMsg	Rejection message. If the attachment cannot be done, thus it returns Observer::Rejected, you can get the reason through this error message.

Qtilities::Core::Observer::AccessMode Qtilities::Core::Observer::categoryAccessMode ( const QtilitiesCategory & category ) const

Returns the access mode for a specific category.

If the category does not exist, Observer::InvalidAccess is returned.

void Qtilities::Core::Observer::clearExportTask ( )

virtual

Clears the export task.

See also:: setExportTask(), exportTask()

Reimplemented from Qtilities::Core::Interfaces::IExportable.

bool Qtilities::Core::Observer::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.

Note:: Only depend on this function (where you specify the object using the object's name) when you are sure that objects have unique names. This can be achieved by installing a NamingPolicyFilter in your observer. If names are not unique, the first match of the given subject_name will be used. If you don't care about unique subject names, rather use subjectReference(int ID) to get subject references.

bool Qtilities::Core::Observer::copyHints ( ObserverHints * display_hints )

Function to let this observer copy a set of display hints.

This function allows you to copy the hints used by this Observer from a different ObserverHints instance.

Note:: If you call this function on the observer which does not have any displayHints() yet (thus useDisplayHints() have not been called yet) this function will call useDisplayHints() before inheriting the hints.

Returns:: True if successful, false otherwise.

See also:: useDisplayHints(), displayHints()

void Qtilities::Core::Observer::dataChanged ( Observer * observer = 0 )

signal

A signal which is emitted when the data in the observer or the tree underneath it changes.

This signal will be emitted whenever the data of the observer or any subjects in the tree underneath the observer changes.

This will happen when any of the following happens inside the observer context:

Activity changes happens.
Names of observers or subjects changes.

Parameters:

observer When the data that changed is related to a specific observer context, for example if the activity of all subjects inside a context changed, the observer can be passed as the observer parameter.

Note:: When creating models for observers, this signal should be connected to the dataChanged() signal of your model.

void Qtilities::Core::Observer::deleteAll	(	const QString &	base_class_name = `"QObject"`,
		bool	refresh_views = `true`
	)

virtualslot

Function to delete all currenlty observed subjects.

Parameters:

base_class_name	Specifies that only items inheriting the specified base class must be deleted.
refresh_views	Indicates if this function must refresh all observer views when done.

void Qtilities::Core::Observer::detachAll ( )

virtualslot

Function to detach all currently observed subjects.

This function will delete necessary objects, thus it will check the ownership of each subject and delete it when it has SpecificObserverOwnership set to this Observer, or when it has ObserverScopeOwnership and this is the last observer that it is attached to. Note that the deletion method used depends on the objectDeletionPolicy() of this observer.

bool Qtilities::Core::Observer::detachSubject	(	QObject *	obj,
		QString *	rejectMsg = `0`
	)

virtualslot

Will attempt to detach the specified object from the observer.

This function will delete obj if necessary, thus it will check its ownership and delete it when it has SpecificObserverOwnership set to this Observer, or when it has ObserverScopeOwnership and this is the last observer that it is attached to. Note that the deletion method used depends on the objectDeletionPolicy() of this observer.

Parameters:

obj	The object to be detached.
rejectMsg	When this function fails and rejectMsg will be populated with an rejection message when valid.

Returns:: True if successful, false otherwise.

QList< QPointer< QObject > > Qtilities::Core::Observer::detachSubjects	(	QList< QObject * >	objects,
		QString *	rejectMsg = `0`
	)

virtualslot

Will attempt to detach the specified object objects in the list from the observer.

This function will delete necessary objects, thus it will check the ownership of each subject and delete it when it has SpecificObserverOwnership set to this Observer, or when it has ObserverScopeOwnership and this is the last observer that it is attached to. Note that the deletion method used depends on the objectDeletionPolicy() of this observer.

Parameters:

objects	A list of objects which must be detached.
rejectMsg	When this function fails and rejectMsg will be populated with an rejection message when valid.

Returns:: A list of objects which was successfully detached.

Qtilities::Core::ObserverHints * Qtilities::Core::Observer::displayHints ( ) const

Function which returns a pointer to the ObserverHints used by this observer.

If no observer hints are used, 0 is returned.

See also:: useDisplayHints(), setDisplayHints()

void Qtilities::Core::Observer::endProcessingCycle ( bool broadcast = true )

virtual

Ends a processing cycle.

Ends a processing cycle started with startProcessingCycle(). The processing cycle will only be stopped when the number of endProcessingCycle() calls matches the number of startProcessingCycle() calls. If you call endProcessingCycle() too many times an error message will be printed using qWarning().

Parameters:

broadcast If the number of subjects changed during the processing cycle (thus, since startProcessingCycle() was called the first time), this function will automatically emit numberOfSubjectsChanged() and refreshLayout() when broadcast is true. When false, none of these signals are emitted. Also, if the observer's modification state is true after the processing cycle ended, the modificationStateChanged() signal will automatically be called when broadcast is true, and not when broadcast is false.

Note:: When emitting numberOfSubjectsChanged() the objects parameter will be empty even when the number of subjects changed.

See also:: startProcessingCycle(), isProcessingCycleActive(), processingCycleEnded(), endTreeProcessingCycle()

Reimplemented in Qtilities::CoreGui::TreeNode.

void Qtilities::Core::Observer::endTreeProcessingCycle ( bool broadcast = true )

virtual

Starts a processing cycle.

Same behaviour as startProcessingCyle(), but starts a processing cycle on the complete tree underneath the observer. Thus, processing cycles are started on all observers attached to this observer and those attached to that observer etc. It is important to node that you should use endTreeProcessingCycle() when using this function.

See also:: startTreeProcessingCycle(), endProcessingCycle(), subjectEventFilteringEnabled(), toggleSubjectEventFiltering(), isProcessingCycleActive(), processingCycleStarted()

Reimplemented in Qtilities::CoreGui::TreeNode.

bool Qtilities::Core::Observer::eventFilter	(	QObject *	object,
		QEvent *	event
	)

Event filter filters property change events on all subjects.

See also:: toggleSubjectEventFiltering(), toggleQtilitiesPropertyChangeEvents()

Qtilities::Core::Interfaces::IExportable::ExportResultFlags Qtilities::Core::Observer::exportBinary ( QDataStream & stream ) const

virtual

Allows exporting to a QDataStream.

See Serializing Qtilities Data Types Overview for more information about the expected output format.

Parameters:

stream A reference to the QDataStream to which the object's information must be appended is provided.

Reimplemented from Qtilities::Core::Interfaces::IExportable.

Qtilities::Core::Interfaces::IExportable::ExportResultFlags Qtilities::Core::Observer::exportXml	(	QDomDocument *	doc,
		QDomElement *	object_node
	)		const

virtual

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.

See Serializing Qtilities Data Types Overview for more information about the expected output format.

Reimplemented from Qtilities::Core::Interfaces::IExportable.

QVariant Qtilities::Core::Observer::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.

If the property_name does not refer to a shared property, the observer context of the observer on which this function is called will be used to define the observer context for which this function will get the property's value. If the property_name refers to a shared property, the shared property's value will be returned.

Qtilities::Core::Interfaces::IExportable::ExportResultFlags Qtilities::Core::Observer::importBinary	(	QDataStream &	stream,
		QList< QPointer< QObject > > &	import_list
	)

virtual

For subjects, the sequence in which the object reconstruction happens is as follows:

Construct object and set object name according to factory data.
Attach object.
Set object category if it exists.
Call the importXml() function on the object's IExportable implementation.
Set object activity.

Note:: This function does not call detachAll() before doing the import.

Reimplemented from Qtilities::Core::Interfaces::IExportable.

Qtilities::Core::Interfaces::IExportable::ExportResultFlags Qtilities::Core::Observer::importXml	(	QDomDocument *	doc,
		QDomElement *	object_node,
		QList< QPointer< QObject > > &	import_list
	)

virtual

For subjects, the sequence in which the object reconstruction happens is as follows:

Construct object and set object name according to factory data.
Attach object.
Set object category if it exists.
Call the importXml() function on the object's IExportable implementation.
Set object activity.

Note:: This function does not call detachAll() before doing the import.

Reimplemented from Qtilities::Core::Interfaces::IExportable.

bool Qtilities::Core::Observer::installSubjectFilter ( AbstractSubjectFilter * subject_filter )

Installs a new subject filter.

The observer will take ownership of the subject filter object and delete it in its constructor. Subject filters can only be installed when the observer has no subjects attached to it.

Subject filter names are unique in the context of an observer. This ensures that two filters of the same type cannot be installed in the same context. This function will check that the filterName() of subject_filter is unique and then add it. If it is not, the function will fail.

Qtilities::Core::InstanceFactoryInfo Qtilities::Core::Observer::instanceFactoryInfo ( ) const

virtual

The instance factory information which must be used when the exported object is reconstructed during an import.

For more information see The IExportable interface, what does it have to do with factories?.

Reimplemented from Qtilities::Core::Interfaces::IExportable.

bool Qtilities::Core::Observer::isProcessingCycleActive ( ) const

Indicates if a processing cycle is active.

See also:: startProcessingCycle(), endProcessingCycle()

bool Qtilities::Core::Observer::isSupportedType	(	const QString &	meta_type,
		Observer *	observer
	)

static

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.

See also:: Qtilities::Core::SubjectTypeInfo

void Qtilities::Core::Observer::layoutChanged ( QList< QPointer< QObject > > new_selection = QList< QPointer< QObject > >() )

signal

A signal which is emitted when the layout of the observer or the tree underneath it changes.

This signal will be emitted whenever the layout of an observer or the tree underneath it changes.

This will happen when any of the following happens inside the observer context:

Number of subjects changes in an observer context which is part of the tree.
Observer hints changes. Since observer hints define how item models displays (lays out) an observer context, changes to these hints will trigger the layoutChanged() signal.
Replace operations triggered by NamingPolicyFilter filters.
Observer access mode and access mode scope changes.
Subject access mode changes.

Parameters:

new_selection The new desired selection in any views that are refreshed due to the layout changed.

Note:: When creating models for observers, this signal should be connected to the layoutChanged() signal of your model for tree models. For table models connecting to numberOfSubjectsChanged() should be enough.

See also:: accessMode(), accessModeScope(), Qtilities::Core::Properties::qti_prop_ACCESS_MODE

void Qtilities::Core::Observer::modificationStateChanged ( bool is_modified ) const

virtualsignal

Implement this function as a signal when implementing the object.

Because this interface does not use the Q_OBJECT macro, you cannot connect to this signal directly. Instead you need to connect to the signal on the base object implementing this interface as follows:

connect(iface->objectBase(),SIGNAL(modificationStateChanged(bool)),SLOT(yourSlot(bool)));

Implements Qtilities::Core::Interfaces::IModificationNotifier.

QStringList Qtilities::Core::Observer::monitoredProperties ( ) const

This function returns a QStringList with the names of all the properties which are monitored by this observer.

Monitored properties are properties that are monitored for changes by the event filter of the observer and Qtilities::Core::AbstractSubjectFilter::handleMonitoredPropertyChange() functions on all subject filters installed in the observer context. The observer's event filter will automatically route the changes to monitored properties of installed subject filters to the correct subject filters.

When property changes are valid, the monitoredPropertyChanged() signal is emitted as soon as the property change is completed.

Note:: The list of monitored properties includes monitored properties of any installed subject filters.

See also:: monitoredPropertyChanged(), toggleSubjectEventFiltering(), propertyChangeFiltered()

void Qtilities::Core::Observer::monitoredPropertyChanged	(	const char *	property_name,
		QList< QObject * >	objects = `QList< QObject * >()`
	)

signal

A signal which is emitted as soon as a monitored property of the observer or any of the installed subject filters changed.

This signal is usefull when you want to monitor a specific object. This can be done in two ways:

By filtering the QtilitiesPropertyChangeEvent on the object. However events can only be delivered to objects in the same thread. Therefore, if the object you are interested in is in a different thread than the observer context, this will not work.
The alternative is to connect to this signal and check if the object you are interested in is in the list of objects on which the property changed.

Parameters:

property_name	The name of the property which changed.
objects	The objects on which the property changed.

See also:: monitoredProperties(), toggleSubjectEventFiltering(), propertyChangeFiltered()

bool Observer::monitorSubjectModificationState ( QObject * obj )

Gets if a subject's modification state must be monitored.

Returns:: True when the modification state of the object is monitored. False otherwise, or when the subject is not attached to this context.

See also:: setMonitorSubjectModificationState()

This function was added in Qtilities v1.2.

void Qtilities::Core::Observer::numberOfSubjectsChanged	(	Observer::SubjectChangeIndication	change_indication,
		QList< QPointer< QObject > >	objects = `QList< QPointer< QObject > >()`
	)

signal

A signal which is emitted when the number of subjects change in this observer context.

This signal only indicates if the number of subjects in this observer changes. To monitor number of subject changes in the complete tree under the observer, see layoutChanged().

Thus, for table views this is enough, for tree views use layoutChanged().

Parameters:

change_indication	Slots can use this indicator to know what change occurred.
objects	A list of objects which was added/removed. When the list contains null items, these objects were deleted and the observer picked it up and removed them. When this signal is emitted in endProcessingCycle() this list will be empty.

Note:: Whenever it is needed to emit this signal, Observer will first set the modification state of the Observer to true and then emit the signal.; When a processing cycle is active on the observer, this signal will be emitted at the end of the processing cycle in endProcessingCycle only if the number of subjects changed during the processing cycle. See endProcessingCycle() for more information.

const QObject* Qtilities::Core::Observer::objectBase ( ) const

inlinevirtual

Returns a const QObject* base of the interface.

This function can be used in const methods, but make sure that you don't modify things that should stay const. An example where this is used is when we want to get a property on an object in a const method. This is a const operation.

Implements Qtilities::Core::Interfaces::IObjectBase.

Qtilities::Core::Observer::ObjectDeletionPolicy Qtilities::Core::Observer::objectDeletionPolicy ( ) const

Function to get the observer's object deletion policy.

Default is DeleteLater.

See also:: setObjectDeletionPolicy()

int Qtilities::Core::Observer::parentCount ( const QObject * obj )

static

Convenience function to get the number of observers observing the specified object. Thus the number of parents of this object.

See also:: parentReferences()

QList< Qtilities::Core::Observer * > Qtilities::Core::Observer::parentReferences ( const QObject * obj )

static

Convenience function to get the a list of parent observers for this object.

See also:: parentCount()

void Qtilities::Core::Observer::propertyChangeFiltered	(	const char *	property_name,
		QList< QObject * >	objects = `QList< QObject * >()`
	)

signal

A signal which is emitted as soon as an property change event is filtered.

This signal can be emitted in two scenarios:

When an attempt is made to modify a reserved property it will always be emitted.
When a monitored property change is not allowed. An example of this is when a name change is rejected.

Parameters:

property_name	The name of the property on which the change was filtered.
objects	The objects on which the property was attempted.

See also:: reservedProperties(), monitoredProperties()

bool Qtilities::Core::Observer::qtilitiesPropertyChangeEventsEnabled ( ) const

Indicates if QtilitiesPropertyChangeEvents are enabled.

See also:: toggleQtilitiesPropertyChangeEvents(), subjectEventFilteringEnabled()

void Qtilities::Core::Observer::refreshViewsData ( bool force = false )

Function to refresh the data views showing this observer.

This function will emit the dataChanged(this) signal.

Parameters:

force When true views will be updated even if a processing cycle is currently active on the observer. When false the processing cycle will be respected.

void Qtilities::Core::Observer::refreshViewsLayout	(	QList< QPointer< QObject > >	new_selection = `QList<QPointer<QObject> >()`,
		bool	force = `false`
	)

Function to refresh the layout views showing this observer.

This function will emit the layoutChanged() signal with the new_selection parameter.

Parameters:

force When true views will be updated even if a processing cycle is currently active on the observer. When false the processing cycle will be respected.

QList< QPointer< QObject > > Qtilities::Core::Observer::renameCategory	(	const QtilitiesCategory &	old_category,
		const QtilitiesCategory &	new_category,
		bool	match_exactly = `true`
	)

Renames old_category to new_category in this observer context.

Parameters:

old_category	The category to rename.
new_category	The new name that must be given to the category.
match_exactly	When true, the old_category must match the new category exactly (thus the depths must match as well). When false, all categories that start with or match the old_category will be updated to start with or match the new category.

Returns:: A list with the subjects for which the category was renamed.

QStringList Qtilities::Core::Observer::reservedProperties ( ) const

This function returns a QStringList with the names of all the reserved properties inside this observer context.

Reserved properties are internal properties that cannot be changed. The observer will filter any attempted changes to these properties. To check if a property is reserved, see the Permission attribute in the property documentation. All Qtilities properties are defined in the Qtilities::Core::Properties namespace.

Note:: The list of reserved properties includes reserved properties of any installed subject filters.

See also:: propertyChangeFiltered()

void Qtilities::Core::Observer::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.

Note:: It is only possible to set the access mode for a category that exist. Thus an object must exist in the observer with the category you want to set the access mode for.

Parameters:

category Only used when accessModeScope() is categorized. Categories which does not have an access mode set for them will use the global access mode. The global access mode can be set by passing QString() as category.

void Qtilities::Core::Observer::setApplicationExportVersion ( quint32 version )

virtual

Sets the application export version currently used by all your application's classes.

See also:: applicationExportVersion()

Reimplemented from Qtilities::Core::Interfaces::IExportable.

void Qtilities::Core::Observer::setExportTask ( ITask * task )

virtual

Sets the task which must be used to log import/export information to.

To remove the task, use clearExportTask()

See also:: exportTask(), clearExportTask()

Reimplemented from Qtilities::Core::Interfaces::IExportable.

void Qtilities::Core::Observer::setExportVersion ( Qtilities::ExportVersion version )

virtual

Returns the export version currently used by all Qtilities classes.

By default the latest Qtilities version is selected.

See also:: exportVersion()

Reimplemented from Qtilities::Core::Interfaces::IExportable.

void Qtilities::Core::Observer::setFactoryData ( InstanceFactoryInfo factory_data )

protected

Sets the factory data which is necessary to reconstruct this observer.

When sub classing from Observer, it might be necessary to set use different factory data settings from the default data used for a normal observer. Call this function in your subclass constructor to change your object's factory data.

void Qtilities::Core::Observer::setModificationState	(	bool	new_state,
		IModificationNotifier::NotificationTargets	notification_targets = `IModificationNotifier::NotifyListeners`,
		bool	force_notifications = `false`
	)

slot

For observers, the listeners will only be notified if a processing cycle is not active or if it is forced using force_notifications.

See also:: isProcessingCycleActive(), startProcessingCycle(), endProcessingCycle()

bool Observer::setMonitorSubjectModificationState	(	QObject *	obj,
		bool	monitor
	)

Sets if a subject's modification state must be monitored.

Returns:: True when the needed property was set succesfully on the subject. False otherwise, or when the subject is not attached to this context.

See also:: monitorSubjectModificationState()

This function was added in Qtilities v1.2.

bool Qtilities::Core::Observer::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.

If the property_name does not refer to a shared property, the observer context of the observer on which this function is called will be used to define the observer context for which this function will set the property's value. If the property_name refers to a shared property, the shared property's value will be returned.

void Qtilities::Core::Observer::setObjectDeletionPolicy ( ObjectDeletionPolicy object_deletion_policy )

Function to set the observer's object deletion policy.

See also:: objectDeletionPolicy()

bool Qtilities::Core::Observer::setSubjectLimit ( int subject_limit )

Function to set the subject limit of this observer.

Returns:: Returns true if the limit was set successfully, otherwise false.

void Qtilities::Core::Observer::startProcessingCycle ( )

virtual

Starts a processing cycle.

When adding/removing many subjects to the observer it makes sense to only let item views know that the observer changed when all subjects have been added/removed. This function will disable the change notification signals of this observer until endProcessingCycle() is called.

Note that this function only affects signals emitted by the observer. The observer still monitors dynamic property changes on all attached subjects during a processing cycle. To control the event filtering, see subjectEventFilteringEnabled() and toggleSubjectEventFiltering().

If a processing cycle was already started, this function does nothing.

Internally observers keep track of how many times you start and end processing cycles. To stop a processing cycle you need to call endProcessingCycle() the same number of times you called startProcessingCycle(). Thus, you don't need to keep track if a processing cycle was already started in the beginning of your function (you don't have to care about it). For example:

Observer obs;
obs.startProcessingCycle(); // Internal count = 1;
obs.startProcessingCycle(); // Internal count = 2;
// Some function gets the observer without any knowledge of previous start/end processing cycle calls:
// It is not necessary to do the following:
{
    bool is_cycle_active = obs.isProcessingCycleActive();
    obs.startProcessingCycle(); // Internal count = 3;
    // Do some batch processing.
    // If we did not have an internal counter the correct way to end it in a function would be:
    if (!is_cycle_active)
        obs.endProcessingCycle(); // Internal count = 2;
    // However, since there is an internal counter we can ignore the is_cycle_active declaration in the above code and just call:
    obs.endProcessingCycle();
}
obs.endProcessingCycle(); // Internal count = 1;
obs.endProcessingCycle(); // Internal count = 0;

Note:: It is very important to note that the observer's layoutChanged() and dataChanged() signals are not emitted during processing cycles. Thus, views displaying the observer are not going to update during processing cycles. When calling endProcessingCycle with the broadcast parameter set to true (the default) the correct signals will be emitted only if the number of subjects changed during the processing cycle. See endProcessingCycle() for more information.

See also:: endProcessingCycle(), subjectEventFilteringEnabled(), toggleSubjectEventFiltering(), isProcessingCycleActive(), processingCycleStarted(), startTreeProcessingCyle()

Reimplemented in Qtilities::CoreGui::TreeNode.

void Qtilities::Core::Observer::startTreeProcessingCycle ( )

virtual

Starts a processing cycle.

Same behaviour as startProcessingCyle(), but starts a processing cycle on the complete tree underneath the observer. Thus, processing cycles are started on all observers attached to this observer and those attached to that observer etc. It is important to node that you should use endTreeProcessingCycle() when using this function.

See also:: endTreeProcessingCycle(), endProcessingCycle(), subjectEventFilteringEnabled(), toggleSubjectEventFiltering(), isProcessingCycleActive(), processingCycleStarted()

Reimplemented in Qtilities::CoreGui::TreeNode.

QList< Qtilities::Core::QtilitiesCategory > Qtilities::Core::Observer::subjectCategories ( ) const

Returns a QStringList with all the categories found in the qti_prop_CATEGORY_MAP properties of all attached subjects.

This function does not take the category filtering options of the observer into account, for that functionality see displayedCategories() on the observer hints for this observer provided by hints(). Category filtering is only related to the displaying of the observer.

int Qtilities::Core::Observer::subjectCount ( const QString & base_class_name = QString() ) const

Returns the number of subjects currently observed by the observer.

This function is different from treeCount() which gets all the children underneath an observer (Thus, children of children etc.).

QString Qtilities::Core::Observer::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.

The displayed name is found using the following sequence, returning the first match:

Check if the object has the qti_prop_DISPLAYED_ALIAS_MAP property
Check if the object has the qti_prop_ALIAS_MAP property
Lastly, just return the objectName()

Parameters:

obj	The object for which the name must be fetched.
check_displayed_name_property	Indicates if the qti_prop_DISPLAYED_ALIAS_MAP property must be checked.
validate_object	When true, the function will first check if the object exists in the context.

Returns:: The name if the object was found, and empty QString() otherwise.

bool Qtilities::Core::Observer::subjectEventFilteringEnabled ( ) const

Indicates if subject event filtering is enabled.

See also:: toggleSubjectEventFiltering(), qtilitiesPropertyChangeEventsEnabled()

int Qtilities::Core::Observer::subjectID	(	const QString &	subject_name,
		Qt::CaseSensitivity	cs = `Qt::CaseSensitive`
	)		const

Returns the ID associated with a specific subject.

Note:: Only depend on this function (where you specify the object using the object's name) when you are sure that objects have unique names. This can be achieved by installing a NamingPolicyFilter in your observer. If names are not unique, the first match of the given subject_name will be used. If you don't care about unique subject names, rather use subjectReference(int ID) to get subject references.

QList< QPointer< Observer > > Observer::subjectObserverReferences ( ) const

Returns a list of observers under this observer.

This is an optimized function to get observer references under this observer. Thus, its much faster than something like subjectReferences("Observer") or subjectReferences("TreeNode").

Qtilities::Core::Observer::ObjectOwnership Qtilities::Core::Observer::subjectOwnershipInContext ( const QObject * obj ) const

Returns the ownership used for the specified object in this context.

If obj is not valid or contained in this context, ManualOwnership is returned. Thus you should check if the object exists in this context using contains() before calling this function.

QObject * Qtilities::Core::Observer::subjectReference	(	const QString &	subject_name,
		Qt::CaseSensitivity	cs = `Qt::CaseSensitive`
	)		const

Gets the subject reference for a specific object name.

Note:: Only depend on this function (where you specify the object using the object's name) when you are sure that objects have unique names. This can be achieved by installing a NamingPolicyFilter in your observer. If names are not unique, the first match of the given subject_name will be used. If you don't care about unique subject names, rather use subjectReference(int ID) to get subject references.

Qtilities::Core::Interfaces::IExportable::ExportModeFlags Qtilities::Core::Observer::supportedFormats ( ) const

virtual

Provides information about the export format(s) supported by your implementation of IExportable.

Note:: It is important to note that you need to check the exportVersion() when you return the supported formats.

Reimplemented from Qtilities::Core::Interfaces::IExportable.

void Qtilities::Core::Observer::toggleBroadcastModificationStateChanges ( bool toggle )

This function enables/disables broadcasting of modification state changes Observer.

If you don't use modification state changes turning this off will increase performance.

See also:: broadcastModificationStateChangesEnabled()

void Qtilities::Core::Observer::toggleQtilitiesPropertyChangeEvents ( bool toggle )

This function enables/disables delivery of QtilitiesPropertyChangeEvents on objects when property changes occurs.

Parameters:

toggle When true, change events are delivered. When false they are not delivered.

See monitoredPropertyChanged() for more details on when property change events can be used. If your implementation does not use property change events, you should disabled the events to optimize performance.

Note:: These events are disabled by default.

See also:: qtilitiesPropertyChangeEventsEnabled(), toggleSubjectEventFiltering()

void Qtilities::Core::Observer::toggleSubjectEventFiltering ( bool toggle )

This function toggles event filtering on objects.

It is recommended to always keep event filtering enabled. However in some cases, like object reconstruction in ObjectManager::constructRelationships() it is necessary to manually edit read only properties (like ownership etc.). Another example is when you want to attach objects in threads other than the observer's thread to it. In such cases you can disable subject event filtering on objects attached to your subjects.

Parameters:

toggle True is event filtering is enabled, thus property changes are monitored by the observer. False otherwise.

Note:: Event filtering is enabled by default. It is also important to know that events won't be monitored on subjects which were attached while subject event filtering was disabled, even if you turn on subject event filtering again at a later stage. Therefore it is best to call this function only once, before attaching any objects to your observer.

See also:: subjectEventFilteringEnabled(), qtilitiesPropertyChangeEventsEnabled()

QObject * Qtilities::Core::Observer::treeAt ( int i ) const

Function to get a QObject reference at a specific location in the tree underneath this observer.

If i is < 0 or bigger than or equal to the number of items retuned by allChildren() this function returns 0.

QList< QObject * > Qtilities::Core::Observer::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.

Returns a list of QObjects* in tree underneath this observer where the list is populated in the same order in which Qtilities::Core::TreeIterator iterates through the tree.

Parameters:

base_class_name	The name of the base class of children you are looking for. By default, all children underneath this observer is returned.
limit	When defined, the tree children will be search up until the limit count is reached. This allows you to stop when a tree gets too big. By default all children are returned.
iterator_id	Internal iterator ID. You should never use this directly.

For example:

QList<QObject*> children;
TreeNode* rootNode = new TreeNode("Root");
TreeNode* parentNode1 = rootNode->addNode("Parent 1");
TreeNode* parentNode2 = rootNode->addNode("Parent 2");
parentNode1->addItem("Child 1");
parentNode1->addItem("Child 2");
parentNode2->addItem("Child 3");
parentNode2->addItem("Child 5");
// The following call will return
QList<QObject*> nodes_verify = rootNode->treeChildren("Qtilities::CoreGui::TreeNode");
QVERIFY(nodes_verify.count() == 2);
QList<QObject*> items_verify = rootNode->treeChildren("Qtilities::CoreGui::TreeItem");
QVERIFY(items_verify.count() == 5);

Note:: This observer itself is not part of the list.

int Qtilities::Core::Observer::treeCount ( const QString & base_class_name = QString() )

Function to get the number of children under the specified observer.

This count includes the children of children as well. To get the number of subjects only in this context use subjectCount().

Note:: This observer itself is not counted.

bool Qtilities::Core::Observer::uninstallSubjectFilter ( AbstractSubjectFilter * subject_filter )

Uninstalls a subject filter.

This function will delete the subject filter since subject filters can only be used once at present.

Qtilities::Core::ObserverHints * Qtilities::Core::Observer::useDisplayHints ( )

Function which constructs hints for this observer.

If the observer does not have any hints, this function will construct an ObserverHints instance and assign it to this observer. If the observer already has hints associated with it, this function does nothing.

Returns:: The constructed hints instance, if hints were already present, returns 0.

See also:: displayHints(), setDisplayHints()

Public Types

Public Slots

Signals

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Displaying the context of an Observer

Observer Trees

Subject filters

Observers and threads

Under The Hood: How observers work behind the scenes.

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation