The AbstractSubjectFilter class provides the abstract interface for observer subject filters. More...

#include <AbstractSubjectFilter.h>

Inheritance diagram for Qtilities::Core::AbstractSubjectFilter:

[legend]

Public Types
enum	EvaluationResult { Allowed, Conditional, Rejected }
	Enumeration which defines the possible results of subject filter evaluation operations. 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...

Signals
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	propertyChangeFiltered (const char property_name, QList< QObject > objects=QList< QObject * >())
	A signal which is emitted as soon as an property change event is filtered.

Public Member Functions
virtual AbstractSubjectFilter::EvaluationResult	evaluateAttachment (QObject obj, QString rejectMsg=0, bool silent=false) const
	Evaluates the attachment of a new subject to the filter's observer context. Use this function to check how an attachment will be handled.
virtual AbstractSubjectFilter::EvaluationResult	evaluateDetachment (QObject obj, QString rejectMsg=0) const
	Evaluates the detachment of a subject from the filter's observer context. Use this function to check how an detachment will be handled.
virtual QString	filterName () const =0
	Returns the name of the subject filter.
virtual void	finalizeAttachment (QObject *obj, bool attachment_successful, bool import_cycle=false)
	Finalize the attachment of a the subject to the filter's observer context.
virtual void	finalizeDetachment (QObject *obj, bool detachment_successful, bool subject_deleted=false)
	Finalize the detachment of a subject from the filter's observer context.
virtual bool	initializeAttachment (QObject obj, QString rejectMsg=0, bool import_cycle=false)
	Initialize the attachment of a new subject to the filter's observer context.
virtual bool	initializeDetachment (QObject obj, QString rejectMsg=0, bool subject_deleted=false)
	Initialize the detachment of a subject from the filter's observer context.
virtual bool	isModificationStateMonitored () const
	Get if this subject filter's modification state is monitored by its observer context.
virtual QStringList	monitoredProperties () const
	This function returns a QStringList with the names of all the properties which are monitored by this subject filter.
Observer *	observerContext () const
	Returns the observer context that this subject filter is attached to.
virtual QStringList	reservedProperties () const
	This function returns a QStringList with the names of all the reserved properties of this subject filter.
virtual void	setIsModificationStateMonitored (bool is_monitored)
	Set if this subject filter's modification state is monitored by its observer context.
virtual bool	setObserverContext (Observer *observer_context)
	Set the observer context for the subject filter. A subject filter is not usable when an observer context to operate in has not been set.
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.
virtual void	clearExportTask ()
	Clears the export task.
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 ExportResultFlags	exportBinary (QDataStream &stream) const
	Allows exporting to a QDataStream.
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.
virtual 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.
virtual ExportResultFlags	importBinary (QDataStream &stream, QList< QPointer< QObject > > &import_list)
	Allows importing and reconstruction of the object state from information provided in a QDataStream.
virtual ExportResultFlags	importXml (QDomDocument doc, QDomElement object_node, QList< QPointer< QObject > > &import_list)
	Allows importing and reconstruction of data from information provided in a XML document. A reference to the QDomElement which contains the object's information is provided, along with a reference to the QDomDocument.
virtual InstanceFactoryInfo	instanceFactoryInfo () const
	The instance factory information which must be used when the exported object is reconstructed during an import.
bool	isExportable () const
	Gets if this object must be part of it's parents' exports.
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.
virtual void	setIsExportable (bool new_is_exportable)
	Sets if this object must be part of it's parents' exports.
virtual ExportModeFlags	supportedFormats () const
	Provides information about the export format(s) supported by your implementation of IExportable.
Public Member Functions inherited from Qtilities::Core::Interfaces::IObjectBase
virtual QObject *	objectBase ()=0
	Returns the QObject* base of the interface.
virtual const QObject *	objectBase () const =0
	Returns a const QObject* base of the interface.
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.

Protected Member Functions
virtual bool	handleMonitoredPropertyChange (QObject obj, const char property_name, QDynamicPropertyChangeEvent *propertyChangeEvent)
	Function which should react to QDynamicPropertyChangeEvents on properties which are reserved by the subject filter.

Protected Attributes
bool	filter_is_modification_state_monitored
	Indicates if the modification state of the filter is monitored by it's observer context.
Observer *	observer
	The observer context to which the subject filter is attached.

Additional Inherited Members
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.

Detailed Description

The AbstractSubjectFilter class provides the abstract interface for observer subject filters.

The AbstractSubjectFilter class defines the standard interface that subject filters must use to be able to interoperate with observers. It is not supposed and cannot to be instantiated directly. Instead, you should subclass it to create new subject filters.

In short, a subject filter is used by an observer to evaulate specific operations performed on subjects by observers. Each subject filter needs an observer context which is set using setObserverContext(). Without the observer context set, the filter is not usable. When installing subject filters using the Qtilities::Core::Observer::installSubjectFilter() function the observer context will automatically be set. On the other hand, Qtilities::Core::Observer::uninstallSubjectFilter() will set the observer context to 0.

For a detailed overview of subject filters, see the Subject filters section of the Observers article.

Member Enumeration Documentation

enum Qtilities::Core::AbstractSubjectFilter::EvaluationResult

Enumeration which defines the possible results of subject filter evaluation operations.

See also:: evaluateAttachment(), evaluateDetachment()

Enumerator:

Allowed	Successful validation.
Conditional	Validation is conditional. Examples of this is when the user still needs to decide how to rename an object, thus it is not possible to know before hand what the result will be.
Rejected	Validation failed.

Member Function Documentation

virtual AbstractSubjectFilter::EvaluationResult Qtilities::Core::AbstractSubjectFilter::evaluateAttachment	(	QObject *	obj,
		QString *	rejectMsg = `0`,
		bool	silent = `false`
	)		const

inlinevirtual

Evaluates the attachment of a new subject to the filter's observer context. Use this function to check how an attachment will be handled.

Parameters:

obj	The object to be evaluated
rejectMsg	Provides a reject message when the evaluation failed.
silent	When true, the attachment must be done in a silent way. That is, it should not show any dialogs. This is usefull when objects must be attached to observers without calling exec() on a dialog (such as the user input dialog for NamingPolicyFilters) which can lead to crashes when for example attaching objects inside an event filter. For more information on this topic see Unpredictable exec().

Returns:: AbstractSubjectFilter::EvaluationResult indicating the result of the evaluation.

Note:: By default AbstractSubjectFilter::Allowed is returned by the base class.

Reimplemented in Qtilities::CoreGui::NamingPolicyFilter, Qtilities::Core::SubjectTypeFilter, and Qtilities::Core::SubjectFilterTemplate.

virtual AbstractSubjectFilter::EvaluationResult Qtilities::Core::AbstractSubjectFilter::evaluateDetachment	(	QObject *	obj,
		QString *	rejectMsg = `0`
	)		const

inlinevirtual

Evaluates the detachment of a subject from the filter's observer context. Use this function to check how an detachment will be handled.

Parameters:

obj	The object to be evaluated
rejectMsg	Provides a reject message when the evaluation failed.

Returns:: AbstractSubjectFilter::EvaluationResult indicating the result of the evaluation.

Note:: By default AbstractSubjectFilter::Allowed is returned by the base class.

Reimplemented in Qtilities::Core::SubjectFilterTemplate.

virtual void Qtilities::Core::AbstractSubjectFilter::finalizeAttachment	(	QObject *	obj,
		bool	attachment_successful,
		bool	import_cycle = `false`
	)

inlinevirtual

Finalize the attachment of a the subject to the filter's observer context.

Note:: When attachment_successful is true, the object will already be attached to the observer context.

Parameters:

obj	The object to be added.
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 neccesarry to validate the context in such cases.
attachment_successful	True if the attachment was successful, false otherwise.

Note:: By default does nothing in the base class.

Reimplemented in Qtilities::Core::ActivityPolicyFilter, Qtilities::CoreGui::NamingPolicyFilter, and Qtilities::Core::SubjectFilterTemplate.

virtual void Qtilities::Core::AbstractSubjectFilter::finalizeDetachment	(	QObject *	obj,
		bool	detachment_successful,
		bool	subject_deleted = `false`
	)

inlinevirtual

Finalize the detachment of a subject from the filter's observer context.

Parameters:

obj	The object to be detached.
detachment_successful	True if the detachment was successfull, false otherwise.
subject_deleted	Indicates if the detachment operation is happening because the subject was deleted. This allows for optimization inside implementations of this function.

Note:: By default does nothing in the base class.

Reimplemented in Qtilities::Core::ActivityPolicyFilter, Qtilities::CoreGui::NamingPolicyFilter, and Qtilities::Core::SubjectFilterTemplate.

virtual bool Qtilities::Core::AbstractSubjectFilter::handleMonitoredPropertyChange	(	QObject *	obj,
		const char *	property_name,
		QDynamicPropertyChangeEvent *	propertyChangeEvent
	)

inlineprotectedvirtual

Function which should react to QDynamicPropertyChangeEvents on properties which are reserved by the subject filter.

As soon as a subject is attached to an observer the observer installs a event filter on the subject which monitors dynamic property changes. When a dynamic property change event is received, the observer will route the event to the appropriate subject filter and call this function on the subject filter. Thus, this function will only be called when the property_name is a reserved property of the subject filter.

Parameters:

obj	The object on which the property change took place.
property_name	The property name which changed.
propertyChangeEvent	The QDynamicPropertyChangeEvent which triggered the event.

Returns:: Return true if the event should be filtered (thus, the event will not be allowed to finish and the property will not change), false otherwise when the change event should be allowed (thus, the event will not be filtered and the property will change if not filtered by any other subject filters).

Note:: By default false is returned by the base class.

See also:: monitoredProperties()

Reimplemented in Qtilities::Core::ActivityPolicyFilter, Qtilities::CoreGui::NamingPolicyFilter, Qtilities::Core::SubjectTypeFilter, and Qtilities::Core::SubjectFilterTemplate.

virtual bool Qtilities::Core::AbstractSubjectFilter::initializeAttachment	(	QObject *	obj,
		QString *	rejectMsg = `0`,
		bool	import_cycle = `false`
	)

inlinevirtual

Initialize the attachment of a new subject to the filter's observer context.

Note:: The object is not yet attached to the observer context when this function is called.

Parameters:

obj	The object to be added.
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 neccesarry to validate the context in such cases.

Returns:: Return true if the attachment is allowed, false otherwise.; True if the attachment was successfully initialized, false otherwise.

Note:: By default true is returned by the base class.

Reimplemented in Qtilities::Core::ActivityPolicyFilter, Qtilities::CoreGui::NamingPolicyFilter, and Qtilities::Core::SubjectFilterTemplate.

virtual bool Qtilities::Core::AbstractSubjectFilter::initializeDetachment	(	QObject *	obj,
		QString *	rejectMsg = `0`,
		bool	subject_deleted = `false`
	)

inlinevirtual

Initialize the detachment of a subject from the filter's observer context.

Parameters:

obj	The object to be detached.
rejectMsg	A reject message when the initialization fails.
subject_deleted	Indicates if the detachment operation is happening because the subject was deleted. This allows for optimization inside implementations of this function.

Returns:: True if the detachment is allowed, false otherwise.

Note:: By default true is returned by the base class.

Reimplemented in Qtilities::Core::SubjectFilterTemplate.

virtual bool Qtilities::Core::AbstractSubjectFilter::isModificationStateMonitored ( ) const

inlinevirtual

Get if this subject filter's modification state is monitored by its observer context.

Returns:: True by default.

virtual QStringList Qtilities::Core::AbstractSubjectFilter::monitoredProperties ( ) const

inlinevirtual

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

Monitored properties are all properties that you use on your subject filter that does not appear in the reservedProperties() list. All of these properties will be monitored by the observer context in which the subject filter is installed. The property change events will be delivered to handleMonitoredPropertyChange().

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

Note:: By default an empty QStringList() is returned by the base class.

See also:: handleMonitoredPropertyChange(), monitoredPropertyChanged()

Reimplemented in Qtilities::Core::ActivityPolicyFilter, Qtilities::CoreGui::NamingPolicyFilter, and Qtilities::Core::SubjectFilterTemplate.

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

The observer context in which the subject filter is installed will listen to this signal and emit the Qtilities::Core::Observer::monitoredPropertyChanged() signal whenever this signal is emitted.

Parameters:

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

See also:: monitoredProperties(), handleMonitoredPropertyChange()

void Qtilities::Core::AbstractSubjectFilter::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 on the observer level.
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()

virtual QStringList Qtilities::Core::AbstractSubjectFilter::reservedProperties ( ) const

inlinevirtual

This function returns a QStringList with the names of all the reserved properties of this subject filter.

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 Permisson attribute in the property documentation. All Qtilities properties are defined in the Qtilities::Core::Properties namespace.

Note:: By default an empty QStringList() is returned by the base class.

Reimplemented in Qtilities::CoreGui::NamingPolicyFilter, and Qtilities::Core::SubjectFilterTemplate.

virtual void Qtilities::Core::AbstractSubjectFilter::setIsModificationStateMonitored ( bool is_monitored )

inlinevirtual

Set if this subject filter's modification state is monitored by its observer context.

Note:: Make sure to set this before you attach the subject filter to your observer context in order for it to work properly.; By default the base class does nothing when this function is called.

virtual bool Qtilities::Core::AbstractSubjectFilter::setObserverContext ( Observer * observer_context )

inlinevirtual

Set the observer context for the subject filter. A subject filter is not usable when an observer context to operate in has not been set.

Note:: The observer context of a subject filter can only be set once. Thus, you cannot use a subject filter more than once. Once you uninstalled it from an observer, you must delete it.

Reimplemented in Qtilities::Core::ActivityPolicyFilter.

Public Types

Signals

Public Member Functions

Protected Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

Member Function Documentation