CIPrintStream

The CIPrintStream interface can modify PageMaker's printed output by altering the print code as it is sent to the printer. The methods within the interface allow a plug-in to add comments, include dictionaries, and even replace objects as they would be printed.


There are two steps to altering PageMaker's printed output. First you register your plug-in for one or more print events listed below, and then you process those events using the CIPrintStream methods.

For a complete discussion of event notification see the CIBasic interface. The following PageMaker events are used exclusively for accessing the application's print stream. Register your plug-in to receive these events and add information to the print stream in response to them.

The description of each event also lists which methods in the CIPrintStream interface you can use when handling the event. You can use methods from other interfaces while handling any of these events, the limitation applies only to CIPrintStream methods.

Print stream events

PMEVT_PRINT_BEFORE

This event occurs before the publication is printed. If you wish to suppress PageMaker's printing, set the wasHandled flag to true when handling this event.

PMEVT_PRINT_DSCHEADER_AFTER (PostScript only)

Handling this event will allow you to add comments to the PostScript header. If you use the SendPSComment method while handling this event, the comments you add to the stream will be placed just before the %%EndComments comment. The only valid CIPrintStream method when this event is received is: SendPSComments.

PMEVT_PRINT_PROLOG_BEFORE (PostScript only)

This event occurs immediately after the %%BeginProlog is sent to the printer or PostScript output file.

The valid CIPrintStream methods when this event is received are: PrintVM, SendPSDictionaryMem, and SendPSComments.

PMEVT_PRINT_PROLOG_AFTER (PostScript only)

This event occurs just before the %%EndProlog comment is sent to the printer or Postscript output file.

The valid CIPrintStream methods when this event is received are: PrintVM, SendPSDictionaryMem, and SendPSComments.

PMEVT_PRINT_DOCSETUP_BEFORE (PostScript only)

This event occurs just after the %%BeginSetup comment is sent.

The valid CIPrintStream methods when this event is received are: PrintVM, SendSetupPSMem, SendSetupPSFile, and SendPSComments.

PMEVT_PRINT_DOCSETUP_AFTER (PostScript only)

This event occurs just before the %%EndSetup comment is sent to the printer or PostScript output file.

The valid CIPrintStream methods when this event is received are: PrintVM, SendPSBlockMem, SendPSBlockFile, SendPSComments, SendSetupPSMem, and SendSetupPSFile.

PMEVT_PRINT_DSCCOMMENT_PAGELEVEL (PostScript only)

This event occurs just before the %%BeginPageSetup comment is sent to the printer or PostScript output file.

The valid CIPrintStream methods when this event is received are: PrintVM and SendPSComments.

PMEVT_PRINT_PAGESETUP_BEFORE (PostScript only)

This event occurs immediately after the %%BeginPageSetup comment is sent to the printer or PostScript output file.

The valid CIPrintStream methods when this event is received are: PrintVM, SendPSBlockMem, SendPSBlockFile, SendPSComments, SendSetupPSMem, and SendSetupPSFile.

PMEVT_PRINT_PAGESETUP_AFTER (PostScript only)

This event occurs immediately before the %%EndPageSetup comment is sent to the printer or PostScript output file. If you are adding DSC comments that are page-specific, it is recommended that you use this event.

The valid CIPrintStream methods when this event is received are: PrintVM, SendPSBlockMem, SendPSBlockFile, SendPSComments, SendSetupPSMem, and SendSetupPSFile.

PMEVT_PRINT_OBJECT_BEFORE (PostScript only)

This event occurs immediately before an object gets printed. You can replace the default PageMaker PostScript code for an object by registering for this event, sending your PostScript code with SendPSBlockMem or SendPSBlockFile, and setting the PMEvent.wasHandled value to true. Setting wasHandled to true will suppress both the default PostScript code, and the PMEVT_PRINT_OBJECT_AFTER event.

The PMEVT_PRINT_OBJECT_BEFORE event only occurs when PageMaker is printing to a PostScript printer. Use the PMEVT_LAYOUT_DRAWOBJECT_BEFORE event to intercept an object printing to a non-PostScript printer.

The valid CIPrintStream methods when this event is received are: PrintVM, SendPSBlockMem, SendPSBlockFile, and SendPSComments.

PMEVT_PRINT_OBJECT_AFTER (PostScript only)

This event occurs immediately after an object is printed. The PMEvent field lparm holds a pointer to the PMOBJ_REC structure for the object.

The valid CIPrintStream methods when this event is received are: PrintVM, SendPSBlockMem, SendPSBlockFile, and SendPSComments.

PMEVT_PRINT_PAGETRAILER_BEFORE (PostScript only)

This event occurs immediately after the %%PageTrailer comment is sent to the printer or PostScript output file.

The valid CIPrintStream methods when this event is received are: PrintVM, SendPSBlockMem, SendPSBlockFile, SendPSComments, SendSetupPSMem, and SendSetupPSFile.

PMEVT_PRINT_PAGETRAILER_AFTER (PostScript only)

This event occurs after all the comments and PostScript code for the %%PageTrailer section have been sent to the printer. You can add to the page trailer section by writing a handler for this event.

The valid CIPrintStream methods when this event is received are: PrintVM, SendPSBlockMem, SendPSBlockFile, SendPSComment, SendSetupPSMem, and SendSetupPSFile.

PMEVT_PRINT_PRMARKS_BEFORE

This event occurs before the printer marks are added to the print stream. You can replace the default printer marks by writing a handler for this event that sets the wasHandled flag to true.

If you set PMEvents.wasHandled to true, then PageMaker will suppress both the default PostScript code, and the PMEVT_PRINT_PRMARKS_AFTER event.

The valid CIPrintStream methods when this event is received are: PrintVM, SendPSBlockMem, SendPSBlockFile, and SendPSComments.

PMEVT_PRINT_PRMARKS_AFTER

This event occurs after the default printer marks are added to the print stream. If the PMEVT_PRINT_PRMARKS_BEFORE event was handled, notification for this event is not sent.

The valid CIPrintStream methods when this event is received are: PrintVM, SendPSBlockMem, SendPSBlockFile, and SendPSComments.

PMEVT_PRINT_JOBTRAILER_BEFORE (PostScript only)

This event occurs immediately after the %%Trailer comment is sent to the print stream.

The valid CIPrintStream methods when this event is received are: PrintVM, SendPSBlockMem, SendPSBlockFile, SendPSComments, SendSetupPSMem, and SendSetupPSFile.

PMEVT_PRINT_JOBTRAILER_AFTER (PostScript only)

This event occurs immediately before the %%EOF comment.

The valid CIPrintStream methods when this event is received are: PrintVM, SendPSComments, SendSetupPSMem, and SendSetupPSFile.

The CIPrintStream methods

void PrintVM( unsigned long * pVMAmount );

Returns the amount of free VM (virtual memory) the printer has. You must declare pVMAmount and the variable it points to before using this method. The method will copy the value into the location you provide.

PMXErr SendPSBlockMem( char *dataBuffer, unsigned long bufSize);

Downloads a block of memory to the printer or PostScript output file. The PostScript will be encapsulated in a save/restore pair.

PMXErr SendPSBlockFile( LPSTR lpFileName );

Downloads the contents of a file to the printer or PostScript output file. The PostScript that you send will be encapsulated in a save/restore pair.

PMXErr SendPSDictionaryMem( int vmNeeded, char *bufData, unsigned long bufSize, char *dictName );

Downloads a PostScript dictionary to the printer. You must supply the name of the dictionary in *dictName. The name will be added to the %%DocumentSuppliedResources comment at the end of the document.

PMXErr SendSetupPSMem( char *dataBuffer, unsigned long bufSize );

Downloads a block of PostScript to the printer or PostScript output file. The PostScript code will not be encapsulated in a save/restore pair.

PMXErr SendSetupPSFile( char *lpFileName );

Send the contents of the file indicated by *lpFileName to the printer. The PostScript that you send will not be encapsulated in a save/restore pair.

PMXErr SendPSComments( char *dataBuffer, unsigned long bufSize );

Send a PostScript comment to the printer or output file. If the text is not a valid comment it will not be sent and a CQ_PRNTSTRM_NOT_A_COMMENT error is returned.

void EnableCommentDetect( PMBool flag );

This method controls comment checking. With this turned on (the default setting) PostScript code can added to the body of the PostScript code. Sending anything that is not a comment to the header, prolog, setup, or trailer will cause a CQ_PRNTSTRM_NOT_A_COMMENT error. Turning this feature off can result in PostScript code that is incompatible with PostScript consumers such as trapping and document management applications, and can cause unpredictable results when printing.


Example

This example will add a %%Orientation comment to the PostScript print stream. The %%Orientation comment is part of the Document Structuring Comments, but is missing from the PostScript code that PageMaker produces. This example uses the plug-in framework; class Example is a subclass of the base class PPluginCall.

Part 1: Register for the PMEVT_PRINT_DSCHEADER_AFTER event.

void Example::DoRegister()
{// The Example class is assumed to have a member variable 
 // that is a copy of the pointer to the PMMessage structure.
 // That 
CIInterfaceManager *mgr;
CIBasic *basicPtr;
PMXErr result;

//Acquire the Basic interface to get the RegisterPMEvent method.
//sPMMessage is a data member, inherited from PPluginCall
mgr=sPMMessage->pInterfaceMgr;
result = mgr->AcquirePMInterface((unsigned long) PMIID_BASIC, (void **)&basicPtr);
if ( result )
	throw result;

// The event constants are in PMEvent.h.
result = basicPtr->RegisterPMEvent( PMEVT_PRINT_DSCHEADER_AFTER );
if ( result )
	throw result;

//Release the Basic interface.
mgr->ReleasePMInterface( basicPtr );
}

Part 2: Handle the event when it occurs.

When the event that you have registered for occurs, your plug-in is called with kPMEvent. Not shown here is the Dispatch method which you can find in PPluginCall. The Dispatch method is a function factory and the DoEvent method is called in the kPMEvent case.

Example::DoEvent()
{
CIInterfaceManager *mgr;
CIPrintStream *printStream;
PMEvent *event;
PMXErr result;
unsigned long commentLength;


mgr = sPMMessage->pInterfaceMgr;
event = (PMEvent *) sPMMessage->pPMData;
char buffer[100];

// A switch statement would usually be here, since most plug-ins
// that you would register for events, you would register for 
// more than just one or two.

if ( event->eventID == PMEVT_PRINT_DSCHEADER_AFTER )
{
//You will find the PGetPageSize class in the PageMaker Class 
//Library. The PGet* indicates that it is a query.
PGetPageSize myPage;
if (myPage.yHeight >= myPage.xWidth)
{
	// We need to put the comment for portrait into our buffer
	strncpy(buffer, "%%Orientation: Portrait\n", 24);
	commentLength = 24;
}
else
{
	//It's a landscape publication.
	strncpy(buffer, "%%Orientation: Landscape\n",25);
	commentLength = 25;
}

mgr->AcquirePMInterface((unsigned long)PMIID_PRINTSTREAM,
			(void **) &printStream);
result = printStream->SendPSComments(&buffer, commentLength);
if ( result )
	throw result;
mgr->ReleasePMInterface( printStream );
}

Notes on the example.

You can register or unregister your plug-in for notification on an event at any point, but doing it in the DoRegister function enables you to create a plug-in that is completely event driven.


Comments or suggestions? Contact Adobe Developer Support

Copyright © 1997 - 2001 Adobe Systems Incorporated. All rights reserved.
Legal notices and trademark attributions