Collapse all Symbian^3 Product Developer Library

CPrintSetup Class Reference

class CPrintSetup : public CBase

Print setup information.

This class stores the information needed to set up, start and stop a print job. This includes the target printer device, the page margins and the header and footer. The page specification, (page orientation and page dimensions) can be set via the printer device.

Print setup information is associated with a document and is stored as part of the persistent form of the document. Print parameters on the other hand, (class TPrintParameters) are associated with a particular print request, not with the document itself, so are not part of the print setup information.

Inherits from

CPrintSetup
- CBase

Public Member Functions
	~CPrintSetup()
IMPORT_C void	AddPrinterDriverDirL(const TDesC &)
IMPORT_C void	CreatePrinterDeviceL(TInt)
IMPORT_C void	CreatePrinterDeviceL(TUid, RFs &)
IMPORT_C CPrinterDriverUI *	CreatePrinterDriverUIL()
IMPORT_C void	EndPrint()
IMPORT_C void	ExternalizeL(RWriteStream &)
CHeaderFooter *	Footer()
IMPORT_C void	FreeModelList()
CHeaderFooter *	Header()
IMPORT_C void	InternalizeL(RReadStream &)
IMPORT_C CPrinterModelList *	ModelNameListL(RFs &)
IMPORT_C CPrintSetup *	NewL()
IMPORT_C CPrinterDevice *	PrinterDevice()
IMPORT_C void	RestoreComponentsL(const CStreamStore &, const MFieldFileNameInfo , const MFieldNumPagesInfo , MPictureFactory *)
IMPORT_C void	RestoreL(const CStreamStore &, TStreamId, const MFieldFileNameInfo , const MFieldNumPagesInfo , MPictureFactory *)
IMPORT_C TInt	StartPreviewPrintL(const TPrintParameters &, MPageRegionPrinter &, MPrintProcessObserver *, CGraphicsDevice &, const TRect &, const TRect &, TInt)
IMPORT_C TInt	StartPrintL(const TPrintParameters &, MPageRegionPrinter &, CPrinterPort , MPrintProcessObserver )
IMPORT_C void	StoreComponentsL(CStreamStore &, CStoreMap &)
IMPORT_C TStreamId	StoreL(CStreamStore &)

Private Member Functions
	CPrintSetup()
void	ConstructL()
void	DoStartPrintL(const TPrintParameters &, MPageRegionPrinter &, MPrintProcessObserver , CPrinterPort )
void	InitializePrintingL(CGraphicsDevice , const TPrintParameters &, MPrintProcessObserver )
void	InitializePrintingL(const TPrintParameters &, MPrintProcessObserver *, const TRect &, const TRect &)
TInt	UpdateFieldPageNum()

Inherited Functions
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::Extension_(TUint,TAny &,TAny )
	CBase::operator new(TUint)
	CBase::operator new(TUint,TAny *)
	CBase::operator new(TUint,TLeave)
	CBase::operator new(TUint,TLeave,TUint)
	CBase::operator new(TUint,TUint)
	CBase::~CBase()

Private Member Enumerations
enum	anonymous { ENumberFirstPage = 0x0001 }

Public Attributes
TInt	iNumOfFirstPage
TPageMargins	iPageMarginsInTwips

Private Attributes
CArrayFixSeg< TFileName > *	iDriverDirList
CHeaderFooter *	iFooter
CHeaderFooter *	iHeader
CPdrModelList *	iModelList
MPrintProcessObserver *	iPrintObserver
TPrintParameters	iPrintParams
CPreviewProcess *	iPrintProcess
CPrinterDriver *	iPrinterDriver

Constructor & Destructor Documentation

CPrintSetup()

CPrintSetup

(

)

[private]

~CPrintSetup()

IMPORT_C

~CPrintSetup

(

)

[virtual]

Destructor.

This frees all resources owned by the CPrintSetup object, prior to its destruction.

Member Functions Documentation

AddPrinterDriverDirL(const TDesC &)

IMPORT_C void

AddPrinterDriverDirL

(

const TDesC &

aDriverDir

)

Adds a search path for printer drivers.

This function must be called before a model name list can be created. It can be called repeatedly to add a number of paths to the search list.

When a printer model name list is requested (using ModelNameListL()), the directories specified in each of the search paths are scanned on all non-remote drives for .pdr files, indicating the models supported. If any path contains a drive, that drive alone is searched.

leave: KErrNoMemory There is insufficient memory to perform the operation.

Parameters

const TDesC & aDriverDir

Path which specifies a directory in which to search for printer drivers. Any filename in the path is ignored. If the path is already in the list, it is not added again.

ConstructL()

void

ConstructL

(

)

[private]

CreatePrinterDeviceL(TInt)

IMPORT_C void

CreatePrinterDeviceL

(

TInt

aModelIndex

)

Selects the target printer device by its index into the list of printer models.

Unlike the other overload of this function, a panic occurs if no printer model list has previously been created using ModelNameListL().

If a print process is taking place when this function is called, it is aborted.

The existing printer device's page specification is preserved.

leave: KErrNoMemory There is insufficient memory to perform the operation.

Parameters

TInt aModelIndex

Index of the printer device into the list of printer devices.

CreatePrinterDeviceL(TUid, RFs &)

IMPORT_C void	CreatePrinterDeviceL	(	TUid	aModelUid,
			RFs &	aFs
		)

Selects the target printer device, from the list of printer models.

If no printer model name list has previously been created by a call to ModelNameListL(), this function will temporarily create one, freeing it before exiting.

If no printer model in the list has the UID specified, the first printer model in the list is selected by default. If the list contains no printer models at all, a leave occurs.

If a print process is taking place when this function is called, it is aborted.

The existing printer device's page specification is preserved.

leave: KErrNoMemory There is insufficient memory to perform the operation.

leave: KErrNotFound The printer model list contains no printer devices.

Parameters

TUid aModelUid	A UID which identifies a printer device.
RFs & aFs	A connection to a file server session.

CreatePrinterDriverUIL()

IMPORT_C CPrinterDriverUI *

CreatePrinterDriverUIL

(

)

Creates a user interface for the target printer device, if the current printer driver has a matching .udl file.

Returns a NULL pointer if no matching .udl file was found. The UI can provide such things as custom print setup dialogs.

panic: PRINT 1 No printer device has been selected. Use CreatePrinterDevice() to select one.

DoStartPrintL(const TPrintParameters &, MPageRegionPrinter &, MPrintProcessObserver , CPrinterPort )

void	DoStartPrintL	(	const TPrintParameters &	aPrintParams,
			MPageRegionPrinter &	aBodyPrinter,
			MPrintProcessObserver *	aObserver,
			CPrinterPort *	aPort
		)	[private]

Parameters

const TPrintParameters & aPrintParams
MPageRegionPrinter & aBodyPrinter
MPrintProcessObserver * aObserver
CPrinterPort * aPort

EndPrint()

IMPORT_C void

EndPrint

(

)

Aborts the print operation, if one is currently taking place.

If a print process observer exists, its NotifyPrintEnded() function is called with KErrCancel.

MPrintProcessObserver

ExternalizeL(RWriteStream &)

IMPORT_C void

ExternalizeL

(

RWriteStream &

aStream

)

const

Externalises a CPrintSetup object to a write stream.

The presence of this function means that the standard templated operator<<() (defined in s32strm.h) is available to externalise objects of this class.

This function does not externalise the rich text components of the header and footer (e.g. fields, pictures and rich text-specific formatting), so it may need to be accompanied by a call to StoreComponentsL().

panic: PRINT 1 No printer device has been selected. Use CreatePrinterDevice() to select one.

Parameters

RWriteStream & aStream

Stream to which the object should be externalised.

Footer()

CHeaderFooter *

Footer

(

)

const [inline]

Gets the footer.

FreeModelList()

IMPORT_C void

FreeModelList

(

)

Deletes and sets the printer model list to NULL.

Header()

CHeaderFooter *

Header

(

)

const [inline]

Gets the header.

The CPrintSetup object owns the header and footer. CPrintSetup implements the MFieldPageNumInfo interface, which allows page numbering to be easily added to fields.

InitializePrintingL(CGraphicsDevice , const TPrintParameters &, MPrintProcessObserver )

void	InitializePrintingL	(	CGraphicsDevice *	aPrinterDev,
			const TPrintParameters &	aPrintParams,
			MPrintProcessObserver *	aObserver
		)	[private]

Parameters

CGraphicsDevice * aPrinterDev
const TPrintParameters & aPrintParams
MPrintProcessObserver * aObserver

InitializePrintingL(const TPrintParameters &, MPrintProcessObserver *, const TRect &, const TRect &)

void	InitializePrintingL	(	const TPrintParameters &	aPrintParams,
			MPrintProcessObserver *	aObserver,
			const TRect &	aHeaderRectInPixels,
			const TRect &	aFooterRectInPixels
		)	[private]

Parameters

const TPrintParameters & aPrintParams
MPrintProcessObserver * aObserver
const TRect & aHeaderRectInPixels
const TRect & aFooterRectInPixels

InternalizeL(RReadStream &)

IMPORT_C void

InternalizeL

(

RReadStream &

aStream

)

Internalises a CPrintSetup object from a read stream.

The presence of this function means that the standard templated operator>>() (defined in s32strm.h) is available to internalise objects of this class.

This function does not restore the rich text components of the header and footer, (e.g. fields, pictures and rich text-specific formatting), so it may need to be accompanied by a call to RestoreComponentsL().

Parameters

RReadStream & aStream

Stream from which the object should be internalised.

ModelNameListL(RFs &)

IMPORT_C CPrinterModelList *

ModelNameListL

(

RFs &

aFs

)

Gets the names of all printer models supported.

The function scans all directories in the search path list which were added using AddPrinterDriverDirL(). It returns a list of the printer models supported by the .pdr files found in those directories.

leave: KErrNoMemory There is insufficient memory to perform the operation.

Parameters

RFs & aFs

A connection to a file server session.

NewL()

IMPORT_C CPrintSetup *

NewL

(

)

[static]

Allocates and constructs an uninitialised CPrintSetup object.

After construction, the print settings, including the target printer device and the page specification must be set before printing can begin.

PrinterDevice()

IMPORT_C CPrinterDevice *

PrinterDevice

(

)

const

Gets the selected printer device.

panic: PRINT 1 No printer device has been selected. Use CreatePrinterDevice() to select one.

RestoreComponentsL(const CStreamStore &, const MFieldFileNameInfo , const MFieldNumPagesInfo , MPictureFactory *)

IMPORT_C void	RestoreComponentsL	(	const CStreamStore &	aStore,
			const MFieldFileNameInfo *	aFileNameInfo = NULL,
			const MFieldNumPagesInfo *	aNumPagesInfo = NULL,
			MPictureFactory *	aFactory = NULL
		)

Restores the rich text components of the print setup object's header and footer.

This function only restores the rich text components of the header and footer (e.g. fields, pictures and rich text-specific formatting), so it may need to be accompanied by a call to InternalizeL().

Parameters

const CStreamStore & aStore	The store from which the components should be restored.
const MFieldFileNameInfo * aFileNameInfo = NULL	An optional object implementing the MFieldFileNameInfo interface. This provides the file name for insertion into a field in the header or footer.
const MFieldNumPagesInfo * aNumPagesInfo = NULL	An optional object implementing the MFieldNumPagesInfo interface. This provides the total number of pages for insertion into a field in the header or footer.
MPictureFactory * aFactory = NULL	Picture factory. Must be supplied if the header or footer contains pictures which should be restored.

RestoreL(const CStreamStore &, TStreamId, const MFieldFileNameInfo , const MFieldNumPagesInfo , MPictureFactory *)

IMPORT_C void	RestoreL	(	const CStreamStore &	aStore,
			TStreamId	aStreamId,
			const MFieldFileNameInfo *	aFileNameInfo = NULL,
			const MFieldNumPagesInfo *	aNumPagesInfo = NULL,
			MPictureFactory *	aFactory = NULL
		)

Restores a CPrintSetup object, including its components from a stream store.

Parameters

const CStreamStore & aStore	Store from which to restore the CPrintSetup object
TStreamId aStreamId	ID of the stream containing the external representation of the CPrintSetup object
const MFieldFileNameInfo * aFileNameInfo = NULL	An optional object implementing the MFieldFileNameInfo interface. This provides the file name for insertion into a field in the header or footer.
const MFieldNumPagesInfo * aNumPagesInfo = NULL	An optional object implementing the MFieldNumPagesInfo interface. This provides the total number of pages for insertion into a field in the header or footer.
MPictureFactory * aFactory = NULL	Picture factory. Must be supplied if the header or footer contains pictures which should be restored.

StartPreviewPrintL(const TPrintParameters &, MPageRegionPrinter &, MPrintProcessObserver *, CGraphicsDevice &, const TRect &, const TRect &, TInt)

IMPORT_C TInt	StartPreviewPrintL	(	const TPrintParameters &	aPrintParams,
			MPageRegionPrinter &	aBodyPrinter,
			MPrintProcessObserver *	anObserver,
			CGraphicsDevice &	aPreviewDev,
			const TRect &	aHeaderRectInPixels,
			const TRect &	aFooterRectInPixels,
			TInt	aNumBands
		)

Starts a new print preview.

If a print process observer is specified, this function calls its NotifyPrintStarted() function.

panic: PRINT 1 No printer device has been selected. Use CreatePrinterDevice() to select one.

Parameters

const TPrintParameters & aPrintParams	The parameters for the print preview operation.
MPageRegionPrinter & aBodyPrinter	An object which implements the page region printer interface.
MPrintProcessObserver * anObserver	An optional object which implements the print process observer interface.
CGraphicsDevice & aPreviewDev	The graphics device to print to. Must not be NULL
const TRect & aHeaderRectInPixels	The rectangle within the top page margin to contain the header.
const TRect & aFooterRectInPixels	The rectangle within the bottom page margin to contain the footer.
TInt aNumBands	The number of bands per page.

StartPrintL(const TPrintParameters &, MPageRegionPrinter &, CPrinterPort , MPrintProcessObserver )

IMPORT_C TInt	StartPrintL	(	const TPrintParameters &	aPrintParams,
			MPageRegionPrinter &	aBodyPrinter,
			CPrinterPort *	aPort,
			MPrintProcessObserver *	anObserver
		)

Starts a new print job.

If a print process observer is specified, this function calls its NotifyPrintStarted() function.

panic: PRINT 1 No printer device has been selected. Use CreatePrinterDevice() to select one.

Parameters

const TPrintParameters & aPrintParams	The parameters for the print job.
MPageRegionPrinter & aBodyPrinter	An object which implements the page region printer interface.
CPrinterPort * aPort	The printer port. Must be provided if the selected printer device requires one.
MPrintProcessObserver * anObserver	An optional object which implements the print process observer interface.

StoreComponentsL(CStreamStore &, CStoreMap &)

IMPORT_C void	StoreComponentsL	(	CStreamStore &	aStore,
			CStoreMap &	aMap
		)	const

Stores the rich text components of the print setup object's header and footer.

This function does not store any other print setup information, so may need to be accompanied by a call to ExternalizeL().

Parameters

CStreamStore & aStore	The store to which the rich text components of the header and footer are stored.
CStoreMap & aMap	Table of swizzles. Supports the deferred loading from the stream store of the components.

StoreL(CStreamStore &)

IMPORT_C TStreamId

StoreL

(

CStreamStore &

aStore

)

const

Stores a CPrintSetup object, including its components (e.g. header and footer) to a stream store.

A panic occurs if no printer device has been created. Use CreatePrinterDevice() to create one.

Parameters

CStreamStore & aStore

Store to which the CPrintSetup object should be stored.

UpdateFieldPageNum()

TInt

UpdateFieldPageNum

(

)

const [private]

Member Enumerations Documentation

Enum anonymous

Enumerators

ENumberFirstPage = 0x0001

Member Data Documentation

CArrayFixSeg< TFileName > * iDriverDirList

CArrayFixSeg< TFileName > *

iDriverDirList

[private]

CHeaderFooter * iFooter

CHeaderFooter *

iFooter

[private]

CHeaderFooter * iHeader

CHeaderFooter *

iHeader

[private]

CPdrModelList * iModelList

CPdrModelList *

iModelList

[private]

TInt iNumOfFirstPage

TInt	iNumOfFirstPage

The number of the first page in the document.

This value is used for printing or displaying page numbering. Note that all other page numbering is zero indexed, to preserve independence from user-defined page numbering.

TPageMargins iPageMarginsInTwips

TPageMargins

iPageMarginsInTwips

The header and footer offset and the width of the four margins.

All measurements are in twips.

TPageMargins

MPrintProcessObserver * iPrintObserver

MPrintProcessObserver *

iPrintObserver

[private]

TPrintParameters iPrintParams

TPrintParameters

iPrintParams

[private]

CPreviewProcess * iPrintProcess

CPreviewProcess *

iPrintProcess

[private]

CPrinterDriver * iPrinterDriver

CPrinterDriver *

iPrinterDriver

[private]

CPrintSetup Class Reference

Inherits from

Constructor & Destructor Documentation

CPrintSetup()

~CPrintSetup()

Member Functions Documentation

AddPrinterDriverDirL(const TDesC &)

Parameters

ConstructL()

CreatePrinterDeviceL(TInt)

Parameters

CreatePrinterDeviceL(TUid, RFs &)

Parameters

CreatePrinterDriverUIL()

DoStartPrintL(const TPrintParameters &, MPageRegionPrinter &, MPrintProcessObserver *, CPrinterPort *)

Parameters

EndPrint()

ExternalizeL(RWriteStream &)

Parameters

Footer()

FreeModelList()

Header()

InitializePrintingL(CGraphicsDevice *, const TPrintParameters &, MPrintProcessObserver *)

Parameters

InitializePrintingL(const TPrintParameters &, MPrintProcessObserver *, const TRect &, const TRect &)

Parameters

InternalizeL(RReadStream &)

Parameters

ModelNameListL(RFs &)

Parameters

NewL()

PrinterDevice()

RestoreComponentsL(const CStreamStore &, const MFieldFileNameInfo *, const MFieldNumPagesInfo *, MPictureFactory *)

Parameters

RestoreL(const CStreamStore &, TStreamId, const MFieldFileNameInfo *, const MFieldNumPagesInfo *, MPictureFactory *)

Parameters

StartPreviewPrintL(const TPrintParameters &, MPageRegionPrinter &, MPrintProcessObserver *, CGraphicsDevice &, const TRect &, const TRect &, TInt)

Parameters

StartPrintL(const TPrintParameters &, MPageRegionPrinter &, CPrinterPort *, MPrintProcessObserver *)

Parameters

StoreComponentsL(CStreamStore &, CStoreMap &)

Parameters

StoreL(CStreamStore &)

Parameters

UpdateFieldPageNum()

Member Enumerations Documentation

Enum anonymous

Enumerators

Member Data Documentation

CArrayFixSeg< TFileName > * iDriverDirList

CHeaderFooter * iFooter

CHeaderFooter * iHeader

CPdrModelList * iModelList

TInt iNumOfFirstPage

TPageMargins iPageMarginsInTwips

MPrintProcessObserver * iPrintObserver

TPrintParameters iPrintParams

CPreviewProcess * iPrintProcess

CPrinterDriver * iPrinterDriver

DoStartPrintL(const TPrintParameters &, MPageRegionPrinter &, MPrintProcessObserver , CPrinterPort )

InitializePrintingL(CGraphicsDevice , const TPrintParameters &, MPrintProcessObserver )

RestoreComponentsL(const CStreamStore &, const MFieldFileNameInfo , const MFieldNumPagesInfo , MPictureFactory *)

RestoreL(const CStreamStore &, TStreamId, const MFieldFileNameInfo , const MFieldNumPagesInfo , MPictureFactory *)

StartPrintL(const TPrintParameters &, MPageRegionPrinter &, CPrinterPort , MPrintProcessObserver )