#include <ISubject.h>

Inheritance diagram for ISubject:

Public Types
enum	{ kDefaultIID = IID_ISUBJECT }

enum	AttachmentType { kRegularAttachment = 0, kLazyAttachment, kBothAttachments }

Public Member Functions
virtual bool16	IsAttached (IObserver *observer, const PMIID &interestedIn, const PMIID &asObserver=IID_IOBSERVER)=0

virtual void	AttachObserver (IObserver *observer, const PMIID &interestedIn, const PMIID &asObserver=IID_IOBSERVER)=0

virtual void	DetachObserver (IObserver *observer, const PMIID &interestedIn, const PMIID &asObserver=IID_IOBSERVER)=0

virtual void	Change (ClassID theChange, const PMIID &interestedIn=IID_IUNKNOWN, void *changedBy=nil)=0

virtual void	Change (ISubject originalSubject, ClassID theChange, const PMIID &interestedIn=IID_IUNKNOWN, void changedBy=nil)=0

virtual void	Mute (bool16 muteOn)=0

virtual bool16	IsMuted () const =0

virtual IChangeManager *	GetChangeManager () const =0

virtual void	ModelChange (ClassID theChange, const PMIID &interestedIn, void changedBy=nil, LazyNotificationData data=nil)=0

virtual void	ModelChange (ISubject originalSubject, ClassID theChange, const PMIID &interestedIn, void changedBy=nil, LazyNotificationData *data=nil)=0

virtual void	ModelChange (IDataBase model, ClassID theChange, const PMIID &interestedIn, void changedBy=nil, LazyNotificationData *data=nil)=0

virtual bool16	IsAttached (AttachmentType attachType, IObserver *observer, const PMIID &interestedIn, const PMIID &asObserver)=0

virtual void	AttachObserver (AttachmentType attachType, IObserver *observer, const PMIID &interestedIn, const PMIID &asObserver)=0

virtual void	DetachObserver (AttachmentType attachType, IObserver *observer, const PMIID &interestedIn, const PMIID &asObserver)=0

Public Member Functions inherited from IPMUnknown
virtual IPMUnknown *	QueryInterface (PMIID interfaceID) const =0

virtual void	AddRef () const =0

virtual void	Release () const =0

Detailed Description

This interface provides a notification mechanism for objects that need to be informed

of changes made to another object; the object being changed is known as the subject, the object being notified is known as the observer (see IObserver). When an object is modified, its ISubject::ModelChange or ISubject::Change method is called to notify attached observers. There are two kinds of notification, regular notification and lazy notification.

Regular notification is initiated by calling ISubject::ModelChange or ISubject::Change. This causes IObserver::Update methods to be called for observers that are attached to this subject using regular attachment. These observers are called within the scope of change method.

Lazy notification is initiated by calling ISubject::ModelChange. In addition to the regular notification described above this also causes IObserver::LazyUpdate methods to be called for observers that are attached to this subject using lazy attachment. These observers are not called within the scope of the ISubject::ModelChange method. Instead, a message is queued and these observers are called later on, when the application is idle.

Changes to objects which persist in InDesign databases that support undo must be notified using ISubject::ModelChange. For example, if an object in an InDesign document (kDocBoss) is modified, then ISubject::ModelChange must be called to notify observers. Changes to objects stored in InDesign databases that don't support undo, or to objects that are not persistent, must be notified using ISubject::Change. For example, if a widget object changes state, then ISubject::Change is called to notify observers.

Consider a typical notification use case for a change to an object stored in an InDesign database that supports undo. A command (ICommand) modifies the object when its Command::Do method is called. When the Command::DoNotify method is called it calls ISubject::ModelChange which calls observers attached to the object using regular attachment via their IObserver::Update method (regular notification). Additionally, the ISubject::ModelChange method queues a message so that observers attached to the subject using lazy attachment get called later on when the application is idle via their IObserver::LazyUpdate method (lazy notification). Note:

If the object being modified is persists in an InDesign database that supports undo then ISubject::ModelChange must be used to notify observers of the change.
Lazy notification is also broadcast on undo or redo, therefore, observers must use lazy attachment in order to be called on undo or redo. On subsequent undo or redo of the change the IObserver::LazyUpdate method gets called. Note that the IObserver::Update method is not called on undo or redo.
Lazy notification is the most efficient form of notification to use for updating objects in the user interface. IObserver::LazyUpdate gets called once per transaction on the InDesign database since the notification is broadcast after all the changes have been made and the transaction is complete. Contrastingly, IObserver::Update may get called several times within a transaction, since the notification is broadcast immediately after the change is made.

See Also: IObserver

Member Enumeration Documentation

enum ISubject::AttachmentType

Type of attachment.
Enumerator
kRegularAttachment
For observers that want regular notification via IObserver::Update.
kLazyAttachment
For observers that want lazy notification via IObserver::LazyUpdate.
kBothAttachments
For observers that want both regular and lazy notification.

Member Function Documentation

virtual void ISubject::AttachObserver	(	IObserver *	observer,
		const PMIID &	interestedIn,
		const PMIID &	asObserver = `IID_IOBSERVER`
	)

pure virtual

Attach an observer that uses regular attachment to this subject.

Note: this method is equivalent to calling ISubject::AttachObserver(AttachmentType, IObserver*, const PMIID& interestedIn, const PMIID& asObserver) specifying an attachment type of kRegularAttachment.

Parameters

observer	the observer to be attached
interestedIn	may be used to narrow the scope of interested changes
asObserver	must be used if the observer has an interface id that is different than IID_IOBSERVER

Implemented in CSubject.

virtual void ISubject::AttachObserver	(	AttachmentType	attachType,
		IObserver *	observer,
		const PMIID &	interestedIn,
		const PMIID &	asObserver
	)

pure virtual

Attach the observer using the given attachment type (regular, lazy or both) to this subject.

Parameters

attachType	specifies the type of attachment the observer uses and controls the type of notification it receives, for example regular notification or lazy notification.
observer	is the observer to be attached
interestedIn	specifies the scope of interested changes; for example if you are interested in a specific interface on this subject pass the interface id here.
asObserver	the interface id of the observer

Implemented in CSubject.

virtual void ISubject::Change	(	ClassID	theChange,
		const PMIID &	interestedIn = `IID_IUNKNOWN`,
		void *	changedBy = `nil`
	)

pure virtual

Notify observers that are attached to this subject via regular attachment that the object this subject is part of has been changed.

This method iterates over the observers that are attached to this subject using regular attachment and calls their IObserver::Update method (regular notification).

Parameters

theChange	is the actual change, often the ClassID of a command
interestedIn	specifies the interface of the object that was modified
changedBy	is generic pointer to the object that caused the change, usually a pointer to a command object

See Also: IObserver::Update

Implemented in CSubject.

virtual void ISubject::Change	(	ISubject *	originalSubject,
		ClassID	theChange,
		const PMIID &	interestedIn = `IID_IUNKNOWN`,
		void *	changedBy = `nil`
	)

pure virtual

Notify observers that are attached to this subject via regular attachment that the object this subject is part of has been changed.

This method iterates over the observers that are attached to this subject using regular attachment and calls their IObserver::Update method (regular notification).

The difference between this method and the other Change method is that the object given by the originalSubject parameter is passed into IObserver::Update as the subject that was changed, rather than this subject.

Parameters

originalSubject	is the original subject of the object that was changed
theChange	is the actual change, often the ClassID of a command
interestedIn	identifies the interface of the object that was modified
changedBy	is generic pointer to the object that caused the change, usually a pointer to a command object

See Also: IObserver::Update

Implemented in CSubject.

virtual void ISubject::DetachObserver	(	IObserver *	observer,
		const PMIID &	interestedIn,
		const PMIID &	asObserver = `IID_IOBSERVER`
	)

pure virtual

Detach an observer that uses regular attachment from this subject.

Note: this method is equivalent to calling ISubject::DetachObserver(AttachmentType, IObserver*, const PMIID& interestedIn, const PMIID& asObserver) specifying an attachment type of kRegularAttachment.

Parameters

observer	the observer to be detached
interestedIn	identifies the interface in this subject that the observer is attached to
asObserver	is the interface id of the observer

Implemented in CSubject.

virtual void ISubject::DetachObserver	(	AttachmentType	attachType,
		IObserver *	observer,
		const PMIID &	interestedIn,
		const PMIID &	asObserver
	)

pure virtual

Detach the observer using the given attachment type (regular, lazy or both) from this subject.

Parameters

attachType	specifies the type of attachment
observer	is the observer to be detached
interestedIn	identifies the interface in this subject that the observer is attached to
asObserver	the interface id of the observer

Implemented in CSubject.

virtual IChangeManager* ISubject::GetChangeManager ( ) const

pure virtual

Access the internal implementation of the notification mechanism.

Returns: the change manager interface pointer

Implemented in CSubject.

virtual bool16 ISubject::IsAttached	(	IObserver *	observer,
		const PMIID &	interestedIn,
		const PMIID &	asObserver = `IID_IOBSERVER`
	)

pure virtual

Check whether an observer that uses regular attachment is attached to this subject.

Note: this method is equivalent to calling ISubject::IsAttached(AttachmentType, IObserver*, const PMIID& interestedIn, const PMIID& asObserver) specifying and attachment type of kRegularAttachment.

Parameters

observer	the observer to be checked
interestedIn	identifies the interface in this subject that the observer is attached to
asObserver	the interface id of the observer

Returns: kTrue if the specified observer has been attached

Implemented in CSubject.

virtual bool16 ISubject::IsAttached	(	AttachmentType	attachType,
		IObserver *	observer,
		const PMIID &	interestedIn,
		const PMIID &	asObserver
	)

pure virtual

Check whether the observer is attached to this subject.

Parameters

attachType	specifies the type of attachment
observer	is the observer to be checked
interestedIn	identifies the interface in this subject that the observer is attached to
asObserver	the interface id of the observer

Returns: kTrue if the specified observer is attached, kFalse otherwise

Implemented in CSubject.

virtual bool16 ISubject::IsMuted ( ) const

pure virtual

Returns kTrue if this subject is muted.

Implemented in CSubject.

virtual void ISubject::ModelChange	(	ClassID	theChange,
		const PMIID &	interestedIn,
		void *	changedBy = `nil`,
		LazyNotificationData *	data = `nil`
	)

pure virtual

Notify observers that are attached to this subject via regular or lazy attachment that the object this subject is part of has been changed; this is the ModelChange method you probably want to call.

This method iterates over the observers that are attached to this subject using regular attachment and calls their IObserver::Update method (regular notification). Additionally, this method queues a message so that observers that are attached to the subject using lazy attachment get called later on when the application is idle via their IObserver::LazyUpdate method (lazy notification).

Precondition: this subject must be part of an InDesign database that supports undo

Parameters

theChange	is the actual change, often the ClassID of a command
interestedIn	identifies the interface of the object that was modified
changedBy	pointer to the object that caused the change, usually a pointer to a command object
data	contains additional information about the change, nil otherwise; see LazyNotificationData for documentation.

See Also: IObserver::Update; IObserver::LazyUpdate

Implemented in CSubject.

virtual void ISubject::ModelChange	(	ISubject *	originalSubject,
		ClassID	theChange,
		const PMIID &	interestedIn,
		void *	changedBy = `nil`,
		LazyNotificationData *	data = `nil`
	)

pure virtual

Notify observers that are attached to this subject via regular or lazy attachment that the object this subject is part of has been changed. Only use this method if you are sure you cannot use ISubject::ModelChange(ClassID, const PMIID&, void*, LazyNotificationData*).

This method passes the object given by the originalSubject parameter to IObserver::Update as the subject that was changed, rather than this subject. However, the originalSubject is not available when IObserver::LazyUpdate is called. When the lazy notification occurs, this subject is passed to IObserver::LazyUpdate. If you need access to originalSubject, do so in the IObserver::Update method.

Precondition: this subject must be part of an InDesign database that supports undo

Parameters

originalSubject	is the original subject of the object that was changed
theChange	is the actual change, often the ClassID of a command
interestedIn	identifies the interface of the object that was modified
changedBy	is generic pointer to the object that caused the change, usually a pointer to a command object
data	contains additional information about the change, nil otherwise; see LazyNotificationData for documentation.

See Also: IObserver::Update; IObserver::LazyUpdate

Implemented in CSubject.

virtual void ISubject::ModelChange	(	IDataBase *	model,
		ClassID	theChange,
		const PMIID &	interestedIn,
		void *	changedBy = `nil`,
		LazyNotificationData *	data = `nil`
	)

pure virtual

Use of this method is very rare. Call one of the other ModelChange methods unless you are sure this one is the right one for your use case. It is used to notify that a "snapshot view interface" has changed. For example, the layout widget uses this method to notify that ILayoutControlData has changed. ILayoutControlData is implemented as a "snapshot view interface" and change to this interface must get undone and redone as changes to the document being viewed get undone and redone.

Parameters

model	pointer to an InDesign database that supports undo
theChange	is the actual change, often the ClassID of a command
interestedIn	identifies the interface of the object that was modified
changedBy	is generic pointer to the object that caused the change, usually a pointer to a command object
data	contains additional information about the change, nil otherwise; see LazyNotificationData for documentation.

See Also: CREATE_VIEW_PMINTERFACE in "InterfaceFactory.h".; "Snapshot view interface" extension pattern documentation in the Programming Guide

Implemented in CSubject.

virtual void ISubject::Mute ( bool16 muteOn )

pure virtual

Mutes all messages from this object. Muting a subject allows you to make changes to the object without notifying its observers.

Parameters

muteOn if kTrue, turns mute on; if kFalse, turns mute off

Implemented in CSubject.

Enumerator
kRegularAttachment	For observers that want regular notification via IObserver::Update.
kLazyAttachment	For observers that want lazy notification via IObserver::LazyUpdate.
kBothAttachments	For observers that want both regular and lazy notification.

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

Member Function Documentation