Class: MBasePrintChannel

Declaration: PrintChannel.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

TPrintChannel

Purpose:

This is an abstract base class that acts both as a protocol specification and as a base class for print jobs. All the standard types of operations that you can perform on jobs are defined here, and the functionality behind the operations is provided by its derived classes. A print channel is used to print pages of a document. It defines the scope of a print job, the job's beginning and end, and how it gets wrapped into something that a printer can use. Think of a channel as a conduit into which a print job (defined by a print job description) gets dumped during the printing process. It is a passive iterator for pages. Because of the nature of printing, a printing session must be bracketed by a definitive beginning and end. The print channel was invented for this purpose. A print session requires an explicit begin and end call so that clients and the printing system know when and if these two events occur. Failure to end a job properly results in an aborted (canceled) job when the print channel is destroyed. The job is not automatically printed. If an exception occurs before the client calls the end function, and the exception is not caught, the job is aborted. When a print channel is initially created, it is in a dormant state. To activate the print channel, BeginJob must be called, through which the print channel receives a relevant print job description. Until an EndJob is called, the print channel accepts pages to print through PrintPage calls. Each call to PrintPage produces a separate page, which means that all page content must be contained in a single MGraphic, such as a view. After the EndJob call, the print channel submits the job for printing and again returns to its dormant state. While in its dormant state, a print channel can be safely discarded or reused to print another print job. If a problem occurs before EndJob is called and the client (or user) decides to cancel the current job, the client simply calls CancelJob without calling EndJob. After CancelJob or EndJob is called on a print channel, the channel can be considered dormant.

Instantiation:

Abstract class; do not instantiate.

Deriving Classes:

Must be derived from. Derived classes must implement BeginJob, EndJob, EndJobAndCreateJobHandle, CancelJob, and PrintPage.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: MBasePrintChannel::~MBasePrintChannel

virtual ~ MBasePrintChannel ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MBasePrintChannel::BeginJob

virtual void BeginJob (const TPrintJobDescription &)

Interface Category:

API.

Purpose:

Indicates the start of a print job.

Calling Context:

Never called directly since this is a pure virtual function in this class.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MBasePrintChannel::EndJob

virtual void EndJob ()

Interface Category:

API.

Purpose:

When the job is completed (that is, all pages have been printed and other operations fully specified), then EndJob must be called to signal to the job object that no more data is forthcoming. If this function is not called, the object raises an exception when the job is deleted, unless the job has been otherwise aborted.

Calling Context:

Never called directly since this is a pure virtual function of this class.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MBasePrintChannel::EndJobAndCreateJobHandle

virtual TPrintJobHandle * EndJobAndCreateJobHandle ()

Interface Category:

API.

Purpose:

Indicates the end of a print job and returns a pointer to the TPrintJobHandle object, from which clients can do things like get the status of the job, pause it, and cancel it.

Calling Context:

Never called directly since this is a pure virtual function of this class.

Parameters:

Return Value:

Returns a pointer to TPrintJobHandle. The client is responsible for deleting it.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MBasePrintChannel::CancelJob

virtual void CancelJob ()

Interface Category:

API.

Purpose:

Cancels all job activity for the current job, if there is one. Any data or operation that has occurred up to the point of call is deleted or ignored. All data is flushed and the channel is returned to an empty state.

Calling Context:

Never called directly since this is a pure virtual function of this class.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MBasePrintChannel::PrintPage

virtual void PrintPage (const MDrawable &, const TPageDescription &)

Interface Category:

API.

Purpose:

Prints the graphic or drawable passed in as a new clean page.

Calling Context:

Never called directly since this is a pure virtual function of this class.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MBasePrintChannel::operator<<=

virtual TStream & operator <<= (TStream & fromwhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called directly to stream in data.

Parameters:

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MBasePrintChannel::operator>>=

virtual TStream & operator >>=(TStream & towhere) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called directly to stream out data.

Parameters:

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MBasePrintChannel::operator=

MBasePrintChannel & operator =(const MBasePrintChannel & channel)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MBasePrintChannel::MBasePrintChannel

  1. MBasePrintChannel ()
  2. MBasePrintChannel (const MBasePrintChannel &)

Interface Category:

API.

Purpose:

  1. Default constructor.
  2. Copy constructor.

Calling Context:

  1. Called by the stream-in operators and the derived class default constructor.
  2. Called to copy an object.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.
Click the icon to mail questions or corrections about this material to Taligent personnel.
Copyright©1995 Taligent,Inc. All rights reserved.