Class CPrintSetup

CPrintSetup

Support

Supported from 5.0

Description

Print setup information.

This class stores the information needed to set up, start and stop a print job.

This information 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, (see class TPrintParameters) are associated with a particular print request, not with the document itself, so are not part of the print setup information.

Derivation

CBase Base class for all classes to be instantiated on the heap CPrintSetup Print setup information MFieldPageNumInfo Specifies the mixin protocol for evaluating a page number field (see class CPageNumField)

Defined in CPrintSetup:
AddPrinterDriverDirL(), CreatePrinterDeviceL(), CreatePrinterDriverUIL(), EndPrint(), ExternalizeL(), Footer(), FreeModelList(), Header(), InternalizeL(), ModelNameListL(), NewL(), PrinterDevice(), RestoreComponentsL(), RestoreL(), StartPreviewPrintL(), StartPrintL(), StoreComponentsL(), StoreL(), iNumOfFirstPage, iPageMarginsInTwips, ~CPrintSetup()

Inherited from CBase:
operator new()

Inherited from MFieldPageNumInfo:
UpdateFieldPageNum()

static CPrintSetup* NewL();

Description

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.

Return value

CPrintSetup* The print setup object

Leave codes

KErrNoMemory There is insufficient memory to perform the operation.

virtual ~CPrintSetup();

Description

Destructor.

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

TStreamId StoreL(CStreamStore& aStore)const;

Description

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

Parameters

CStreamStore& aStore Store to which the CPrintSetup object should be stored.

Return value

TStreamId ID of the stream containing the external representation of the CPrintSetup object.

Leave codes

KErrNoMemory There is insufficient memory to perform the operation.

Notes:

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

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

Description

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 Picture factory. Must be supplied if the header or footer contains pictures which should be restored.

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

Description

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

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.

Leave codes

KErrNoMemory The write action caused the stream's resources to be exhausted.

Notes:

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

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

Description

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

Parameters

const CStreamStore& aStore The store from which the components should be restored. const MFieldFileNameInfo* aFileNameInfo 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 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 Picture factory. Must be supplied if the header or footer contains pictures which should be restored.

Leave codes

KErrNoMemory The operation caused an out of memory error.

Notes:

• 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().

void ExternalizeL(RWriteStream& aStream) const;

Description

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.

Parameters

RWriteStream& aStream Stream to which the object should be externalised.

Leave codes

KErrNoMemory The write action caused the stream's resources to be exhausted.

Panic codes

EPanicNoPrinterDriver No printer device has been selected. Use CreatePrinterDevice() to select one.

Notes:

• 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().

void InternalizeL(RReadStream& aStream);

Description

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.

Parameters

RReadStream& aStream Stream from which the object should be internalised.

Leave codes

KErrNoMemory Internalisation caused an out of memory error.

Notes:

• 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().

void AddPrinterDriverDirL(const TDesC& aDriverDir);

Description

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.

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.

Leave codes

KErrNoMemory There is insufficient memory to perform the operation.

Notes:

• 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.

CPrinterModelList* ModelNameListL(RFs& aFs);

Description

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.

Parameters

RFs& aFs A connection to a file server session.

Return value

CPrinterModelList* The list of printer models supported.

Leave codes

KErrNoMemory There is insufficient memory to perform the operation.

void FreeModelList();

Description

Deletes and sets the printer model list to NULL.

void CreatePrinterDeviceL(TUid aModelUid,RFs& aFs);

Description

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.

Parameters

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

Leave codes

KErrNoMemory There is insufficient memory to perform the operation. KErrNotFound The printer model list contains no printer devices.

Notes:

• If a print process is taking place when this function is called, it is aborted.
• The existing printer device's page specification is preserved.

void CreatePrinterDeviceL(TInt aModelIndex);

Description

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

Parameters

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

Leave codes

KErrNoMemory There is insufficient memory to perform the operation.

Notes:

• 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.

CPrinterDevice* PrinterDevice()const;

Description

Gets the selected printer device.

Return value

CPrinterDevice* The selected printer device.

Panic codes

EPanicNoPrinterDriver No printer device has been selected. Use CreatePrinterDevice() to select one.

CPrinterDriverUI* CreatePrinterDriverUIL();

Description

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.

Return value

CPrinterDriverUI* The UI for the selected printer device.

Panic codes

EPanicNoPrinterDriver No printer device has been selected. Use CreatePrinterDevice() to select one.

void EndPrint();

Description

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

Notes:

• If a print process observer exists, its NotifyPrintEnded() function is called with KErrCancel. For more details, see class MPrintProcessObserver.

See also:

• MPrintProcessObserver

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

Description

Starts a new print job.

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

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.

Return value

TInt KErrNone if the operation completed successfully, KErrAlreadyExists if a print process is already taking place, or another of the system-wide error codes.

Leave codes

KErrNoMemory There is insufficient memory to perform the operation.

Panic codes

EPanicNoPrinterDriver No printer device has been selected. Use CreatePrinterDevice() to select one.

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

Description

Starts a new print preview.

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

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.

Return value

TInt KErrNone if the operation completed successfully, KErrAlreadyExists if a print preview process is already taking place, or another of the system-wide error codes.

Leave codes

KErrNoMemory Insufficient resources are available.

Panic codes

EPanicNoPrinterDriver No printer device has been selected. Use CreatePrinterDevice() to select one.

CHeaderFooter* Header()const;

Description

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.

Return value

CHeaderFooter* The header.

CHeaderFooter* Footer()const;

Description

Gets the footer.

Return value

CHeaderFooter* The footer.

TInt iNumOfFirstPage

Description

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

Description

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

All measurements are in twips.

See also:

• TPageMargins