The Spool Library: 5.2 Print Control Messages: Flow of Control Messages

| Up: GEOS SDK TechDocs | Up | Prev: 5.1 Common Response Messages | Next: 5.3 Working with Instance Data 
MSG_PRINT_CONTROL_PRINTING_COMPLETED, MSG_PRINT_CONTROL_REPORT_PROGRESS, MSG_PRINT_CONTROL_PRINTING_CANCELLED, MSG_PRINT_CONTROL_REPORT_STRING, MSG_PRINT_CONTROL_INITIATE_PRINT, MSG_PRINT_CONTROL_PRINT, MSG_PRINT_CONTROL_INITIATE_OUTPUT_UI

Sending these messages to the Print Control signals that a new stage of printing is ready to begin.

MSG_PRINT_CONTROL_PRINTING_COMPLETED

void	MSG_PRINT_CONTROL_PRINTING_COMPLETED();

This message signals the Print Control that the application is finished describing the print job. The application must send this message (or a MSG_PRINT_CONTROL_PRINTING_CANCELLED ) some time after receiving a MSG_PRINT_START_PRINTING .

Source: The object that received MGS_PRINT_START_PRINTING .

Destination: Any PrintControl object.

Parameters: None.

Return: Nothing.

Interception: Unlikely, unadvised.

MSG_PRINT_CONTROL_REPORT_PROGRESS

Boolean	MSG_PRINT_CONTROL_REPORT_PROGRESS(
        PCProgressType 	progress,
        int 	pageOrPercent);

This message may be sent between the time the Print Output receives a MSG_PRINT_START_PRINTING and the time it sends a MSG_PRINT_CONTROL_PRINTING_COMPLETED . Its arguments include a progress type (page number or percentage) and a number representing the progress. It returns a Boolean value, which will normally be true but will be false if the user wishes to cancel printing.

The application should send out this message periodically over the course of a long print job, probably about once per page. Progress may be reported as a page number, a percentage of the job completed, or as a null-terminated string.

If the return value is false , the application should stop drawing to the print GString immediately and send the Print Control a MSG_PRINT_CONTROL_PRINTING_CANCELLED . The return value may be safely ignored, but if the user wishes to cancel printing, it's polite to cancel immediately instead of making him wait until the MSG_PRINT_START_PRINTING has finished describing the entire job.

Source: The object that received MGS_PRINT_START_PRINTING when building a time-consuming job.

Destination: The PrintControl object specified by MSG_PRINT_START_PRINTING .

Parameters: progress How progress is being reported, by page (PCPT_PAGE) or percent (PCPT_PERCENT).

pageOrPercent
How much progress has been made.

Return: Flag signalling that printing should continue. If the flag is false (i.e. zero), then the user wants to cancel printing, and it would be polite to stop.

Interception: Unlikely.

Structures: The PCProgressType enumeration is defined:

 typedef enum {
 PCPT_PAGE,
 PCPT_UNUSED1, /* Unused type */
 PCPT_PERCENT,
 PCPT_UNUSED2, /* Unused type */
 PCPT_TEXT
} PCProgressType;

MSG_PRINT_CONTROL_REPORT_PROGRESS_STRING

@alias(MSG_PRINT_CONTROL_REPORT_PROGRESS) \ 
Boolean	MSG_PRINT_CONTROL_REPORT_PROGRESS_STRING(
        PCProgressType 	progress,
        Chars 	*progressString);

This message may be sent between the time the Print Output receives a MSG_PRINT_START_PRINTING and the time it sends a MSG_PRINT_CONTROL_PRINTING_COMPLETED . Its arguments include a text string giving some indication of progress. This message returns a Boolean value, which will normally be true but will be false if the user wishes to cancel printing.

The application should send out this message periodically over the course of a long print job, probably about once per page. Progress may be reported as a page number, a percentage of the job completed, or as a null-terminated string.

If the return value is false , the application should stop drawing to the print GString immediately and send the Print Control a MSG_PRINT_CONTROL_PRINTING_CANCELLED . The return value may be safely ignored, but if the user wishes to cancel printing, it's polite to cancel immediately instead of making him wait until the MSG_PRINT_START_PRINTING has finished describing the entire job.

Source: The object that received MGS_PRINT_START_PRINTING when building a time-consuming job.

Destination: The PrintControl object specified by MSG_PRINT_START_PRINTING .

Parameters: progress This must be PCPT_TEXT. The reason that this parameter has only one possible value is that this message is actually an alias of MSG_PRINT_CONTROL_REPORT_PROGRESS , handled by the same assembly routine.

progressString
A string of text, giving an indication of progress.

Return: Flag signalling that printing should continue. If the flag is false (i.e. zero), then the user wants to cancel printing, and it would be polite to stop.

Interception: Unlikely.

Structures: The PCProgressType enumeration is defined:

typedef enum {
 PCPT_PAGE,
 PCPT_UNUSED1, /* Unused type */
 PCPT_PERCENT,
 PCPT_UNUSED2, /* Unused type */
 PCPT_TEXT
} PCProgressType;

MSG_PRINT_CONTROL_INITIATE_OUTPUT_UI

void MSG_PRINT_CONTROL_INITIATE_OUTPUT_UI(
        PrinterDriverType type);

Display the output dialog box.

Source: Anything.

Destination: PrintControl object.

Parameters: type PrinterDriverType value specifying what sort of printer device.

Return: Nothing.

Interception: Rare. This messages is generally used internally only, as the PrintControl normally provides all the UI neededfor printing.

MSG_PRINT_CONTROL_PRINTING_CANCELLED

void	MSG_PRINT_CONTROL_PRINTING_CANCELLED();

The application may send this message to the PrintControl after receiving a MSG_PRINT_START_PRINTING . Do not send both this message and a MSG_PRINT_CONTROL_PRINTING_COMPLETED for a single print job.

The application may send this message to cancel a document while describing a print job, before it would send the MSG_PRINT_CONTROL_PRINTING_COMPLETED .

Source: Unrestricted, probably the PCI_output .

Destination: The PrintControl object specified by MSG_PRINT_START_PRINTING .

Parameters: None.

Return: Nothing.

Interception: Unlikely.

MSG_PRINT_CONTROL_INITIATE_PRINT

void	MSG_PRINT_CONTROL_INITIATE_PRINT();

This message, normally sent by the Print trigger in the File menu, is the signal that the Print Control should display the Print dialog box. Geodes with custom print triggers should make sure that those triggers send this message to the Print Control. Geodes using the Print Control's provided print trigger need not send this message.

Source: Unrestricted--typically the user print trigger (or fax trigger).

Destination: Any PrintControl object.

Parameters: None.

Return: Nothing.

Interception: Unlikely.

MSG_PRINT_CONTROL_PRINT

void	MSG_PRINT_CONTROL_PRINT();

This message, normally sent by the Print trigger in the Print dialog box, is the signal that the user has made his printing choices and is ready for the Print Control to verify those choices and spool the job.

Source: Unrestricted--typically the Print trigger in the Print Dialog Box.

Destination: Any PrintControl object.

Parameters: None.

Return: Nothing.

Interception: Unlikely.

| Up: GEOS SDK TechDocs | Up | Prev: 5.1 Common Response Messages | Next: 5.3 Working with Instance Data