All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Pages
Public Types | Public Slots | Signals | Public Member Functions | Static Public Member Functions | Protected Member Functions
Qtilities::Core::Observer Class Reference

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:
Inheritance graph
[legend]

List of all members.

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.
ObserverHintsdisplayHints () 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.
Observeroperator<< (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< QtilitiesCategorysubjectCategories () 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.
ObserverHintsuseDisplayHints ()
 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.
IExportableduplicate (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 ITaskexportTask () 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_tree_classification.jpg
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:

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

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().

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.

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.

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.

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.

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:
objThe object to be attached.
ownershipThe ownership that the observer should use to manage the object. The default is Observer::ManualOwnership.
rejectMsgWhen this function fails and rejectMsg will be populated with an rejection message when valid.
import_cycleIndicates 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:
objectsA list of objects which must be attached.
ownershipThe ownership that the observer should use to manage the object. The default is Observer::ManualOwnership.
import_cycleIndicates 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.
rejectMsgWhen 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:
objThe object to be attached.
ownershipThe ownership that the observer should use to manage the object. The default is Observer::ManualOwnership.
rejectMsgWhen this function fails and rejectMsg will be populated with an rejection message when valid.
import_cycleIndicates 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:
objThe object to test attachment of.
rejectMsgRejection message. If the attachment cannot be done, thus it returns Observer::Rejected, you can get the reason through this error message.
ownershipThis parameter allows you to specify the ownership to use during attachment. By default Observer::ManualOwnership.
silentWhen 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_objectThe mime data object to test attachment of.
rejectMsgRejection message. If the attachment cannot be done, thus it returns Observer::Rejected, you can get the reason through this error message.
silentWhen 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:
objThe object to test detachment of.
rejectMsgRejection 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:
observerWhen 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_nameSpecifies that only items inheriting the specified base class must be deleted.
refresh_viewsIndicates 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:
objThe object to be detached.
rejectMsgWhen 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:
objectsA list of objects which must be detached.
rejectMsgWhen 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:
broadcastIf 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:
streamA 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_selectionThe 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_nameThe name of the property which changed.
objectsThe 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_indicationSlots can use this indicator to know what change occurred.
objectsA 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_nameThe name of the property on which the change was filtered.
objectsThe 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:
forceWhen 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:
forceWhen 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_categoryThe category to rename.
new_categoryThe new name that must be given to the category.
match_exactlyWhen 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:
categoryOnly 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:

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:
objThe object for which the name must be fetched.
check_displayed_name_propertyIndicates if the qti_prop_DISPLAYED_ALIAS_MAP property must be checked.
validate_objectWhen 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:
toggleWhen 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:
toggleTrue 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_nameThe name of the base class of children you are looking for. By default, all children underneath this observer is returned.
limitWhen 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_idInternal 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()


Qtilities : Reference Documentation Back to top Copyright © 2009-2013, Jaco Naudé