Michael J. Young

Although the final results can be gratifying, writing code to print under Microsoft Windows is not a simple task. One of the most confusing elements, and yet one of the most important, is the "abort procedure." This article explains why a Windows print routine needs to have an abort procedure, and describes exactly what goes on during a print job when an abort procedure has been installed. It also provides the code for a sample abort procedure.

Under Windows, printing is similar to sending output to a window. You first obtain a handle to a device context for the printer; you can then display text or graphics on the printer using the standard Windows GDI (Graphics Device Interface) functions, such as TextOut or Ellipse. When printing, however, you also need to manage the print job by making calls to the Windows Escape function, which provides an entire family of printer services; you specify the particular service you want by passing a code as the second parameter.

The basic steps for printing under Windows are as follows:

1. Call CreateDC to obtain a handle to a device context for the printer.
2. Initiate the print job by calling Escape, passing the STARTDOC function code.
3. Display the desired text or graphics on the page by calling standard Windows GDI functions, passing the handle obtained in step 1.
4. When the page is complete, call the NEWFRAME Escape function to signal Windows to begin printing the page.
5. Repeat steps 3 and 4 for any additional pages in the document.
6. Terminate the print job by calling the ENDDOC Escape function.
7. Call DeleteDC to release the printer device context.

There is a serious problem, however, with the printing procedure just outlined. A typical Windows print job can be lengthy, during which time, Windows message processing is blocked. The ramifications of this are that: 1. The program performing the printing cannot process mouse or keyboard input messages, so there is no way for the user to signal the program to stop the print job once it has begun; and 2. other Windows programs are prevented from running. The user, therefore, cannot accomplish useful work in other applications while printing is taking place. Furthermore, the Print Manager itself is unable to run and cannot begin copying print files to the printer until the program completes the entire printing routine and returns to retrieve another message. As a result, the generation of the printed copy is delayed. Also, the GDI may run out of disk space for storing print files (which can be quite large). Because the Print Manager is not allowed to run, it cannot free disk space by deleting the print files that it has already copied to the printer.

An abort procedure is a function you define within your program. If you install an abort procedure before initiating the print job, the GDI will call it periodically while processing any subsequent NEWFRAME Escape calls.

The abort procedure given here has the form: BOOL FAR PASCAL AbortFunc (HDC HPrnDC, short Code);. The function AbortFunc represents the function name; you can choose any name you want. The HPrnDC parameter is the handle to the printer device context. The Code parameter indicates whether or not the GDI has run out of disk space for creating temporary print files. It will have one of two values: 0 if there is sufficient disk space, or SP_OUTOFDISK if the GDI has run out of disk space but more disk space could be made available by allowing the Print Manager to run. If the abort procedure returns a nonzero value, the print job will continue. If it returns 0, the print job will be cancelled.

  BOOL FAR PASCAL AbortProc (HDC HPrnDC,short Code)
       {
       MSG Msg;

       while (!UserAbort && PeekMessage (&Msg,NULL,O,O,PM_REMOVE))
            {
            TranslateMessage (&Msg);
            DispatchMessage (&Msg);
            }
       return (!UserAbort);

       } // end AbortProc

The heart of the abort procedure example is a message loop, which extracts and dispatches messages until the program's message queue is empty. To avoid blocking the print job, the procedure calls PeekMessage--which returns immediately even if no message is available--rather than GetMessage. When there are no more program messages, PeekMessage returns FALSE, which causes the abort procedure to return control to the GDI so that printing can continue.

PeekMessage is one of the Windows functions that yields control to other programs in the system. Therefore, each time the GDI calls the abort procedure during the print job, other applications, including the Print Manager, are allowed to run. The user can therefore work within other programs while printing continues in the background. Also, the Print Manager can start copying print files to the printer--and then deleting these files--while the GDI is still processing print commands, accelerating the generation of printed output and alleviating any lack of disk space. (Consequently, the abort procedure need not perform any special action if the Code parameter indicates an out-of-disk-space condition.)

Also, because the abort procedure dispatches all program messages (by calling DispatchMessage), the program can continue to receive input, allowing the user to terminate the print job by clicking the "Cancel Printing" button, or by pressing Esc.

  HWND HAbortButton;
  HANDLE HInst;
  HDC HPrnDC;
  BOOL InPrintJob = FALSE;
  FARPROC PtrAbortProc;
  BOOL UserAbort;
    .     .     .
  if (InPrintJob)
       return (NULL);
  HPrnDC = GetPrnDC ();
  ShowWindow (HAbortButton,SW_SHOW);
  UserAbort = FALSE;
  InPrintJob = TRUE;
  PtrAbortProc = MakeProcInstance (AbortProc,HInst);
  Escape (HPrnDC, SETABORTPROC, 0, (LPSTR)PtrAbortProc,NULL);
  Escape (HPrnDC, STARTDOC, 10, (LPSTR) "Print Demo", 0L);

  // Calls to GDI output functions, such as TextOut and Ellipse go here.
  Escape (HPrnDC, NEWFRAME,0,0L,0L);
  Escape (HPrnDC, ENDDOC,0,0L,0L);
  FreeProcInstance (PtrAbortProc);
  InPrintJob = FALSE;
  ShowWindow (HAbortButton,SW_HIDE);
  DeleteDC (HPrnDC);

The examples in this article assumed that printing takes place directly from the program window; you could use a similar approach to print from a modal dialog box, displaying the "Cancel Printing" button within this box and processing input messages received during printing within the dialog procedure.

To enhance the routines presented here, you could display an hourglass cursor while the mouse pointer is within the program window. To do this, simply process the WM_MOUSEMOVE message, setting the cursor to an hourglass (by calling SetCursor) only if InPrintJob is TRUE.

Copyright © 1992, Dr. Dobb's Journal