The Be Book - System Overview - The Interface Kit

BPrintJob

A BPrintJob object runs a printing session. It negotiates everything after the user's initial request to print—from engaging the Print Server to calling upon BViews to draw and spooling the results to the printer. It also handles a secondary and somewhat separate matter related to printing—configuring the page layout.

Setting Up the Page Layout

Users typically don't decide how a document fits on a page—the size of the paper, the width of the margins, the orientation of the image, and so on—each time they print. These decisions are usually made when setting up the document, perhaps from a Page Layout menu item, rather than Print.

To set up the page parameters for a document, an application should create a BPrintJob object, assign it a name, and call ConfigPage():

status_t MyDocumentManager::SetUpPage()
{
   BPrintJob job("document");
   return job.ConfigPage();
}

ConfigPage() has the Print Server interact with the user to set up the page configuration. Configuration settings are stored in a BMessage object that will be handed to the server when the document is printed. The BMessage is important to the server, but the application doesn't need to look at it directly; functions are provided to access the useful data it contains. However, you may want to get the object and store it with the document so that the configuration can be reused whenever the document is printed—and so that the user's previous choices can be the default settings when ConfigPage() is called again. This is good behavior for an application to follow, and is highly recommended.

Settings() returns the page configuration the user set up; SetSettings() initializes the configuration that's presented to the user. For example:

BMessage *setup;
. . .
status_t MyDocumentManager::SetUpPage() {
   status_t result;
   BPrintJob job("document's name");

   if (setup) {
      job.SetSettings(new BMessage(*setup));
   }

   result = job.ConfigPage();

   if (result == B_OK) {
      setup = job.Settings();

      /* record the settings for your own use */
      paper_rect = job.PaperRect();
      printable_rect = job.PrintableRect();
   }

   return result;
}

In this example, the setup BMessage presumably is flattened and saved with the document whenever the document is saved, and unflattened whenever the document is open and the page settings are needed.

Printing

To print a document, an application must go through several ordered steps:

Engaging the Print Server and setting parameters for the job.
Setting up a spool file to hold image data.
Asking BViews to draw each page.
After each page is drawn, putting the data for the page in the spool file.
Committing the spool file to the Print Server.

A BPrintJob object has member functions that assist with each step.

Setting Up a Print Job

A print job begins when the user requests the application to print something. In response, the application should create a BPrintJob object, assign the job a name, and call ConfigJob() to initialize the printing environment. For example:

BMessage *setup;
. . .
status_t MyDocumentManager::Print()
{
   BPrintJob job("document");
   status_t err;

   if ( setup )
      job.SetSettings(new BMessage(*setup));
   if ( (err = job.ConfigJob()) == B_OK ) {
      delete setup;
      setup = job.Settings();
   }
   . . .
}

So far, this looks much like the code for configuring the page presented in the previous "Setting Up the Page Layout" section. The idea is the same. ConfigJob() gets the Print Server ready for a new printing session and has it interact with the user to set up the parameters for the job—which pages, how many copies, and so on. It uses the same settings BMessage to record the user's choices as ConfigPage() did, though it records information that's more immediate to the particular printing session.

Again, you may want to store the user's choices with the document so that they can be used to set the initial configuration for the job when the document is next printed. By calling Settings(), you can get the job configuration the user set up; SetSettings() initializes the configuration that's presented to the user.

Information about the page layout will be required while printing. If that information isn't available in the Settings() BMessage, ConfigJob() will begin, in essence, by calling ConfigPage() so that the server can ask the user to supply it.

To discover which pages the user wants to print, you can call the FirstPage() and LastPage() functions after ConfigJob() returns:

int32 pageCount = job.LastPage() - job.FirstPage() + 1;

The Spool File

The next step after configuring the job is to call BeginJob() to set up a spool file and begin the production of pages. After all the pages are produced, CommitJob() is called to commit them to the printer.

job.BeginJob();
/* draw pages here*/
job.CommitJob();

BeginJob() and CommitJob() bracket all the drawing that's done during the job.

Cancellation

A number of things can happen to derail a print job after it has started—most significantly, the user can cancel it at any time. To be sure that the job hasn't been canceled or something else hasn't happened to defeat it, you can call CanContinue() at critical junctures in your code. This function will tell you whether it's sensible to continue with the job. In the following example, a while loop is used to loop through all the pages in the document, or until CanContinue() returns false, indicating that the job has been canceled:

job.BeginJob();
while (job.CanContinue() && page <= pageCount) {
   /* draw each page here*/
   page++;
}
job.CommitJob();

Drawing on the Page

A page is produced by asking one or more BViews to draw within a rectangle that can be mapped to a sheet of paper (excluding the margins at the edge of the paper). DrawView() requests one BView to draw some portion of its data and specifies where the data should appear on the page. You can call DrawView() any number of times for a single page to ask any number of BViews to contribute to the page. After all views have drawn, SpoolPage() spools the data to the file that will eventually be committed to the printer. SpoolPage() is called just once for each page. For example:

for (int i = job.FirstPage();
job.CanContinue() && i <= job.LastPage();
i++) {
   . . .
   job.DrawView(someView, viewRect, pointOnPage);
   job.DrawView(anotherView, anotherRect, differentPoint);
   . . .
   job.SpoolPage();
}

DrawView() calls the BView's Draw() function. That function must be prepared to draw either for the screen or on the printed page. It can test the destination of its output by calling the Draw() IsPrinting() function.

Note

Don't use the BView::Bounds() function to determine the area to render. Instead, use the update rectangle passed to the BView::Draw() function.

A Complete Printing Function

This function puts together all the above code snippets and handles the printing of a document (minus the actual drawing and visual status information presented to the user as printing goes on).

status_t MyDocumentManager::Print() {
   status_t result = B_OK;
   BPrintJob job("document's name");

   // If we have no setup message, we should call ConfigPage()
   // You must use the same instance of the BPrintJob object
   // (you can't call the previous "PageSetup()" function, since it
   // creates its own BPrintJob object).

   if (!setup) {
      result = job.ConfigPage();
      if (result == B_OK) {
         // Get the user Settings
         setup = job.Settings();

         // Use the new settings for your internal use
         paper_rect = job.PaperRect();
         printable_rect = job.PrintableRect();
      }
   }

   if (result == B_OK) {
      // Setup the driver with user settings
      job.SetSettings(setup);

      result = job.ConfigJob();
      if (result == B_OK) {
         // WARNING: here, setup CANNOT be NULL.
         if (setup == NULL) {
            // something's wrong, handle the error and bail out
         }
         delete setup;

         // Get the user Settings
         setup = job.Settings();

         // Use the new settings for your internal use
         // They may have changed since the last time you read it
         paper_rect = job.PaperRect();
         printable_rect = job.PrintableRect();

         // Now you have to calculate the number of pages
         // (note: page are zero-based)
         int32 firstPage = job.FirstPage();
         int32 lastPage = job.LastPage();

         // Verify the range is correct
         // 0 ... LONG_MAX -> Print all the document
         // n ... LONG_MAX -> Print from page n to the end
         // n ... m -> Print from page n to page m

         if (lastPage > your_document_last_page)
            last_page = your_document_last_page;

         int32 nbPages = lastPage - firstPage + 1;

         // Verify the range is correct
         if (nbPages <= 0)
            return B_ERROR;

         // Now you can print the page
         job.BeginJob();

         // Print all pages
         bool can_continue = job.CanContinue();

         for (int i=firstPage ; can_continue && i<=lastPage ; i++) {
            // Draw all the needed views
            job.DrawView(someView, viewRect, pointOnPage);
            job.DrawView(anotherView, anotherRect, differentPoint);

            // If the document have a lot of pages, you can update
               a BStatusBar, here
            // or else what you want...
            update_status_bar(i-firstPage, nbPages);

            // Spool the page
            job.SpoolPage();

            // Cancel the job if needed.
            // You can for exemple verify if the user pressed the
            // ESC key or (SHIFT + '.')...
            if (user_has_canceled)
            {
               // tell the print_server to cancel the printjob
               job.CancelJob();
               can_continue = false;
               break;
            }

            // Verify that there was no error (disk full for example)
            can_continue = job.CanContinue();
         }

         // Now, you just have to commit the job!
         if (can_continue)
            job.CommitJob();
         else
            result = B_ERROR;
      }
   }

   return result;
}

Drawing Coordinates

When a BView draws for the printer, it draws within the printable rectangle of a page—a rectangle that matches the size of a sheet of paper minus the unprinted margin around the paper's edge. The PaperRect() function returns a rectangle that measures a sheet of paper and PrintableRect() returns the printable rectangle, as illustrated in this diagram.

Both rectangles are stated in a coordinate system that has its origin at the left top corner of the page. Thus, the left and top sides of the rectangle returned by PaperRect() are always 0.0. PrintableRect() locates the printable rectangle on the paper rectangle. However, DrawView() assumes coordinates that are local to the printable rectangle—that is, an origin at the left top corner of the printable rectangle rather than the paper rectangle.

The diagram below shows the left top coordinates of the printable rectangle as PrintableRect() would report them and as DrawView() would assume them, given a half-inch margin.

Draw() always draws in the BView's own coordinate system. Those coordinates are mapped to locations in the printable rectangle as specified by the arguments passed to DrawView().