A subject filter which only allows attachement of specific object types. More...

#include <SubjectTypeFilter.h>

Inheritance diagram for Qtilities::Core::SubjectTypeFilter:

[legend]

Signals
void	modificationStateChanged (bool is_modified) const
	Implement this function as a signal when implementing the object.
Signals inherited from Qtilities::Core::AbstractSubjectFilter
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
void	addSubjectType (SubjectTypeInfo subject_type_info)
	Adds a known subject type .
void	enableInverseFiltering (bool enabled)
	Inverse the list of known subject types. Thus all unknown types are allowed and known types are filtered, rather than the defualt filtering of all unkown types.
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.
IExportable::ExportResultFlags	exportBinary (QDataStream &stream) const
	Allows exporting to a QDataStream.
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.
QString	filterName () const
	Returns the name of the subject filter.
QString	groupName () const
	Gets the name describing the known subject grouping.
IExportable::ExportResultFlags	importBinary (QDataStream &stream, QList< QPointer< QObject > > &import_list)
	Allows importing and reconstruction of the object state from information provided in a QDataStream.
IExportable::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.
InstanceFactoryInfo	instanceFactoryInfo () const
	The instance factory information which must be used when the exported object is reconstructed during an import.
bool	inverseFilteringEnabled () const
	Returns true if inverse filtering is enabled. The default is false, thus the filter will filter all object types unless you add known types.
bool	isKnownType (const QString &meta_type) const
	Returns true if the specified type if a known type in this filter.
bool	isModified () const
	Indicates the modification state of the object.
QList< SubjectTypeInfo >	knownSubjectTypes () const
	Provides a list of all the subject types known to this subject type filter.
QObject *	objectBase ()
	Returns the QObject* base of the interface.
const QObject *	objectBase () const
	Returns a const QObject* base of the interface.
void	setGroupName (const QString &group_name)
	Sets the name describing the known subject grouping.
ExportModeFlags	supportedFormats () const
	Provides information about the export format(s) supported by your implementation of IExportable.
Public Member Functions inherited from Qtilities::Core::AbstractSubjectFilter
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 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 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	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.
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.

Protected Member Functions
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.

Additional Inherited Members
Public Types inherited from Qtilities::Core::AbstractSubjectFilter
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...
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...
Protected Attributes inherited from Qtilities::Core::AbstractSubjectFilter
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.

Detailed Description

A subject filter which only allows attachement of specific object types.

The SubjectTypeFilter allows control over the types of objects which can be attached to an observer context. The filter only allows known subject types to be attached. A subject type is defined by the SubjectTypeInfo struct and each filter only knows about subject types added to it using the addSubjectType() function. You can inverse the known filter types by calling the enableInverseFiltering() function. In this scenario the filter will only allow attachment of unknown filter type and it will filter all known types.

Checking if an object to be attached matches any of the known types is done through the QObject::inherits() function. Thus if you add QObject as a known type, any object inheriting QObject will be allowed while non QObject based objects will be filtered.

Another usefull feature of the SubjectTypeFilter class is that it provides a name for the group of subjects that is known to it which is accessable through groupName(). The group name is set in the constructor of the filter.

To install a SubjectTypeFilter on an Observer is easy:

Observer* obs = new Observer;
SubjectTypeFilter* subject_type_filter = new SubjectTypeFilter;
subject_type_filter->addSubjectType(SubjectTypeInfo("TestMetaType1","TestTypeName1"));
subject_type_filter->setGroupName("TestGroupName");
subject_type_filter->enableInverseFiltering(true);
obs->installSubjectFilter(subject_type_filter);

When you use Qtilities::CoreGui::TreeNode instead, its even easier:

TreeNode* tree_node = new TreeNode;
SubjectTypeFilter* subject_type_filter = tree_node->setChildType("TestGroupName");
subject_type_filter->addSubjectType(SubjectTypeInfo("TestMetaType1","TestTypeName1"));
subject_type_filter->enableInverseFiltering(true);

Note:: You need to set up your filter before attaching any subjects to its observer context.

See also:: Observer, AbstractSubjectFilter, ActivityPolicyFilter, NamingPolicyFilter

Member Function Documentation

void Qtilities::Core::SubjectTypeFilter::addSubjectType ( SubjectTypeInfo subject_type_info )

Adds a known subject type .

Note:: Known subject types can only be added when no subjects are attached to the filter's observer context.

See also:: isKnownType(), knownSubjectTypes()

void Qtilities::Core::SubjectTypeFilter::enableInverseFiltering ( bool enabled )

Inverse the list of known subject types. Thus all unknown types are allowed and known types are filtered, rather than the defualt filtering of all unkown types.

Note:: Inversed filtering can only changed when no subjects are attached to the filter's observer context.; When constructing a SubjectTypeFilter using the Qtilities::CoreGui::TreeNode class's setChildType() function, inversed filtering is enabled by default.

See also:: inverseFilteringEnabled()

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

virtual

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

Qtilities::Core::Interfaces::IExportable::ExportResultFlags Qtilities::Core::SubjectTypeFilter::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::SubjectTypeFilter::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.

QString Qtilities::Core::SubjectTypeFilter::groupName ( ) const

Gets the name describing the known subject grouping.

See also:: setGroupName()

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

protectedvirtual

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

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

virtual

Allows importing and reconstruction of the object state from information provided in a QDataStream.

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

Parameters:

stream	The QDataStream which contains the object's information.
import_list	All objects constructed during the import operation must be added to the import list. When the operation fails, all objects in this list will be deleted.

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

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

virtual

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.

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

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

Qtilities::Core::InstanceFactoryInfo Qtilities::Core::SubjectTypeFilter::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::SubjectTypeFilter::inverseFilteringEnabled ( ) const

Returns true if inverse filtering is enabled. The default is false, thus the filter will filter all object types unless you add known types.

See also:: enableInverseFiltering()

bool Qtilities::Core::SubjectTypeFilter::isKnownType ( const QString & meta_type ) const

Returns true if the specified type if a known type in this filter.

This call takes the inverse filtering setting into account. Note that the name of the SubjectTypeInfo struct is not checked but rather the d_meta_type field.

See also:: knownSubjectTypes(), addSubjectType()

QList< Qtilities::Core::SubjectTypeInfo > Qtilities::Core::SubjectTypeFilter::knownSubjectTypes ( ) const

Provides a list of all the subject types known to this subject type filter.

See also:: isKnownType(), addSubjectType()

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

const QObject* Qtilities::Core::SubjectTypeFilter::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.

void Qtilities::Core::SubjectTypeFilter::setGroupName ( const QString & group_name )

Sets the name describing the known subject grouping.

See also:: groupName()

Qtilities::Core::Interfaces::IExportable::ExportModeFlags Qtilities::Core::SubjectTypeFilter::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.

Signals

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation