The Interface Kit: BPrintJob

Derived from: public BObject

Declared in: <interface/PrintJob.h>


Overview

A BPrintJob object runs a printing session. It negotiates everything after the user's initial request to print--from engaging the Print Server to formatting pages, calling upon BViews to draw, and spooling the results to the printer.

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 InitJob() to initialize the printing environment. For example:

   void MyDocumentManager::Print()
   {
       BPrintJob *job = new BPrintJob("document");
       if ( job->InitJob() < B_NO_ERROR )
           goto end;
       else {
           . . .
       }
       . . .
   end:
       delete job;
       return;
   }

InitJob() has the Print Server interact with the user to set up the parameters for the job --the number of copies, the size of the paper, scaling, orientation on the page, and so on.

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 Config(), you can get the job configuration the user set up; SetConfig() initializes the configuration that's presented to the user. For example:

   BMessage *configuration;
   . . .
   void MyDocumentManager::Print()
   {
       BPrintJob *job = new BPrintJob("document");
       if ( configuration )
           job->SetConfig(configuration);
       if ( job->InitJob() < B_NO_ERROR )
           goto end;
       if ( job->CanContinue() ) {
           if ( configuration )
               delete configuration;
           configuration = job->Config();
       }
       else
           goto end;
       . . .
   }

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, as illustrated above. This function will tell you whether it's sensible to continue with the job.

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

   job->BeginPrinting();
   /* draw pages here */
   job->Commit();

BeginPrinting() and Commit() bracket all the drawing that's done during the job.

Each page is produced by asking one or more BViews to draw within the page's printable rectangle (the rectangle that excludes the unprinted margin around the edge of the paper). 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, the page is spooled to the file that will eventually be committed to the printer. For example:

   for ( . . . ) {
       if ( job->CanContinue() ) {
           job->DrawView(someView, viewRect, pointOnPage);
           job->DrawView(anotherView, anotherRect, differentPoint);
           . . .
           job->SpoolPage();
       }
       else
           goto end;
   }

DrawView() calls the BView's Draw() function. That function can test whether it's drawing on the screen or on the printed page by calling the BView IsPrinting() function. SpoolPage() is called just once for each page.

< This is the first release of the printing API; it will be enhanced in future releases to provide greater control over printing parameters. >

See also: BView::IsPrinting()


Constructor and Destructor


BPrintJob()

      BPrintJob(char *name)

Initializes the BPrintJob object and assigns the job a name . The Print Server isn't contacted until InitJob() is called. The spool file isn't created until BeginPrinting() starts the production of pages.

See also: InitJob(), BeginPrinting()


~BPrintJob()

      virtual ~BPrintJob(void)

Frees all memory allocated by the object.


Member Functions


BeginPrinting()

      void BeginPrinting(void)

Opens a spool file for the job and prepares for the production of a series of pages. Call this function only once per printing session--just after initializing the job and just before drawing the first page.

See also: Commit()


CancelJob()

      void CancelJob(void)

Cancels the print job programmatically and gets rid of the spool file. The job cannot be restarted; you must delete the BPrintJob object. Create a new object to renew printing.


CanContinue()

      bool CanContinue(void)

Returns TRUE if there's no impediment to continuing with the print job, and FALSE if the user has canceled the job, the spool file has grown too big, or something else has happened to terminate printing. It's a good idea to liberally sprinkle CanContinue() queries throughout your printing code to make sure that the work you're about to do won't be wasted.


Commit()

      void Commit(void)

Commits all spooled pages to the printer. This ends the print job; when Commit() returns, the BPrintJob object can be deleted. Commit() can be called only once per job.

See also: BeginPrinting()


Config() see SetConfig()


DrawView(), SpoolPage()

      virtual void DrawView(BView *view, BRect rect, BPoint point)
      void SpoolPage(void)

DrawView() calls upon a view to draw the rect portion of its display at point on the page. The view's Draw() function will be called with rect passed as the update rectangle. The rectangle should be stated in the BView's coordinate system and it should be fashioned so that the view draws only in the page's printable rectangle. The point should be stated in a coordinate system that has the origin at the top left corner of the printable rectangle.

The view must be attached to a window; that is, it must be known to the Application Server. However, when printing, a BView can be asked to draw portions of its display that are not visible on-screen. Its drawing is not limited by the clipping region, its bounds rectangle, or the frame rectangles of ancestor views.

DrawView() doesn't look down the view hierarchy; it asks only the named view to draw, not any of its children. However, any number of BViews can draw on a page if they are subjects of separate DrawView() calls.

After all views have drawn and the page is complete, SpoolPage() adds it to the spool file. SpoolPage() must be called once to terminate each page.

See also: PrintableRect() , BView::Draw()


FirstPage(), LastPage()

      long FirstPage(void)
      long LastPage(void)

< These functions both currently return 0. >


InitJob()

      long InitJob(void)

Engages the Print Server and initializes the job. If SetConfig() has been called to establish a recommended configuration for the job, this function will pass it to the Print Server so the Server can present it to the user. Otherwise, a default configuration will be used.

InitJob() returns B_ERROR if it has trouble communicating with the Server or if the job can't be established for any other reason. It returns B_NO_ERROR if all goes well.

See also: SetConfig()


LastPage() see FirstPage()


PaperRect(), PrintableRect()

      BRect PaperRect(void)
      BRect PrintableRect(void)

These functions return rectangles that describe the size of a printed page

PaperRect() returns a rectangle that records the presumed size of the paper that the printer will use. It has 0.0 as its left and top coordinate values, and right and bottom coordinates that reflect the size of a sheet of paper. The size depends on choices made by the user when setting up the print job.

PrintableRect() returns a rectangle that encloses the portion of a page where printing can appear. It's stated in the same coordinate system as the rectangle returned by PaperRect(), but excludes the margins around the edge of the paper. When drawing on the printed page, the left top corner of this rectangle is taken to be the coordinate origin, (0.0, 0.0).

The diagram below illustrates the paper and printable rectangles, along with a closer view showing the coordinates of the left top corner of the printable rectangle as PrintableRect() would report them and as DrawView() would assume them, given a half-inch margin.

See also: DrawView()


SetConfig(), Config()

      void SetConfig(BMessage *configuration)
      BMessage *Config(void)

These functions set and return the group of parameters that configure the Print Server for the current job. The parameters are recorded in a BMessage object that can be regarded as a black box; the entries in the message are interpreted by the Print Server and will be documented when the Server and the print driver API are documented.

Config() can be called to get the current configuration message, which can then be flattened and stored with the document. You can retrieve it later and pass it to SetConfig() to set initial configuration values the next time the document is printed, as illustrated in the Overview.

See also: InitJob()


SpoolPage() see DrawView()






The Be Book, HTML Edition, for Developer Release 8 of the Be Operating System.

Copyright © 1996 Be, Inc. All rights reserved.

Be, the Be logo, BeBox, BeOS, BeWare, and GeekPort are trademarks of Be, Inc.

Last modified September 6, 1996.