SDKLayoutHelper Class Reference

#include <SDKLayoutHelper.h>

Public Member Functions
	SDKLayoutHelper ()
virtual	~SDKLayoutHelper ()
UIDRef	CreateDocument (const UIFlags uiFlags=K2::kFullUI, const PMReal &width=612, const PMReal &height=792, const int32 pages=1, const int32 pagesPerSpread=1, const int32 pageBinding=0)
UIDRef	OpenDocument (const IDFile &sysFile, UIFlags uiFlags=K2::kFullUI)
ErrorCode	CloseDocument (const UIDRef &documentUIDRef, bool16 saveOnClose=kFalse, UIFlags uiFlags=K2::kFullUI, bool8 allowCancel=kTrue, IDocFileHandler::CloseCmdMode cmdMode=IDocFileHandler::kSchedule)
ErrorCode	SaveDocumentAs (const UIDRef &documentUIDRef, const IDFile &sysFile, UIFlags uiFlags=kFullUI)
ErrorCode	OpenLayoutWindow (const UIDRef &documentUIDRef)
UIDRef	GetActiveSpreadLayerRef (const UIDRef &spreadUIDRef, bool16 wantGuideLayer=kFalse)
UIDRef	GetSpreadLayerRef (const UIDRef &spreadUIDRef, int32 documentLayerIndex=1, bool16 wantGuideLayer=kFalse)
PMRect	PageToSpread (const UIDRef &pageUIDRef, const PMRect &boundsInPageCoords)
UIDRef	PlaceFileInFrame (const IDFile &contentFile, const UIDRef &parentUIDRef, const PMRect &boundsInParentCoords, const UIFlags uiFlags=K2::kFullUI, const bool16 retainFormat=kTrue, const bool16 convertQuotes=kTrue, const bool16 applyCJKGrid=kFalse, const UID &uidPreview=kInvalidUID)
UIDRef	CreateRectangleFrame (const UIDRef &parentUIDRef, const PMRect &boundsInParentCoords)
UIDRef	CreateTextFrame (const UIDRef &parentUIDRef, const PMRect &boundsInParentCoords, int32 numberOfColumns=0, bool16 verticalFrame=kFalse, UIDRef *storyUIDRef=nil, bool16 isLeftToRight=kTrue)
UIDRef	CreateRectangleGraphic (const UIDRef &parentUIDRef, const PMRect &boundsInParentCoords)
UIDRef	CreateSplineGraphic (const UIDRef &parentUIDRef, const PMRect &boundsInParentCoords, const PMRect &boundsInInnerCoords, PMPathPointList &pathPointList, bool16 bClosedPath=kTrue)
UIDRef	GetGraphicFrameRef (const InterfacePtr< ITextFrameColumn > &textFrameColumn)
UIDRef	GetTextModelRef (const InterfacePtr< IGraphicFrameData > &graphicFrameData)

Detailed Description

Helper methods to perform basics of manipulating the layout content in a document.

All frame creation methods expect the bounds of the object to be created to be given in the bounds of the parent. Normally the parent will be a spread layer (ISpreadLayer), which implies the bounds are given in spread co-ordinates.

To assist in laying out content relative to the page origin (which is the top left corner of the page) a helper method SDKLayoutHelper::PageToSpread is provided. This will transform the bounds of a frame from page co-ordinates to spread co-ordinates ready to be passed to one of the frame creation methods like SDKLayoutHelper::CreateRectangleFrame.

See Also

IDocument

IPageList

ISpreadList

ISpread

ISpreadLayer

ILayerList

IDocumentLayer

IGraphicFrameData

IHierarchy

ITransform

IGeometry

Constructor & Destructor Documentation

SDKLayoutHelper::SDKLayoutHelper

(

)

Constructor.

SDKLayoutHelper::~SDKLayoutHelper ( )

virtual

Destructor.

Member Function Documentation

ErrorCode SDKLayoutHelper::CloseDocument	(	const UIDRef &	documentUIDRef,
		bool16	saveOnClose = kFalse,
		UIFlags	uiFlags = K2::kFullUI,
		bool8	allowCancel = kTrue,
		IDocFileHandler::CloseCmdMode	cmdMode = IDocFileHandler::kSchedule
	)

Close the document, with option to save.

Parameters

documentUIDRef	IN specifies the document to close
saveOnClose	kTrue if the document should be saved before closing, kFalse otherwise (default kFalse)
uiFlags	IN (default kFullUI)
allowCancel	IN kTrue if the user can cancel during the close, kFalse otherwise (default kTrue).
cmdMode	IN specifies if the close command should be processed immediately or scheduled (default kSchedule).

Returns

kSuccess on success, kFailure otherwise

UIDRef SDKLayoutHelper::CreateDocument	(	const UIFlags	uiFlags = K2::kFullUI,
		const PMReal &	width = 612,
		const PMReal &	height = 792,
		const int32	pages = 1,
		const int32	pagesPerSpread = 1,
		const int32	pageBinding = 0
	)

Create a document but without opening a layout view onto it.

Parameters

uiFlags	IN (default kFullUI)
width	IN width of page in points (default 612)
height	IN height of page in points (default 792)
pages	IN number of pages (default 1)
pagesPerSpread	IN number of pages per spread (default 1)
pageBinding	IN 0 for left to right page binding

Returns

UIDRef of document created, or UIDRef::gNull if creation failed; the returned UIDRef can be used to instantiate an IDocument

Postcondition

a document will be created and opened if the input parameters are valid, but without a layout view. Call SDKLayoutHelper::OpenLayoutWindow to obtain an layout view onto the document.

UIDRef SDKLayoutHelper::CreateRectangleFrame	(	const UIDRef &	parentUIDRef,
		const PMRect &	boundsInParentCoords
	)

Create a rectangular graphic frame of specified dimensions.

Parameters

parentUIDRef	IN reference to an IHierarchy item. Normally this is a kSpreadLayerBoss but could be another type of page item that will parent the new item.
boundsInParentCoords	IN bounds in parent's co-ordinate space. When the parent is a kSpreadLayerBoss this is spread co-ordinates.

Returns

UIDRef of frame(IGraphicFrameData) created, or UIDRef::gNull if failed.

UIDRef SDKLayoutHelper::CreateRectangleGraphic	(	const UIDRef &	parentUIDRef,
		const PMRect &	boundsInParentCoords
	)

Create a rectangle of specified dimensions.

Parameters

parentUIDRef	IN reference to an IHierarchy item. Normally this is a kSpreadLayerBoss but could be another type of page item that will parent the new item.
boundsInParentCoords	IN bounds in parent's co-ordinate space. When the parent is a kSpreadLayerBoss this is spread co-ordinates.

Returns

UIDRef of graphic created, from which an IGraphicFrameData interface can be instantiated, or UIDRef::gNull if failed.

UIDRef SDKLayoutHelper::CreateSplineGraphic	(	const UIDRef &	parentUIDRef,
		const PMRect &	boundsInParentCoords,
		const PMRect &	boundsInInnerCoords,
		PMPathPointList &	pathPointList,
		bool16	bClosedPath = kTrue
	)

Create a spline described by the given pathPointList translated and scaled to the bounds in the parent's co-ordinate space given by boundsInParentCoords.

Parameters

parentUIDRef	IN reference to an IHierarchy item. Normally this is a kSpreadLayerBoss but could be another type of page item that will parent the new item.
boundsInParentCoords	IN bounds in parent's co-ordinate space. When the parent is a kSpreadLayerBoss this is spread co-ordinates.
boundsInInnerCoords	IN bounds of the pathPointList in inner co-ordinates.
pathPointList	IN/OUT on input contains a list of PMPathPoint's in inner co-ordinates. On output these are transformed so the path is translated and scaled to the given boundsInParentCoords.
bClosedPath	kTrue if pathPointList describes a closed path, kFalse if open.

Returns

UIDRef of spline created, from which an IGraphicFrameData can be instantiated, or UIDRef::gNull if failed.

UIDRef SDKLayoutHelper::CreateTextFrame	(	const UIDRef &	parentUIDRef,
		const PMRect &	boundsInParentCoords,
		int32	numberOfColumns = 0,
		bool16	verticalFrame = kFalse,
		UIDRef *	storyUIDRef = nil,
		bool16	isLeftToRight = kTrue
	)

Create a text frame of specified dimensions.

Parameters

parentUIDRef	IN reference to an IHierarchy item. Normally this is a kSpreadLayerBoss but could be another type of page item that will parent the new item.
boundsInParentCoords	IN bounds in parent's co-ordinate space. When the parent is a kSpreadLayerBoss this is spread co-ordinates.
numberOfColumns	IN the number of columns (default 0 which means that the text frame options preference number of columns will be used).
verticalFrame	IN kTrue to make the text frame vertical.
storyUIDRef	IN/OUT pass a pointer to get back the reference to the story's text model(ITextModel), pass nil if you don't care.
isLeftToRight	IN kTrue to make frame left to right

Returns

UIDRef of frame created, from which an IGraphicFrameData can be instantiated if the call succeeded, or UIDRef::gNull if failed.

UIDRef SDKLayoutHelper::GetActiveSpreadLayerRef	(	const UIDRef &	spreadUIDRef,
		bool16	wantGuideLayer = kFalse
	)

Acquire UIDRef of active ISpreadLayer.

Parameters

spreadUIDRef	IN references the spread whose active spread layer is wanted
wantGuideLayer	IN kTrue if guide spread layer wanted, kFalse for content spread layer (default kFalse)

Returns

UIDRef of spreadlayer(ISpreadLayer) or UIDRef::gNull if no active spread layer is available.

UIDRef SDKLayoutHelper::GetGraphicFrameRef

(

const InterfacePtr< ITextFrameColumn > &

textFrameColumn

)

Get reference to the graphic frame associated with the given text frame.

Parameters

textFrameColumn

reference to a text frame (ITextFrameColumn), normally a kMultiColumnItemBoss object or a kFrameItemBoss object but can be text on path.

Returns

UIDRef of the associated graphic frame, from which an IGraphicFrameData can be instantiated, or UIDRef::gNull if none.

UIDRef SDKLayoutHelper::GetSpreadLayerRef	(	const UIDRef &	spreadUIDRef,
		int32	documentLayerIndex = 1,
		bool16	wantGuideLayer = kFalse
	)

Acquire UIDRef of the spread layer (ISpreadLayer) associated with the indicated document layer where the desired document layer is indicated by its index into ILayerList.

Parameters

spreadUIDRef	reference to spread (ISpread) reference
documentLayerIndex	index in ILayerList of document layer whose spread layer is wanted. Default to 1 as 0 is the pages layer and we're likely interested in contents
wantGuideLayer	IN kTrue if guide spread layer wanted, kFalse for content spread layer (default kFalse)

Returns

UIDRef of spreadlayer(ISpreadLayer) or UIDRef::gNull if no spread layer exists for this documentLayerIndex.

UIDRef SDKLayoutHelper::GetTextModelRef

(

const InterfacePtr< IGraphicFrameData > &

graphicFrameData

)

Get reference to the text model associated with the given graphic frame.

Parameters

graphicFrameData

reference to a graphic frame, normally a kSplineItemBoss object.

Returns

UIDRef of the associated story's text model (from which an ITextModel can be instantiated), or UIDRef::gNull if none.

UIDRef SDKLayoutHelper::OpenDocument	(	const IDFile &	sysFile,
		UIFlags	uiFlags = K2::kFullUI
	)

Open an existing document for which the path is known, and acquire UIDRef, but don't open layout window onto it.

Parameters

sysFile	IN specifies the path to the file
uiFlags	IN (default kFullUI)

Precondition

the file at specified path should exist and be a type the app can open, i.e. be supported by an open provider service

Returns

UIDRef of the document opened, from which an IDocument can be instantiated.

Postcondition

document is in the open document list if opened successfully.

ErrorCode SDKLayoutHelper::OpenLayoutWindow

(

const UIDRef &

documentUIDRef

)

Open a layout view on the document.

Parameters

documentUIDRef

references an IDocument object.

Returns

kSuccess if window opened, other ErrorCode otherwise.

PMRect SDKLayoutHelper::PageToSpread	(	const UIDRef &	pageUIDRef,
		const PMRect &	boundsInPageCoords
	)

Return boundingBox transformed from page to spread co-ordinates. Laying out of content relative to a page is easy since the page origin is at the top left of the page. This call accounts for margins so the origin is adjusted to be the top left margin rather than the top left of the page (it is assumed that all content is being positioned within the margins).

Parameters

pageUIDRef	references page the boundingBox lies on.
boundsInPageCoords	bounds in page co-ordinate space. For example PMRect(10,10,30,30) is specifies a 20 point by 20 point square 10 points in and down from the top left margin on the page.

Returns

the bounding box in spread's co-ordinate system

UIDRef SDKLayoutHelper::PlaceFileInFrame	(	const IDFile &	contentFile,
		const UIDRef &	parentUIDRef,
		const PMRect &	boundsInParentCoords,
		const UIFlags	uiFlags = K2::kFullUI,
		const bool16	retainFormat = kTrue,
		const bool16	convertQuotes = kTrue,
		const bool16	applyCJKGrid = kFalse,
		const UID &	uidPreview = kInvalidUID
	)

Create a rectangular frame and place a content file inside it, if the placed content is a text this will result in a text frame, otherwise a frame containing a picture will be created.

Parameters

contentFile	file containing content to be placed in frame.
parentUIDRef	IN reference to an IHierarchy item. Normally this is a kSpreadLayerBoss but could be another type of page item that will parent the new item.
boundsInParentCoords	IN bounds in parent's co-ordinate space. When the parent is a kSpreadLayerBoss this is spread co-ordinates.
uiFlags	IN (default kFullUI) controls whethet the import provider displays its options for the import.
retainFormat	IN (default kTrue).
convertQuotes	IN (default kTrue).
applyCJKGrid	IN (default kFalse).
uidPreview	IN (default kInvalidUID) identifies a proxy

Returns

UIDRef of frame(IGraphicFrameData) created, or UIDRef::gNull if failed.

ErrorCode SDKLayoutHelper::SaveDocumentAs	(	const UIDRef &	documentUIDRef,
		const IDFile &	sysFile,
		UIFlags	uiFlags = kFullUI
	)

Save document to specified path.

Parameters

documentUIDRef	IN specifies document of interest
sysFile	IN path to save to
uiFlags	IN control over associated user interface (default kFullUI)

Precondition

documentUIDRef and sysFile should be valid

Returns

kSuccess if document could be saved, kFailure otherwise

Postcondition

document written out on success