The NamingPolicyFilter class is an implementation of AbstractSubjectFilter which allows control over naming of objects within the context of an Observer. More...

#include <NamingPolicyFilter.h>

Inheritance diagram for Qtilities::CoreGui::NamingPolicyFilter:

[legend]

List of all members.

Public Types
enum	ResolutionPolicy { AutoRename = 0, PromptUser = 1, Replace = 2, Reject = 3 }
	Policy to control how invalid or duplicate names should be handled. More...
enum	UniquenessPolicy { AllowDuplicateNames, ProhibitDuplicateNames, ProhibitDuplicateNamesCaseSensitive }
	Policy to control uniqueness of subject names in the observer context in which this filter is installed. More...
enum	ValidationCheck { NoChecks = 0, Validity = 1, Uniqueness = 2, AllChecks = Validity \| Uniqueness }
	Policy to control which checks must be performed by the filter. More...
enum	ValidityCheckResult { Acceptable = 0, Duplicate = 1, Invalid = 2 }
	Enumeration defining the possible outcames of name evaluation operations. More...
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...

Signals
void	modificationStateChanged (bool is_modified) const
	Implement this function as a signal when implementing the object.
void	subjectNameChanged (QObject *obj, const QString &old_name, const QString &new_name)
	Signal which is emitted when the name of an object who's name is managed by this policy filter is changed.
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
virtual INamingPolicyDialog *	constructUserDialog () const
	Constructs the input dialog presented to the user when using PromptUser policies.
QString	debugInfo () const
	Provides debug information about this filter.
void	endValidationCycle ()
	Function which ends a naming validation cycle.
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 NamingPolicyFilter::NameValidity	evaluateName (const QString &name, QObject *object=0) const
	Evaluates a name in the observer context in which this subject filter is installed.
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.
void	finalizeAttachment (QObject *obj, bool attachment_successful, bool import_cycle=false)
	Finalize the attachment of a the subject to the filter's observer context.
void	finalizeDetachment (QObject *obj, bool detachment_successful, bool subject_deleted=false)
	Finalize the detachment of a subject from the filter's observer context.
virtual QString	generateValidName (QString input_name=QString(), bool force_change=false)
	Attempt to generate a valid name in the context from the given input_name.
QObject *	getConflictingObject (const QString &name) const
	Gets the object which conflicts with the specified name. If no object conflicts, returns 0.
virtual QString	getEvaluationName (QObject *object) const
	Gets the name to be used during evaluateName() for a specific object.
QString	getName (QObject *object)
	Function which gets the name of the object.
QValidator *	getValidator ()
	Gets the validator used to validate names.
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.
bool	initializeAttachment (QObject obj, QString rejectMsg=0, bool import_cycle=false)
	Initialize the attachment of a new subject to the filter's observer context.
InstanceFactoryInfo	instanceFactoryInfo () const
	The instance factory information which must be used when the exported object is reconstructed during an import.
bool	isModified () const
	Indicates the modification state of the object.
bool	isObjectNameManager (QObject *obj) const
	Checks if this subject filter is the name manager of the specified object.
bool	isValidationCycleActive () const
	Returns true if a validation cycle is active at present.
void	makeNameManager (QObject *obj)
	Function which makes this naming policy filter the object name manager of the given object.
QStringList	monitoredProperties () const
	This function returns a QStringList with the names of all the properties which are monitored by this subject filter.
QObject *	objectBase ()
	Returns the QObject* base of the interface.
const QObject *	objectBase () const
	Returns a const QObject* base of the interface.
NamingPolicyFilter::ValidationCheckFlags	processingCycleValidationChecks () const
	Gets the naming checks that must be done when this filter's observer context is busy with a processing cycle.
QStringList	reservedProperties () const
	This function returns a QStringList with the names of all the reserved properties of this subject filter.
void	setConflictingObject (QObject *obj)
	Sets the conflicting object. Only used from NamingPolicyInputDialog.
void	setName (QObject *object, const QString &new_name)
	Function which sets the name of the object.
void	setProcessingCycleValidationChecks (NamingPolicyFilter::ValidationCheckFlags validation_checks)
	Sets the naming checks that must be done when this filter's observer context is busy with a processing cycle.
void	setUniquenessPolicy (NamingPolicyFilter::UniquenessPolicy naming_uniqueness_policy)
	Sets the naming uniqueness policy of this subject filter.
void	setUniquenessResolutionPolicy (NamingPolicyFilter::ResolutionPolicy naming_uniqueness_resolution_policy)
	Sets the naming uniqueness conflict policy used by this subject filter.
void	setValidationChecks (NamingPolicyFilter::ValidationCheckFlags validation_checks)
	Sets the naming checks that must be done when this filter's observer context is not busy with a processing cycle.
void	setValidator (QValidator *valid_naming_validator)
	Function to set the validator used to validate names.
void	setValidityResolutionPolicy (NamingPolicyFilter::ResolutionPolicy naming_validity_resolution_policy)
	Sets the naming validity conflict policy used by this subject filter.
void	startValidationCycle ()
	Function which starts a new naming validation cycle.
ExportModeFlags	supportedFormats () const
	Provides information about the export format(s) supported by your implementation of IExportable.
NamingPolicyFilter::UniquenessPolicy	uniquenessNamingPolicy () const
	Gets the naming uniqueness policy used by this subject filter.
NamingPolicyFilter::ResolutionPolicy	uniquenessResolutionPolicy () const
	Gets the naming uniqueness conflict policy used by this subject filter.
NamingPolicyFilter::ValidationCheckFlags	validationChecks () const
	Gets the naming checks that must be done when this filter's observer context is not busy with a processing cycle.
NamingPolicyFilter::ResolutionPolicy	validityResolutionPolicy () const
	Gets the naming validity conflict policy used by this subject filter.
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 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.
Observer *	observerContext () const
	Returns the observer context that this subject filter is attached to.
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.

Static Public Member Functions
static QString	resolutionPolicyToString (ResolutionPolicy resolution_policy)
	Function which returns a string associated with a specific ResolutionPolicy.
static ResolutionPolicy	stringToResolutionPolicy (const QString &resolution_policy_string)
	Function which returns the ResolutionPolicy associated with a string.
static UniquenessPolicy	stringToUniquenessPolicy (const QString &uniqueness_policy_string)
	Function which returns the UniquenessPolicy associated with a string.
static ValidationCheckFlags	stringToValidationCheckFlags (const QString &validation_checks)
	Function which returns the ValidationCheckFlags associated with a string.
static QString	uniquenessPolicyToString (UniquenessPolicy uniqueness_policy)
	Function which returns a string associated with a specific UniquenessPolicy.
static QString	validationCheckFlagsToString (ValidationCheckFlags validation_checks)
	Function which returns a string associated with a specific ValidationCheckFlags.

Protected Member Functions
void	assignNewNameManager (QObject *obj)
	Attempt to assign a new name manager to the object, other than this filter.
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.
bool	isObjectNameDirty (QObject *obj) const
	Check if the property actually changed during monitoredPropertyChanged() function call, thus check objectName() against the qti_prop_NAME property.
virtual bool	validateNamePropertyChange (QObject obj, const char property_name)
	Validates if `property_name` is a valid name for `obj` in this context.

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

The NamingPolicyFilter class is an implementation of AbstractSubjectFilter which allows control over naming of objects within the context of an Observer.

The NamingPolicyFilter class is usefull when you need to control the names of subjects within the context of an Observer. Currently NamingPolicyFilter allows control over the validity and uniqueness of a names within the context of an Observer set using setObserverContext().

Names are checked against the following criteria:

Validity of the name, defined through a QValidator set through setValidator().
Uniqueness of names, controlled through setUniquenessPolicy().

To install a NamingPolicyFilter on an Observer is easy:

Observer* obs = new Observer;
NamingPolicyFilter* naming_filter = new NamingPolicyFilter;
naming_filter->setUniquenessPolicy(NamingPolicyFilter::ProhibitDuplicateNames);
naming_filter->setValidityResolutionPolicy(NamingPolicyFilter::PromptUser);
naming_filter->setUniquenessResolutionPolicy(NamingPolicyFilter::Reject);
obs->installSubjectFilter(naming_filter);

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

TreeNode* tree_node = new TreeNode;

NamingPolicyFilter* naming_filter = tree_node->enableNamingControl(ObserverHints::ReadOnlyNames,NamingPolicyFilter::ProhibitDuplicateNames);

Validity Of Names

The validity of a name is determined by a QValdiator which is set using setValidator(). To get the current validator use getValidator(). Valid names are those which return QValidator::Acceptable when validated using the validator. By default the NamingPolicySubject filter validates names using a QRegExpValidator constructed as follows:

const QRegExp default_expression("\\.{1,200}",Qt::CaseInsensitive);

QRegExpValidator* default_validator = new QRegExpValidator(default_expression,0);

Uniqueness Of Names

The uniqueness of names are determined by comparing the names of subjects using QString's compare (overloaded ==) functionality, thus comparisons are case sensitive. The uniqueness of names are controlled by the UniquenessPolicy of the subject filter. This can be accessed using setUniquenessPolicy() and uniquenessPolicy().

Once the NamingPolicyFilter is set up the way you need it, it will add a single shared property (see Qtilities::Core::SharedProperty) to subjects attached to it's observer context. The name of this property is defined in code using the Qtilities::Core::Properties::qti_prop_NAME constant.

This dynamic property will be sync'ed with objectName() at all times. Since there is no way to know when setObjectName() is called on a QObject, a dynamic property needed to be added to manage the subject's name. Whenever you update this shared property it will be evaluated by the subject filter which will make sure the new name follows the validity of the filter's validator as well as the UniquenessPolicy of the filter. When a subject is attached to multiple contexts in which names are managed by NamingPolicyFilter objects, the first context to which it was attached will become its name manager. The name manager context will use the qti_prop_NAME property and all contexts (with naming policy filters) to which the subject is attached after being attached to the name manager will use Qtilities::Core::Properties::qti_prop_ALIAS_MAP to store aliases for the object in those contexts. The name of a subject in a context can be found using the Qtilities::Core::Observer::subjectNameInContext() function.

The diagram below shows a QObject which is observed by a number of observers with different, or no naming policy filters installed.

Naming Policy Filter Overview

Subject names are evaulated during attachment to the filter's observer context and when changing the name properties discussed above. Evaluation is done using the evaluateName() function which returns the validity of the name using a value defined by ValidityCheckResult. You can control how conflicting names are handled by setting the uniqueness resolution policy and the validity resolution policy of the subject filter. Access functions for these policies are setUniquenessResolutionPolicy(), uniquenessResolutionPolicy() setValidityResolutionPolicy() and validityResolutionPolicy(). Possible values for these policies are defined using ResolutionPolicy.

When isExportable() is true the parameters of the filter will be exported with its Observer context when the observer is exported. Note that when streaming naming policy filter objects, custom validators will not be streamed at present. Thus the default validator will be used when constructing the naming policy filter again in the future.

Displayed Names

By default Observer models display the names of subjects provided by qti_prop_NAME or qti_prop_ALIAS_MAP depending on who the name manager is. This name is also used during validation and uniqueness checking. In some cases it is required to display a different name to the user and for those cases the Qtilities::Core::Properties::qti_prop_DISPLAYED_ALIAS_MAP property can be used. An example where this is usefull is Qtilities::CoreGui::TreeFileItem which allows you to show different parts of a file path to the user. However in the background the qti_prop_NAME still reffers to the full path, even though only the name is displayed for example, and the naming policy filters will still use the qti_prop_NAME to check for duplicates etc.

Changing Subject Names

It is important to understand how to change the name of an object when using NamingPolicyFilter. An example of how to change the name on an object is shown below:

// We need to check if qti_prop_NAME exists first:
if (ObjectManager::propertyExists(obj,qti_prop_NAME)) {
    SharedProperty new_subject_name_property(qti_prop_NAME,QVariant("New Name"));
    ObjectManager::setSharedProperty(obj,new_subject_name_property);
} else {
    // Handle cases where there is no naming policy filter:
    setObjectName("New Name");

In most cases its not neccessarry to know if the name was actually set or not (thus not rejected by the NamingPolicyFilter). In other cases you might want to know if the property was set successfully and this can be done by connecting a slot to the subjectNameChanged() signal, or through an event filter on the object for which the name must be changed. If the property change in rejected by the NamingPolicyFilter the QDynamicPropertyChangeEvent event will be filtered by the observer context. Thus you can see if the event was filtered or not.

Another way is to listen for Qtilities::Core::QtilitiesPropertyChangeEvent events on the object (this is not enabled by default on observers). Whenever a property was successfully changed the observer context will post a QtilitiesPropertyChangeEvent event to the object. Thus if you get the event the name was changed successfully. For more information on how this see Monitoring property changes and changing properties.

Subclassing NamingPolicyFilter

It is possible to customize naming policy filters by subclassing NamingPolicyFilter. The needed functions are virtual and allows you to customize the behaviour. Thus you can for example provide a custom naming policy filter dialog which is presented to the user if you decide to use that resolution policy.

The following virtual functions can be subclassed to get the described behaviour:

evaluateName() : Evaluates a name in the context. By default evaluation is done as described in Validity Of Names and Uniqueness Of Names. Reimplement this function in order to customize the way the evaluation is done.
getEvaluationName() : Returns the name to be evaluated for a given object.
generateValidName() : Generates valid names when AutoRename is used as the ResolutionPolicy and when the standard NamingPolicyInputDialog is used the auto-rename button is clicked. Reimplement this function in order to customize the generation of valid names.
validateNamePropertyChange() : Defines the behaviour when name properties change on objects.
constructUserDialog() : Constructs the dialog presented ot the user when using PromptUser resolution policies. To present your own widget, overload this function and construct your own widget.

See also:: NamingPolicyInputDialog

Member Enumeration Documentation

enum Qtilities::CoreGui::NamingPolicyFilter::ResolutionPolicy

Policy to control how invalid or duplicate names should be handled.

setUniquenessPolicy(), uniquenessNamingPolicy(), setUniquenessResolutionPolicy(), uniquenessResolutionPolicy(), setValidityResolutionPolicy(), validityResolutionPolicy()

Enumerator:

AutoRename	Automatically rename new names. See also: generateValidName()
PromptUser	Bring up a Qtilities::CoreGui::NamingPolicyInputDialog widget from which the user can decide what to do. Note: Important: When this NamingPolicyFilter is installed on an Observer which does not live in the main GUI thread, this resolution policy should not be used. If it is used it will attempt to construct a widget in a non-GUI thread and it will crash.
Replace	Replace the conflicting object with the current object. This option will only work when the conflicting object is only observed in the context to which the naming policy filter is attached. If this is the case, the replacement operation will delete the conflicting object and attach the new object to the observer. Note: The Replace policy is only usable when duplicate names are encountered, not invalid names. For invalid names Reject will be used.
Reject	Reject unacceptable names.

enum Qtilities::CoreGui::NamingPolicyFilter::UniquenessPolicy

Policy to control uniqueness of subject names in the observer context in which this filter is installed.

See also:: setUniquenessPolicy(), uniquenessNamingPolicy()

Enumerator:

AllowDuplicateNames	Allow duplicate names.
ProhibitDuplicateNames	Prohibit duplicate names (checking for duplicate names done in a case in-sensitive way).
ProhibitDuplicateNamesCaseSensitive	Prohibit duplicate names (checking for duplicate names done in a case sensitive way).

enum Qtilities::CoreGui::NamingPolicyFilter::ValidationCheck

Policy to control which checks must be performed by the filter.

setProcessingCycleValidationChecks(), processingCycleValidationChecks(), setValidationChecks(), validationChecks()

Enumerator:

NoChecks	Automatically rename new names. See also: generateValidName()
Validity	Checks the validity of subject names. See also: uniquenessNamingPolicy()
Uniqueness	Checks the uniqueness of subject names. See also: validityResolutionPolicy()
AllChecks	All checks are performed.

enum Qtilities::CoreGui::NamingPolicyFilter::ValidityCheckResult

Enumeration defining the possible outcames of name evaluation operations.

See also:: evaluateName()

Enumerator:

Acceptable

The name is acceptable.

Duplicate

A duplicate name exists.

Invalid

The name is invalid in this context.

See also:: setValidator(), getValidator().

Member Function Documentation

void Qtilities::CoreGui::NamingPolicyFilter::endValidationCycle ( )

Function which ends a naming validation cycle.

Ends a validation cycle started with startValidationCycle(). If no cycle was started this function does nothing.

Qtilities::CoreGui::AbstractSubjectFilter::EvaluationResult Qtilities::CoreGui::NamingPolicyFilter::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::CoreGui::NamingPolicyFilter::NameValidity Qtilities::CoreGui::NamingPolicyFilter::evaluateName	(	const QString &	name,
		QObject *	object = `0`
	)		const

virtual

Evaluates a name in the observer context in which this subject filter is installed.

Parameters:

name	The name to validate in observerContext().
object	The current object. When null (by default) the context is checked for `name` and if it exists, Duplicate is returned. If object is not null, the context is checked for instances of the name except for the current object.

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

void Qtilities::CoreGui::NamingPolicyFilter::finalizeAttachment	(	QObject *	obj,
		bool	attachment_successful,
		bool	import_cycle = `false`
	)

virtual

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

void Qtilities::CoreGui::NamingPolicyFilter::finalizeDetachment	(	QObject *	obj,
		bool	detachment_successful,
		bool	subject_deleted = `false`
	)

virtual

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

QString Qtilities::CoreGui::NamingPolicyFilter::generateValidName	(	QString	input_name = `QString()`,
		bool	force_change = `false`
	)

virtual

Attempt to generate a valid name in the context from the given input_name.

The valid name generation attempts the following in the order shown.

When invalid:

Attempt to fix the string using the QRegExpValidator::fixup() function
Go on to the steps shown below.

When invalid and unique: (fixup worked)

Append the value of a counter to the name

When valid and duplicate: (fixup failed)

Attempt to remove whitespaces
Try a simple string: new_object
Try a simple string without an underscore: NewObject

This function takes the UniquenessPolicy of the subject filter into account when generating a valid name.

Returns:: A valid QString value. If QString is returned empty the function could not succeed in generating a valid name.

virtual QString Qtilities::CoreGui::NamingPolicyFilter::getEvaluationName ( QObject * object ) const

inlinevirtual

Gets the name to be used during evaluateName() for a specific object.

By default an empty QString is returned and NamingPolicyFilter gets the correct name depending where this function is called.

Parameters:

object The object for which the evaluation name must be obtained.

QString Qtilities::CoreGui::NamingPolicyFilter::getName ( QObject * object )

Function which gets the name of the object.

This function checks if the subject filter is the name manager of the object, in that case it uses qti_prop_NAME. If not, it uses qti_prop_ALIAS_MAP with the subject filter's observer context ID.

bool Qtilities::CoreGui::NamingPolicyFilter::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::CoreGui::NamingPolicyFilter::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::CoreGui::NamingPolicyFilter::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.

bool Qtilities::CoreGui::NamingPolicyFilter::initializeAttachment	(	QObject *	obj,
		QString *	rejectMsg = `0`,
		bool	import_cycle = `false`
	)

virtual

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

Qtilities::Core::InstanceFactoryInfo Qtilities::CoreGui::NamingPolicyFilter::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.

void Qtilities::CoreGui::NamingPolicyFilter::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::CoreGui::NamingPolicyFilter::monitoredProperties ( ) const

virtual

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

const QObject* Qtilities::CoreGui::NamingPolicyFilter::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::CoreGui::NamingPolicyFilter::ValidationCheckFlags Qtilities::CoreGui::NamingPolicyFilter::processingCycleValidationChecks ( ) const

Gets the naming checks that must be done when this filter's observer context is busy with a processing cycle.

The default is AllChecks.

QStringList Qtilities::CoreGui::NamingPolicyFilter::reservedProperties ( ) const

virtual

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

void Qtilities::CoreGui::NamingPolicyFilter::setName	(	QObject *	object,
		const QString &	new_name
	)

Function which sets the name of the object.

This function checks if the subject filter is the name manager of the object, in that case it sets qti_prop_NAME. If not, it sets qti_prop_ALIAS_MAP with the subject filter's observer context ID.

void Qtilities::CoreGui::NamingPolicyFilter::setUniquenessPolicy ( NamingPolicyFilter::UniquenessPolicy naming_uniqueness_policy )

Sets the naming uniqueness policy of this subject filter.

Note:: The uniqueness policy can only be changed when no subjects are attached to the filter's observer context.

void Qtilities::CoreGui::NamingPolicyFilter::setValidator ( QValidator * valid_naming_validator )

Function to set the validator used to validate names.

Note:: The validator can only be set when the context to which this filter is attached to has no objects attached to it.; NamingPolicyFilter takes ownership of the new validator after this call.

void Qtilities::CoreGui::NamingPolicyFilter::startValidationCycle ( )

Function which starts a new naming validation cycle.

A naming validation cycle reffers to a bunch of validations that must happen. For example if you are parsing an input file which results in the attachment of many subjects to the observer context which this filter is validating, you create a validation cycle for this process.

Validation cycles allow the use of the "All in this cycle" option in the NamingPolicyInputDialog. When checked, you may choose to use one option for all subjects in this cycle and the user does not need to select an option for each file.

An cycle is ended by calling endValidationCycle(). If you call startValidationCycle() while a cycle is already active the function has no effect. Thus you don't have to match the number of startValidationCycle() calls with the equal number of endValidationCycle() calls.

void Qtilities::CoreGui::NamingPolicyFilter::subjectNameChanged	(	QObject *	obj,
		const QString &	old_name,
		const QString &	new_name
	)

signal

Signal which is emitted when the name of an object who's name is managed by this policy filter is changed.

Parameters:

obj	The object who's name changed.
old_name	The previous name, before it was changed.
new_name	The new name that was changed.

This function was added in Qtilities v1.2.

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

Qtilities::CoreGui::NamingPolicyFilter::UniquenessPolicy Qtilities::CoreGui::NamingPolicyFilter::uniquenessNamingPolicy ( ) const

Gets the naming uniqueness policy used by this subject filter.

The default is ProhibitDuplicateNames.

Qtilities::CoreGui::NamingPolicyFilter::ResolutionPolicy Qtilities::CoreGui::NamingPolicyFilter::uniquenessResolutionPolicy ( ) const

Gets the naming uniqueness conflict policy used by this subject filter.

The default is PromptUser.

bool Qtilities::CoreGui::NamingPolicyFilter::validateNamePropertyChange	(	QObject *	obj,
		const char *	property_name
	)

protectedvirtual

Validates if property_name is a valid name for obj in this context.

Note:: When you are loading a project and there is a chance that duplicate names might occur and the user changes it, you need to subclass NamingPolicyFilter and call PROJECT_MANAGER->markProjectAsChangedDuringLoad() in order for the project not to set your observer context as not modified.

Returns:: True if the changed name is allowed, false otherwise.

Qtilities::CoreGui::NamingPolicyFilter::ValidationCheckFlags Qtilities::CoreGui::NamingPolicyFilter::validationChecks ( ) const

Gets the naming checks that must be done when this filter's observer context is not busy with a processing cycle.

The default is AllChecks.

Qtilities::CoreGui::NamingPolicyFilter::ResolutionPolicy Qtilities::CoreGui::NamingPolicyFilter::validityResolutionPolicy ( ) const

Gets the naming validity conflict policy used by this subject filter.

The default is PromptUser.

Public Types

Signals

Public Member Functions

Static Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Validity Of Names

Uniqueness Of Names

Displayed Names

Changing Subject Names

Subclassing NamingPolicyFilter

Member Enumeration Documentation

Member Function Documentation