IPreflightExpansionHelper Class Reference

#include <IPreflightExpansionHelper.h>

Public Types
enum	{   kAddedChildToDatabase = (1L<<1), kChildNotRequired = (1L<<2), kChildTBDLinkRemoved = (1L<<3), kNewLinkAdded = (1L<<4),   kDuplicateLink = (1L<<5), kNoChangeBecauseParentNotFound = (1L<<6), kAddedChildToExpansionList = (1L<<8), kAddedChildToVisitList = (1L<<9),   kInternalError = (1L<<30) }
typedef uint32	AddResult

Public Member Functions
	IPreflightExpansionHelper ()
virtual	~IPreflightExpansionHelper ()
virtual IPreflightProcess *	QueryProcess () const =0
virtual const IPreflightOptions *	QueryPreflightOptions () const =0
virtual const PreflightObjectID &	GetParentObjectID () const =0
virtual IPreflightObject *	GetParentObject () const =0
virtual IDataBase *	GetDataBase () const =0
virtual bool	ShouldAdd (PreflightObjectClassID childClassID) const =0
virtual bool	ExistsInDatabase (const PreflightObjectID &objID) const =0
virtual AddResult	AddChild (const PreflightObjectID &childID, bool asReference=kFalse)=0
virtual AddResult	AddObjectWithTBDParent (const PreflightObjectID &childID)=0
virtual void	ExpandAgainLater (const IPreflightObjectModelService *iService, uint32 timeDelay_ms=0)=0

Detailed Description

This class works with the preflight object model services. These services provide the structure (the preflight DOM) that preflight rules visit. In order to create the DOM the preflight engine starts at the doucment node and asks the object model services to expand the children of each node, recursively.

This class provides a number of services when an object model service is called back via Expand(). Typically a service checks ShouldExpand() if it expands more than one child class for a given parent class (the Expand() call will not be made if the service does not purport to declare children that are interesting at the moment). It then calls AddChild for each child it knows about. It can also use the parent-child form of AddChild if it wants to expand an entire tree.

See Also

IPreflightObjectModelService

IPreflightOptions

Member Enumeration Documentation

anonymous enum

Results codes for the AddChild methos.

Enumerator
kAddedChildToDatabase	Child wasn't in the database.
kChildNotRequired	Child not added (and no link created) because the child (and any potential children of it) are not required by the current set of rules.
kChildTBDLinkRemoved	Child was removed as a TBD from another parent because a "true" parent was specified.
kNewLinkAdded	New link (either ownership, reference, or TBD, depending on call) added from parent to child.
kDuplicateLink	There's already a link between the parent and child objects, so a new one wasn't added.
kNoChangeBecauseParentNotFound	Parent not found in the database (this can only happen for the parent/child form of AddChild). You'll need to anchor the parent to something that already exists in the database.
kAddedChildToExpansionList	The child was also added to the list of children to be expanded later.
kAddedChildToVisitList	The child was also added to the list of children to be visited later.
kInternalError	Something bad happened.

Constructor & Destructor Documentation

IPreflightExpansionHelper::IPreflightExpansionHelper ( )

inline

Constructor.

virtual IPreflightExpansionHelper::~IPreflightExpansionHelper ( )

inlinevirtual

Virtual destructor.

Member Function Documentation

virtual AddResult IPreflightExpansionHelper::AddChild ( const PreflightObjectID &  childID, bool  asReference = kFalse  )

pure virtual

Adds a child under the parent object.

Parameters

childID	IN The child object.
asReference	IN True if the child is owned by the parent; false if this is simply a reference to the child object. One way to think of it is this: if you delete the parent, is the child implicitly deleted too? If so, it's ownership; if not, it's a reference. For example, a document owns its swatches; page items have references to those swatches.

Returns

A result code indicating what change, if any, was made in the database as a result.

virtual AddResult IPreflightExpansionHelper::AddObjectWithTBDParent ( const PreflightObjectID &  childID )

pure virtual

Adds an object to the database as a "owner/parent to be determined" object. In simple expansion cases the parent-child relationship is unambiguous and the child is always determined by expanding the parent. But in more complex expansion cases you might discover children before the parents have been expanded; or it may be that it's much more practical to work from children to parents and so you need to create the parent, bind the object as a child of the parent, and then later discover the parents of the parents. This method allows you to put the object in the database with a "TBD" link from the specified anchor to the parent. Once a "true" parent child relationship is established later the TBD link is removed.

Note

You can call this even if the object is in the database already; in that case this method won't have any side effects. This saves you the trouble of calling ExistsInDatabase before calling this.

Parameters

childID

IN The child object.

Returns

A result code indicating what change, if any, was made in the database as a result.

virtual bool IPreflightExpansionHelper::ExistsInDatabase ( const PreflightObjectID &  objID ) const

pure virtual

Given an object ID, returns whether it exists yet in the database.

Parameters

objID

IN The object to look for.

Returns

True if it exists; false if not.

virtual void IPreflightExpansionHelper::ExpandAgainLater ( const IPreflightObjectModelService *  iService, uint32  timeDelay_ms = 0  )

pure virtual

Call this method if your service was unable to expand the node in a reasonable amount of time or was interrupted. The node and service are placed in a queue that will be called back once all othe other expansion is complete, or 'timeDelay_ms' milliseconds have elapsed, whichever comes last.

Currently this is used by ID native the artwork OM service but can be used by any service that may take some time to complete and can be cancelled by the user. Or if you do some work in a thread you can use this to be called back later at some interval to see if the work is complete.

Parameters

iService	IN The object model service to call back; typically just 'this'.
timeDelay_ms	The number of milliseconds (minimum) to wait before retrying the expansion. If zero the expansion will be retried as soon as all of the other (non-delayed) expansion is complete.

virtual IDataBase* IPreflightExpansionHelper::GetDataBase ( ) const

pure virtual

Get the database of the parent object. This is the same result as ::GetDataBase(GetParentObject()).

Returns

The NON-refcounted database of the parent.

virtual IPreflightObject* IPreflightExpansionHelper::GetParentObject ( ) const

pure virtual

Get the parent object, ie the one whose children should be enumerated.

Note

You can expand as far down as is convenient via AddChild(parent, child).

Returns

The IPreflightObject interface of the current parent. This is NOT refcounted (thus 'Get').

virtual const PreflightObjectID& IPreflightExpansionHelper::GetParentObjectID ( ) const

pure virtual

Get the parent object, ie the one whose children should be enumerated.

Note

You can expand as far down as is convenient via AddChild(parent, child).

Returns

The object ID of the current parent.

virtual const IPreflightOptions* IPreflightExpansionHelper::QueryPreflightOptions ( ) const

pure virtual

Returns

the preflight options associated with the process.

virtual IPreflightProcess* IPreflightExpansionHelper::QueryProcess ( ) const

pure virtual

Returns

the preflight process this expansion is associated with.

virtual bool IPreflightExpansionHelper::ShouldAdd ( PreflightObjectClassID  childClassID ) const

pure virtual

Given an object class ID, returns whether to expand into children of that type.

Parameters

childClassID

IN The class you're wondering about.

Returns

True if you should add objects of this class; false if not.