IDigitalPublishingSetupProvider Class Reference

#include <IDigitalPublishingSetupProvider.h>

Inheritance diagram for IDigitalPublishingSetupProvider:

Classes
class	OverlayCreator

Public Types
enum	{ kDefaultIID = IID_IDIGITALPUBLISHINGSETUPPROVIDER }
enum	Orientation { kPortraitOrientation, kLandscapeOrientation, kInvalidOrientation = 0xffffffff }
enum	DrawPass {   kScrubberDrawPass, kAssetDrawPass, kThumbnailDrawPass, kTOCImageDrawPass,   kOverlayCollectionPass, kPDFGenerationPass, kInvalidDrawPass = 0xffffffff }
enum	DrawBehavior { kDrawBehaviorIncludeItem, kDrawBehaviorOmitItem, kDrawBehaviorAbortDrawing, kDrawBehaviorInvalidOption = 0xffffffff }

Public Member Functions
virtual ErrorCode	BeginFolioCreation ()=0
virtual void	EndFolioCreation (bool folioWasCreated)=0
virtual ErrorCode	BeginOverlayCollection ()=0
virtual void	EndOverlayCollection ()=0
virtual ErrorCode	BeginContentStack (IDocument const *doc, Orientation orientation, const MiniFolioOptions &folioOptions)=0
virtual ErrorCode	EndContentStack (IDocument const *doc, Orientation orientation)=0
virtual ErrorCode	BeginPage (IDocument const *doc, UIDRef const &page, uint32 index, OverlayCreator *overlayCreator)=0
virtual ErrorCode	EndPage (IDocument const *doc, UIDRef const &page, uint32 index, OverlayCreator *overlayCreator)=0
virtual ErrorCode	BeginDrawingPass (IDocument const *doc, UIDRef const &page, DrawPass pass)=0
virtual ErrorCode	EndDrawingPass (IDocument const *doc, UIDRef const &page, DrawPass pass)=0
virtual bool	GetShouldNotifyOnPageItemDraw (DrawPass pass) const =0
virtual DrawBehavior	HandlePageItemDraw (IPMUnknown const *thisThing, DrawPass pass, OverlayCreator *overlayCreator)=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

Simple C++ service to be implemented by anyone wishing to be notified as events occur during the creation of a digital publishing folio file. Implementors can use these notifications to control how the folio file is created, including how interactive overlay instances are created.

***NOTES:

Accessing the provider MUST be done using the new utility digpub::QueryIDigitalPublishingSetupProvider defined below because it determines which version of the provider interface to use: IDigitalPublishingSetupProvider or IDigitalPublishingSetupProvider2.

Usage example: ... InterfacePtr<IK2ServiceProvider> service(registry->QueryNthServiceProvider(kDigitalPublishingSetupService, i)); InterfacePtr<IDigitalPublishingSetupProvider> provider(digpub::QueryIDigitalPublishingSetupProvider(service)); ...

Member Enumeration Documentation

enum IDigitalPublishingSetupProvider::DrawBehavior

Options for controlling how page items should be drawn during content generation

enum IDigitalPublishingSetupProvider::DrawPass

Drawing passes. The folio generation code will make multiple passes over the content. This specifies which pass is being done.

enum IDigitalPublishingSetupProvider::Orientation

Orientation for a content stack

Member Function Documentation

virtual ErrorCode IDigitalPublishingSetupProvider::BeginContentStack ( IDocument const *  doc, Orientation  orientation, const MiniFolioOptions &  folioOptions  )

pure virtual

Notification that a content stack is about to be generated. These are generated from a source document in separate passes for portrait and landscape orientations.

Parameters

doc	The document representing the content stack
orientation	The orientation being generated
folioOptions	The options for this folio. This includes wide and narrow dimension for the folio, asset format and quality, smooth scrolling, ect.

See Also

MiniFolioOptions.h

Returns

kSuccess if the folio creation should continue, or an error code to abort it

virtual ErrorCode IDigitalPublishingSetupProvider::BeginDrawingPass ( IDocument const *  doc, UIDRef const &  page, DrawPass  pass  )

pure virtual

Notification that a drawing pass is about to begin. Note that this will occur within a BeginPage/EndPage block for asset and thumbnail passes but not for the scrubber pass.

Note: In current implementation, spreads are exported a page at a time. This will likely change in the future. When this occurs - and the options selected for folio generation indicate that we should generate stack pages from spreads instead of pages - the 'page' and 'index' parameters will point to the spread and spread index, rather than page and page index as they do now. For the kPDFGenerationPass, only one page per spread is supported, and the page parameter is a UIDRef to that page.

Parameters

doc	The document representing the content stack
page	Reference to the page or spread for the content stack page (see note above)
pass	The drawing pass that is about to begin

Returns

kSuccess if the folio creation should continue, or an error code to abort it

virtual ErrorCode IDigitalPublishingSetupProvider::BeginFolioCreation ( )

pure virtual

Notification that a folio is about to be created. Called prior to exporting any of the content stacks that make up the folio.

Returns

kSuccess if the folio creation should continue, or an error code to abort it

virtual ErrorCode IDigitalPublishingSetupProvider::BeginOverlayCollection ( )

pure virtual

Notification that overlay collection is about to occur. This is called when the system needs to determine the list of overlays outside the context of folio generation. For example, this will be called if the getAllOverlays scripting API is used. It will not be called during normal folio generation.

Returns

kSuccess if the overlay collection should continue, or an error code to abort it

virtual ErrorCode IDigitalPublishingSetupProvider::BeginPage ( IDocument const *  doc, UIDRef const &  page, uint32  index, OverlayCreator *  overlayCreator  )

pure virtual

Notification that a page in a content stack is about to be generated.

Note: In current implementation, spreads are exported a page at a time. This will likely change in the future. When this occurs - and the options selected for folio generation indicate that we should generate stack pages from spreads instead of pages - the 'page' and 'index' parameters will point to the spread and spread index, rather than page and page index as they do now. For the kPDFGenerationPass, only one page per spread is supported, and the page parameter is a UIDRef to that page.

Parameters

doc	The document representing the content stack
page	Reference to the page or spread for the content stack page (see note above)
index	Index of the page or spread, starting from zero
overlayCreator	An instance of an overlay creator that can be used to generate overlay instances for the page

Returns

kSuccess if the folio creation should continue, or an error code to abort it

virtual ErrorCode IDigitalPublishingSetupProvider::EndContentStack ( IDocument const *  doc, Orientation  orientation  )

pure virtual

Notification that generation of a content stack has completed.

Parameters

doc	The document representing the content stack
orientation	The orientation being generated

Returns

kSuccess if the folio creation should continue, or an error code to abort it

virtual ErrorCode IDigitalPublishingSetupProvider::EndDrawingPass ( IDocument const *  doc, UIDRef const &  page, DrawPass  pass  )

pure virtual

Notification that a drawing pass has ended. Note that this will occur within a BeginPage/EndPage block for asset and thumbnail passes but not for the scrubber pass.

Note: In current implementation, spreads are exported a page at a time. This will likely change in the future. When this occurs - and the options selected for folio generation indicate that we should generate stack pages from spreads instead of pages - the 'page' and 'index' parameters will point to the spread and spread index, rather than page and page index as they do now. For the kPDFGenerationPass, only one page per spread is supported, and the page parameter is a UIDRef to that page.

Parameters

doc	The document representing the content stack
page	Reference to the page or spread for the content stack page (see note above)
pass	The drawing pass that is about to begin

Returns

kSuccess if the folio creation should continue, or an error code to abort it

virtual void IDigitalPublishingSetupProvider::EndFolioCreation ( bool  folioWasCreated )

pure virtual

Notification that folio creation has completed. This is called even if the folio creation encountered an error or was aborted by a setup provider.

Parameters

folioWasCreated

true if the folio was created, otherwise false

virtual void IDigitalPublishingSetupProvider::EndOverlayCollection ( )

pure virtual

Notification that overlay collection has completed. Like the matching BeginOverlayCollection call, this is only called when the system needs to determine the list of overlays outside the context of folio generation.

virtual ErrorCode IDigitalPublishingSetupProvider::EndPage ( IDocument const *  doc, UIDRef const &  page, uint32  index, OverlayCreator *  overlayCreator  )

pure virtual

Notification that a page in a content stack has been generated.

Note: In current implementation, spreads are exported a page at a time. This will likely change in the future. When this occurs - and the options selected for folio generation indicate that we should generate stack pages from spreads instead of pages - the 'page' and 'index' parameters will point to the spread and spread index, rather than page and page index as they do now. For the kPDFGenerationPass, only one page per spread is supported, and the page parameter is a UIDRef to that page.

Parameters

doc	The document representing the content stack
page	Reference to the page or spread for the content stack page (see note above)
index	Index of the page or spread, starting from zero
overlayCreator	An instance of an overlay creator that can be used to generate overlay instances for the page

Returns

kSuccess if the folio creation should continue, or an error code to abort it

virtual bool IDigitalPublishingSetupProvider::GetShouldNotifyOnPageItemDraw ( DrawPass  pass ) const

pure virtual

Called for each content stack page, after a call to BeginPage has occurred, but before any content generation has occurred. This allows the setup provider to hook into the drawing code and determine whether or not particular page items are drawn during content generation.

Returns

true if the set up provider should be notified as page items draw in the given pass

virtual DrawBehavior IDigitalPublishingSetupProvider::HandlePageItemDraw ( IPMUnknown const *  thisThing, DrawPass  pass, OverlayCreator *  overlayCreator  )

pure virtual

Called if GetShouldNotifyOnPageItemDraw returned true for the current pass, indicating that the setup provider wants to hook into the page item drawing pipeline for assets.

Note: The overlayCreator parameter may be nil if overlay creation is not supported in the given pass. In current implementation, overlay creation is only supported in the kAssetDrawPass and kOverlayCollectionPass passes.

Parameters

thisThing	The page item being drawn. Use ::GetUIDRef(pageitem) to get the UIDRef this page item. Note that for text, this may not be an UID-based item, so UIDRef may be null.
pass	The current DrawPass.
overlayCreator	An instance of an overlay creator that can be used to generate overlay instances for the page, or nil if not supported

Returns

one of the DrawBehavior values indicating how to handle the page item