The Spool Library: 4.5 Print Control Instance Data: Print Output Object

PCI_output, MSG_PRINT_START_PRINTING, MSG_PRINT_VERIFY_PRINT_REQUEST, MSG_PRINT_NOTIFY_PRINT_DB

Some object is going to describe the print jobs to the Print Control. When instantiating the Print Control, set the chosen object's name in the PCI_output field:

PCI_output = <yourObject>;

There are three messages the Print Control may send to its output: MSG_PRINT_START_PRINTING, MSG_PRINT_VERIFY_PRINT_REQUEST, andMSG_PRINT_NOTIFY_PRINT_DB . The Print Output must respond to MSG_PRINT_START_PRINTING , which is the signal that it's time to describe a print job. The Print Output also must respond to MSG_PRINT_VERIFY_PRINTING if the PrintControl's PCA_VERIFY_PRINT bit has been set. Otherwise, it need not handle this message. Finally, the Print Output may have a handler for the MSG_PRINT_NOTIFY_DB , a message the PrintControl will send whenever the Print dialog box comes up or goes away.

The Print Method

Assuming your geode doesn't try to do anything fancy with its own printing UI or weird scheduling, probably the most complicated thing you'll have to do when adding printing capability to your geode is write a Print Method.

This message must be handled by the Print Output object, though the handler probably won't be too complicated. In its simplest form, a MSG_PRINT_START_PRINTING handler could just call some graphics commands and finish off by sending MSG_PRINT_CONTROL_PRINTING_COMPLETED to the PrintControl.

The message is accompanied by a pointer back to the Print Control and a GString handle. Any graphics commands drawn to the GString handle will be retained and will become part of the print job.

Before looking at examples, be warned that there are some requirements that every Print Method must meet:

Be sure the document size has been set correctly. Before the job is finished and you send MSG_PRINT_CONTROL_PRINTING_COMPLETED , you must be certain the document's size and margins have been set somewhere. This may have been set using the PCI_docSizeInfo field when defining the Print Control. If you haven't already let the Print Control know about the document size elsewhere, then you must send a MSG_PRINT_CONTROL_SET_DOC_SIZE , probably either in the MSG_PRINT_START_PRINTING or wherever your geode sets up document information in general.
Be certain the number of pages to be printed has been correctly set. If your application hasn't already set the page range (when the Print Control was created or when the Print dialog box goes up are popular times for this), send aMSG_PRINT_CONTROL_SET_TOTAL_PAGE_RANGE to your Print Control. Make sure you do it before sending in the MSG_PRINT_CONTROL_PRINTING_COMPLETED .
Be sure the document name has been set. If you use a GenDocumentGroup as your PCI_docNameOutput , this will be taken care of for you. Otherwise, some time before the MSG_PRINT_CONTROL_PRINTING_COMPLETED is sent, your PCI_docNameOutput object is going to be asked for the document name, and the job won't be spooled until your PCI_docNameOutput sends the correct name back to the Print Control.
The Print Method should end each page with a GrNewPage() ; the last thing drawn before the print job ends is a GrNewPage() .
Finally, when the Print Method is finished describing the print job, it must end with a MSG_PRINT_CONTROL_PRINTING_COMPLETED . Otherwise, the Print Control has no way of knowing the job is ready.

When the Print Control receives the message MSG_PRINT_CONTROL_PRINTING_COMPLETED , it responds by cleaning up and sending the print job to the spooler.

Your handler can send a MSG_PRINT_CONTROL_REPORT_PROGRESS to the Print Control if it is spooling a large job and wants to reassure the user. If something goes wrong, or if MSG_PRINT_CONTROL_REPORT_PROGRESS returns a signal indicating the user wishes to cancel, MSG_PRINT_START_PRINTING should send a MSG_PRINT_CONTROL_PRINTING_CANCELLED instead.

MSG_PRINT_START_PRINTING

void	MSG_PRINT_START_PRINTING(
        optr		printControlOD,
        GStateHandle		gstate);

The handler for this message should call a number of graphics routines, using the passed GState. When done with graphics routines, the handler should send a MSG_PRINT_CONTROL_PRINTING_COMPLETED (or MSG_PRINT_CONTROL_PRINTING_CANCELED ) to the Print Control. The handler may have to accomplish other tasks; see the above bulleted list (the one marked as "the most used and useful section of this chapter").

Source: PrintControl object.

Destination: The object specified in PCI_output .

Parameters: printControlOD The optr of the PrintControl object.

gstate: The GState handle to draw to.

Return: Nothing.

Interception: The Print output object must intercept this message, build the print job by drawing to the passed GState, then send MSG_PRINT_CONTROL_PRINTING_COMPLETED to the object in printControlOD .

Verifying User Choices

You may write a handler for MSG_PRINT_VERIFY_PRINT_REQUEST , which will be sent to the Print Output if the PCA_VERIFY_PRINT bit has been set. The message will be sent after the user has dismissed the Print dialog box, after the system has had a chance to make sure the document fits on the paper but before the document is actually spooled.

This message gives the application a chance to check out the state of the UI and make sure that the user's choices are valid. Note that the PrintControl does its own checking to make sure that the document will fit on the page. After examining the UI, the handler must send back a MSG_PRINT_CONTROL_VERIFY_COMPLETED , passing the argument to say whether it's okay to print.

MSG_PRINT_VERIFY_PRINT_REQUEST

void	MSG_PRINT_VERIFY_PRINT_REQUEST(
        optr 	printControlOD);

The handler for this message should make whatever checks are necessary to make sure that the user has made valid choices with the printing UI. The handler should then send back an indication of whether the user's choices are all right by means of a MSG_PRINT_CONTROL_VERIFY_COMPLETED.

Source: PrintControl object.

Destination: The object specified in PCI_output .

Parameters: printControlOD The optr of the PrintControl object.

Return: Nothing explicitly. However, the handler for this message must send a MSG_PRINT_CONTROL_VERIFY_COMPLETED back to the print control.

Interception: If you've set the PCA_VERIFY_PRINT flag, you must intercept this message correctly or else the print job will never start.

Dialog Box Notification

The Print Control will send the Print Output a MSG_PRINT_NOTIFY_DB every time the Print dialog box comes up or goes away. Note that this message allows the application to update the page range and print group's UI at only those times that updates are needed.

This message will arrive with one argument, a pointer back to the PrintControl object that sent it. The handler for this message might wish to update the page range information using MSG_PRINT_CONTROL_SET_TOTAL_PAGE_RANGE and MSG_PRINT_CONTROL_SET_SELECTED_PAGE_RANGE .

MSG_PRINT_NOTIFY_PRINT_DB

void	MSG_PRINT_NOTIFY_PRINT_DB(
        optr		printControlOD,
        PrintControlStatus		pcs);

The handler for this message can do any almost anything; this message signals that the Print dialog box has just come up or gone away.

Source: PrintControl object.

Destination: The object specified in PCI_output .

Parameters: printControlOD The optr of the PrintControl object.

pcs: The status of the print control; either PCS_PRINT_BOX_VISIBLE or PCS_PRINT_BOX_NOT_VISIBLE.

Return: Nothing.

Interception: Some Print Output objects will intercept this message to set page ranges.

GEOS SDK TechDocs |

4.4 Document Size | Next:

4.6 Document Name Output